Transaction types

Every type goes in body.type; the other body fields are listed per type. Amounts are strings of base units (6 decimals). Tokens are USDC (the network dollar), MLX, and USDT (older balances only).

Rules marked door are checked by POST /api/tx before the transaction is stored (an HTTP error, nothing recorded). The rest are checked in the block: a transaction that breaks them is recorded with status: "failed" and its error, changes nothing and doesn't use its nonce. Every user transaction also has to pass the common checks on Submitting.

#Account

#create_account

Creates the wallet named in from and records pk as its key.

• from is the new name, nonce is 0. door
• The name matches NAME_RE in lib/chain/types.ts (^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?\.mlx$: lowercase letters, digits and hyphens, starting and ending with a letter or digit) and is not reserved (rewards, treasury, bridge, sequencer and the other protocol names) or a look-alike of one (treasury1, mlx-support). door
• pk is a valid Ed25519 key that is not of small order. door
• The name isn't taken, and pk doesn't already control another wallet.
• referrer names an existing wallet that isn't a protocol account or the wallet itself; otherwise "An invite is needed to create a wallet…". door (Before 29 Oct 2026 16:30 UTC it was optional, and an unknown one was ignored.)

#Money

#transfer

Moves a token from the signing wallet to another wallet.

• to exists and isn't the sender ("You can't send to yourself").
• Protocol accounts can't receive transfers, except treasury.mlx.
• Only unlocked MLX moves. Locks whose date has passed are released first; MLX still locked can't be sent ("That MLX is still locked…").
• The sender holds the amount ("luca.mlx has insufficient USDC").

#swap

Buys MLX with dollars, or sells MLX for USDC, at the protocol's spot price on the emission curve (the buy premium and sell discount apply; the live spread is in GET /api/stats, market).

• Get a quote, and the minOut to sign, from GET /api/market/quote?side=buy|sell&amount=<base units>. See Market and the curve.
• Below the smallest buy or sale the swap fails ("The smallest buy is …", "The smallest sale is …").
• A buy fails if the treasury can't deliver that much MLX; a sale fails if treasury.mlx lacks the USDC ("Sell liquidity is low right now…").
• Only unlocked MLX can be sold.
• If the result would be below minOut: "The price moved beyond your limit. Try again."
• MLX bought on the spot market is never locked.

#withdraw

Takes USDC out of MLX Network. The amount (plus any fee) moves into the escrow account withdrawals.mlx at once; a withdraw_settle system transaction later records the payout or refunds it.

• Solana: address is a Solana wallet address (base58). A USDC token account's address is refused ("That's a token account's address…"). door The network fee is 0.5 USDC, taken with the amount ("You need … including the … network fee").
• A refund (rejected) returns the amount and the fee.

#Compute API

#api_fund

Adds API credit: USDC from the wallet into the protocol account api.mlx, held for the wallet's Compute API requests.

#api_refund

Gives API credit back to the wallet's USDC.

POST /api/tx also refuses (409, with the amount you can take back) a refund of credit that pays for requests since the last daily bill or for requests running now. door

#Seats

#buy_node

Buys a dedicated seat from the wallet's balance. (Seats paid with crypto at checkout arrive as the system transaction mint_node instead.)

• tier is a known seat id ("Unknown seat size").
• With USDC/USDT (or no pay), one coin has to cover the whole price ("A Core seat costs … USDC or USDT…").
• With WALLET: USDC first, then USDT, then just enough unlocked MLX sold at the spot sell price. The MLX goes to treasury.mlx and its dollars straight into the seat. Without maxMlx, or if more MLX would be needed: the transaction fails. The record's sold shows what was sold.
• The price goes to treasury.mlx; the seat gets the next seat number and appears in account.nodes.

#transfer_seat

Gives a dedicated seat the signing wallet holds to another wallet. Seats are freely transferable; a transfer is not a sale, so nothing is paid on the ledger and no distributor commission is created or reversed.

{ "type": "transfer_seat", "id": 12, "to": "luca.mlx" }

• id is a positive whole number ("Seat number must be a positive whole number") and to a wallet name ("Send a seat to a wallet name like luca.mlx"); no other fields. door
• The seat exists ("There's no seat #12") and the sender holds it ("You don't hold seat #12"). door
• to isn't the sender ("You can't send a seat to yourself"), exists ("x.mlx does not exist") and is a user wallet ("x.mlx is a protocol account and can't hold a seat"). door
• Dedicated seats aren't offered to US persons, so the recipient must have confirmed it isn't a US person. Otherwise 409 "x.mlx can't receive a dedicated seat: only wallets that confirmed they aren't a US person can hold one.". The sender has nothing to confirm. door
• The seat leaves the sender's account.nodes and joins the recipient's. Its record keeps its number, tier, purchase, payment and lock-in; owner becomes the recipient, buyer names the wallet that bought (or was granted) it, and transfers lists its latest changes of holder (from, to, tx, height, ts).
• From the next hour the seat mines for the recipient: it is carried by one of the recipient's Macs, and both wallets' lock-in for newly mined MLX follows the seats each now holds (see Seats and Lock-ins). MLX already mined and locked stays with the wallet that earned it.
• The effect is { "kind": "seat", "from", "to", "node", "tier" }.

#Devices

#bind_device

Links a Mac (or iPhone/iPad) to the wallet, so its work earns for this wallet. The Mac's own Secure Enclave key signs a link request; the wallet puts that request on the ledger.

• proof signs SHA-256 of canonical({ type: "mlx-device-link", chain, account, device, name, chip, memoryGB, os, ts }) (linkMessage in lib/chain/device.ts; a missing chip/os is "" and a missing memoryGB is 0), where account is this wallet's name or * for an open request any wallet may take ("The device didn't sign this link request").
• ts is close to the transaction's own ts ("That link request has expired…").
• A request works once, and must be newer than the Mac's current link ("…was already used", "…older than this Mac's current link").
• A Mac linked to another wallet moves to this one.
• A wallet links up to 32 devices.

How MLX Node builds and shows the request: Links.

#unbind_device

Unlinks a device from the wallet.

• The device is linked to this wallet ("That device isn't linked to this wallet").

#System transactions

Signed by the sequencer (from: "sequencer", nonce: 0, the sequencer's pk). Any other signer fails. Each is idempotent: a second one for the same payment, hour, payout or grant fails ("…already credited", "That hour was already paid").

Each system transaction shows on the explorer with its effects and notes, and its balances are in the next state commitment.