API reference

A transistor-level MOS 6502 over HTTP, one half-cycle at a time.

Nothing behind this API models 6502 behaviour. Every request settles a network of 3510 transistors and 1725 nodes, the same engine the visual explorer runs, verified bit-exact against the original visual6502 simulation. Every register in every response is read back out of its own storage nodes on the die; every cycle count is emergent.

The server is stateless. Each request carries the whole machine in a Machine object: the chip's four state bitsets (about 2 KB of hex) plus a sparse 64 KiB memory. Each response carries the whole machine back. Your copy of that object is the session. Save it to a file, diff two of them, or hand one to somebody else mid-instruction; any server instance can pick any of them up. Resuming from a serialized machine is proven bit-exact over every node at every half-cycle.

Three requests

Assemble, boot, step

# 1. Boot a program. The source is assembled, laid into memory at its
#    .org, the reset vector aimed at it, and the chip power-cycled through
#    its real reset sequence. The machine comes back standing at its first
#    opcode fetch.
curl -s https://6502.tinymachines.ai/api/v1/boot -H 'content-type: application/json' -d '{
  "rom": { "source": "        .org $0200\nstart:  LDA #$2E\n        STA $80\n        LDA #$14\n        STA $81\nsum:    CLC\n        LDA $80\n        ADC $81\n        STA $82\n        JMP start" }
}' > m0.json

# 2. Step 41 half-cycles, tracing every one and watching two named wires.
python3 -c 'import json; m = json.load(open("m0.json"));
print(json.dumps({"machine": m["machine"], "half_cycles": 41,
                  "trace": True, "watch": ["sync", "sb0"]}))' |
  curl -s https://6502.tinymachines.ai/api/v1/step -H 'content-type: application/json' -d @- > m1.json

# 3. Read the answer out of the silicon: A holds $42 (0x42 = 66), and
#    $2E + $14 = $42 sits in memory at $0082.
python3 -c 'import json; r = json.load(open("m1.json"));
print(hex(r["observe"]["a"]), r["observe"]["flags"]);
print(bytes.fromhex(r["machine"]["memory"]["pages"]["00"])[0x82])'

To keep going, POST m1.json's machine back to /v1/step. Stepping 20 and then 21 half-cycles across two requests is byte-identical to stepping 41 in one; the test suite pins it.

Endpoints

Six routes that run the chip

The atlas

Seven routes that ask what a wire is part of

/v1/nodes above answers what can I watch, and its grouping is a reading of the names. These five answer what is this node part of, and every answer is measured. Twenty-three kinds of machinery are walked out of the switch network itself: the ALU as eight bit slices with its inputs and carry ends, the status register as one container per flag, the four registers as their storage closures plus the lines that move each, the timing chain as the cells that compute each T-state, the decimal correction as everything its names are wired into. The derivation is web/chip-groups.js, the same module the tracer and the chip map draw with, so the API and the drawings cannot disagree.

Two layers, and the difference is the point. The partition is 132 groups with every one of the 1547 nodes in exactly one, because a drawing needs disjoint boxes and ownership goes to the most specific claim. The containers are the same derivations unfiltered: 135 of them, overlapping, with 88 nodes in more than one and three (sdp:sd1, sdp:sd2, sbus:link) that exist only there, absorbed whole by a container that outranks them. Asking which group a node is in and getting one answer is a fact about the drawing, not about the chip.

Nothing here runs the chip and none of it changes, so every response is served public, max-age=86400.

Cartridges

A ROM, its tiles, and the contract they were written to

There is no video hardware on this die and no interrupt in use, so a frame is not something the silicon knows about. It is an agreement between a ROM and whatever drives it, and that agreement is the whole console:

The ROM busy-waits on that flag, which is the only way to synchronise with the outside world when you have no interrupt and no timer. It works over HTTP because the API is stateless: the frame boundary is a memory edit between two /v1/step calls, and the whole machine travels in each one. Nothing about this was designed for games. It falls out of a design that carries the machine as a value.

The memory map

None of these are facts about the silicon. They are addresses two programs agree on, which is why they are published rather than left to be inferred from a game that already works.

A ROM that reaches its own screen is overwritten by the picture it draws, and it assembles and boots first, so nothing errors: Die Runner grew past $0400 when its scenery arrived and drew unrelated memory for a while. That is a refusal here rather than a game that runs and is wrong.

Tiles

8x8 pixels, two bits a pixel, sixteen bytes a tile: the NES shape, because it is what every old-school sprite tool emits and because four colours a tile is the constraint that makes the art look like the era rather than like a photograph.

bytes 0..7    bit 0 of each pixel, one byte a row, MSB the leftmost pixel
bytes 8..15   bit 1 of each pixel
colour        (plane1 << 1) | plane0   ->  0..3

The palette is the die's own, the four colours the exploded view paints the mask layers in: #0B1120 substrate, #3E93A6 diffusion, #E0A24B polysilicon, #4FBFD4 metal. Colour 0 is drawn, not skipped, because this is a tiled screen and not a sprite layer.

Art arrives in either of two forms and leaves in both. chr is the binary format above as hex, which is what a converter emits. pixels is eight strings of eight '0'..'3' a tile, which is the form something writing a cartridge from text can actually emit. Whichever arrives, both are written into the file, so a reader never has to decode and a drawing tool never has to parse ASCII.

"pixels": [["00333300",
            "03222230",
            "32000023",
            "32033023",
            "32033023",
            "32000023",
            "03222230",
            "00333300"]]     // one tile: a capacitor

The file

One gzipped JSON document, and it carries the contract with the ROM rather than beside it, because the contract is the part an outside author has to agree with and a contract in a different file from the bytes it governs is the copy that drifts.

{
  "format": "tinymachines.cartridge", "version": 1,
  "encoding": { /* how to read every field, in the file */ },
  "contract": { /* what each console address is for */ },
  "meta":    { name, author, blurb, minted },
  "rom":     { org, end, size, reset, bytes, labels, source },
  "console": { tick, input, screen, width, height, ... },
  "tiles":   { count, chr, pixels, palette },
  "verify":  { /* what the chip did when this was minted */ },
  "notes":   [ /* what is worth saying and is not fatal */ ]
}

The source travels too, so a cartridge can be read, edited and minted again by whoever has the file. Gzip mtime is zero, so minting the same cartridge twice gives the same bytes: a container that changes every time it is written cannot be diffed, and diffing two cartridges is how a person sees what an edit did.

# Mint one, then play it.
curl -s https://6502.tinymachines.ai/api/v1/console | python3 -m json.tool

curl -s https://6502.tinymachines.ai/api/v1/cartridge -H 'content-type: application/json' \
  -d @cartridge.json -o mine.cart.gz

# games.tinymachines.ai loads one from ?cart=<url> or from its file picker.
python3 -c 'import gzip,json,sys; print(json.load(gzip.open("mine.cart.gz"))["verify"])'

MCP

Five tools, each one a whole errand

POST /api/mcp speaks the Model Context Protocol over streamable HTTP: initialize, tools/list, tools/call. No session id is issued and no SSE stream is opened, for the same reason the API keeps no sessions. A GET returns 405, which is the spec's own answer for a server that offers no stream.

The tools are coarse where the HTTP routes are fine-grained, and that is the design rather than a shortcut. The API is stateless because a program holds the machine: 2 KB of hex travels out and back, and the client's copy is the session. An MCP client is a language model, and a model cannot usefully hold 2 KB of hex. Pasting a machine into the next tool call would spend most of a context window carrying a value it cannot read. So run assembles, boots, steps and reports in one call, and the machine never leaves the server.

run renders the screen as two hex characters a cell, row major, and that is the one thing that turns writing a 6502 game from guessing into working: an assembler says the bytes are legal, and only the picture says the program is right. Give it frames and a controller byte to hold down, and it hands back what your ROM drew.

Give run exactly one of half_cycles, until_pc (a breakpoint at an opcode fetch) or frames. Addresses are hex with or without a $, because a model writes $0500 and a program writes 1280 and neither should have to learn the other's spelling.

# Hand-driving it: initialize, then call a tool.
curl -s https://6502.tinymachines.ai/api/mcp -H 'content-type: application/json' -d '{
  "jsonrpc":"2.0","id":1,"method":"initialize",
  "params":{"protocolVersion":"2025-06-18","capabilities":{},
            "clientInfo":{"name":"curl","version":"0"}}}'

curl -s https://6502.tinymachines.ai/api/mcp -H 'content-type: application/json' -d '{
  "jsonrpc":"2.0","id":2,"method":"tools/call",
  "params":{"name":"run","arguments":{
      "source":".org $0200\nstart LDA #$2E\n      CLC\n      ADC #$14\n      STA $82\n      JMP start",
      "half_cycles":41, "read":["0082"], "watch":["sync"]}}}'

A tool that refuses comes back as a normal result with isError set and the reason in the text, never as a JSON-RPC error: the model has to be able to read why and try again, and a protocol error is for the client rather than for the model.

Objects

The shapes that travel

Machine

The unit of statelessness: {"state": ChipState, "memory": SparseMemory}. POST it back to continue exactly where the last response left off.

ChipState

A blob of the wrong length, a non-hex character, or a set bit in the padding past the last node is refused (422 at the model boundary, 400 at the engine): a state that decodes to the wrong chip is worse than one that is rejected.

SparseMemory

64 KiB as {"fill": "00", "pages": {"02": "<512 hex chars>"}}: a background byte plus only the 256-byte pages that differ from it. Keys are the page number in hex ("00".."ff", so page "02" starts at $0200). Responses are canonical: a page that is all fill is dropped, because "fill everywhere except the listed pages" is the entire meaning. Set fill to "ea" and an empty machine executes NOPs.

Rom

A program as source, not bytes: {"source": "...", "org": 512} (org optional, default $0200, and a .org directive in the source wins). Labels, forward references, .byte/.word data and comments are the assembler's; the programs page shows the dialect.

AssembleResponse

Observation

What a learner reads off the chip at one instant. All of it is read out of the silicon; none of it is modelled.

StepResponse

Encodings

The bits on the wire

A bitset is lowercase hex of its bytes: bit i of the set is byte i/8, LSB first within the byte. Node numbering is visual6502's own, so node 0 is bit 0 of byte 0. The node sets (1725 bits) pack to 216 bytes, 432 hex chars; the transistor set (3510 bits) to 439 bytes, 878 chars. The same convention the simulator's halfshot export uses.

Memory pages are 256 bytes as 512 hex chars, plain byte order. All hex is accepted case-insensitively and returned lowercase.

The rows trace

With format: "rows", trace_rows carries {cols, watch_names, watch_encoding, rows}: one row per half-cycle, columns named by cols. Encodings, stated: clk0 and sync are 0/1; phase is 1 or 2; rw is 0 read, 1 write; tstates is a bitmask, bit n for Tn (bit 1 meaning the T+/T1x state); hidden is 0 none, 1 T1, 2 VEC0, 3 T6; store_data is 0 none, 1 SD1, 2 SD2; a fetch that has not happened is addr -1, opcode -1. The flags string is dropped because it derives from p.

watch is a lowercase hex bitset over watch_names, the same convention as the state blobs (bit i in byte i/8, LSB first), fixed width of ceil(names/8) bytes, an empty string with no watches; watch_encoding: "hex" says so on the wire. Hex and not an integer because a JSON number is a float64 to every browser: past 53 names an integer mask silently corrupts with no error anywhere, which a consumer watching 64 names found. A reader that can decode the state blobs decodes watch with the same three lines.

Responses are gzipped when the client accepts it, which shrinks both trace forms by an order of magnitude and narrows the gap between them: repeated key names compress to almost nothing.

Errors

Refusals, never guesses

CORS is open (Access-Control-Allow-Origin: *), on purpose: the server holds no user state and no credentials, so a notebook, a classroom page, or a CodePen can POST a machine here from any origin and risk nothing.

What to run first

The result that is in no register

Boot the add program from the quick start and step 45 half-cycles with trace on, watching dpc17_SUMS (the adder's sum select) and dpc23_SBAC (special bus into A: the writeback). The trace shows two different kinds of control line at once, measured on this exact run: SUMS is high in all 45 half-cycles, because the adder sums continuously whether or not the instruction wants it, while SBAC pulses exactly where A loads, once per instruction that writes it.

The pulse at h=38 is the one to stare at. ADC's own cycles are over: sync was high at h=36 for the next instruction's fetch, IR already holds STA's opcode, and A still reads $2E. The sum exists and is in no register, and the observation shows the whole mechanism: at h=36 the operands sit in the adder's input latches (alua $2E, alub $14), at h=37 the alu and sb fields both read $42 while a reads $2E and idl already holds the next opcode. One half-cycle into STA, SBAC fires and A snaps to $42. The pulse at h=30 is the same overlap happening to the LDA before it. Every behavioural emulator hides this; it falls out of this one because nothing here knows what ADC is supposed to do.

Behind the API

What answers a request

A pool of warm engine processes (halfwave, Rust, zero dependencies), each holding the parsed netlist and one constructed machine. A request overwrites the machine's entire state with yours, settles the network the requested number of half-cycles, and hands the state back; nothing survives between requests. One warm instance runs about 28,000 half-cycles a second, which is a simulated 6502 at roughly 14 kHz: three orders of magnitude slower than the real part, and exactly as fast as a learning tool needs to be.

Swagger UI and ReDoc are generated from the same Pydantic models that validate every request, so they cannot drift from the behaviour.