Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
Inference settlement receipts (three-inference-receipt/v1)
The wire format that ties an x402 payment for inference work to the exact job
and response it paid for (Roadmap phase 4). When a paid inference call on
/api/x402/llm-proxy settles, the response body
carries an inferenceReceipt object. Anyone holding the receipt can prove,
offline and from first principles, that a specific payment on a specific
network bought a specific metered job with a specific signed response. A node
operator uses the same receipt to prove they were paid for exactly the work
they performed.
- Spec id:
three-inference-receipt/v1(receipt),three-inference-response/v1(metered job) - Status: live on
/api/x402/llm-proxybehindINFERENCE_SIGNING_KEY(unset disables signing and receipt issuance; the rollback toggle). - Reference implementation:
api/_lib/inference-settlement.js - Persistence:
inference_jobstable,api/_lib/migrations/20260812000000_inference_jobs.sql - Verifiers:
POST /api/x402/inference-verify(free, HTTP) andscripts/inference-receipt-verify.mjs(offline CLI) - Relationship to OIN: OPEN_INFERENCE_PROTOCOL.md signs GPU worker job envelopes; this spec settles LLM inference over the x402 payment rail. Same ed25519 primitive, different artifact.
Design goals
- Payment bound to work, not to a timestamp. The receipt commits to the sha256 of the exact prompt and the exact completion, the provider-reported token counts, the settlement transaction, the amount, the asset, the payer and the payTo. Changing any one byte of any committed field invalidates a signature.
- Two attributable identities. The response signature answers "which node stands behind this output"; the receipt signature answers "which issuer vouches that this payment covered this job". They can be the same key (default) or distinct operator-controlled keys.
- Verify without trusting us. Both signatures are ed25519 over domain-tagged canonical JSON, verifiable with any RFC 8032 implementation. The on-chain leg (settlement confirmation) is optional and read-only.
- No real funds in proof runs. The test lane settles on Solana devnet
(
solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1), which the platform's self-hosted facilitator already routes. Mainnet activation is a documented, owner-gated step (see "Activation" below).
Canonical encoding
Identical construction to the 3D provenance credentials (PROVENANCE_3D.md): JSON with object keys sorted recursively, no whitespace, UTF-8. All digests are SHA-256 over canonical bytes, hex-encoded lowercase. Signatures are ed25519 (RFC 8032) over
TAG || canonical_bytes
where TAG is a versioned domain-separation string so a signature from any
other three.ws signing scheme can never replay as an inference artifact:
| Artifact | Tag |
|---|---|
| Metered job | three-inference-response/v1\n |
| Receipt | three-inference-receipt/v1\n |
Signatures and public keys are base58 (Solana encoding), so an operator's existing Solana keypair doubles as a signing identity.
The metered job (three-inference-response/v1)
Produced by the node immediately after inference, before settlement. Lives on
the paid response body as metering and inside the receipt as job.
{
"type": "three-inference-response/v1",
"jobId": "9b2f…", // uuid, one per paid request
"route": "/api/x402/llm-proxy",
"model": "llama-3.3-70b-versatile", // concrete model that produced the output
"provider": "groq", // provider lane that ran it
"promptSha256": "a1b2…", // sha256 hex of the raw prompt string
"responseSha256": "c3d4…", // sha256 hex of the raw completion text
"inputTokens": 5, // provider-reported prompt tokens
"outputTokens": 6, // provider-reported completion tokens
"tokensUsed": 11, // inputTokens + outputTokens
"latencyMs": 312 // optional, measured wall-clock
}
The prompt and completion themselves never appear in the receipt: only their hashes. A verifier who holds the raw text re-derives the hashes; a verifier who does not can still check both signatures and the on-chain settlement.
The receipt (three-inference-receipt/v1)
Issued after the x402 settlement lands, attached to the paid response body as
inferenceReceipt, and persisted server-side in inference_jobs.
{
"receiptType": "three-inference-receipt/v1",
"issuedAt": "2026-08-12T00:00:00.000Z",
"job": { /* the metered job above, verbatim */ },
"responseSignature": "4xY…", // ed25519 by responseSigner over the job core
"responseSigner": "NodePub…", // base58 node key (INFERENCE_SIGNING_KEY)
"payment": {
"network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", // CAIP-2
"payer": "BuyerWallet…",
"payTo": "OperatorWallet…",
"amountAtomics": "5000", // decimal string, 6-decimal USDC atomics
"asset": "EPjFWdd5…", // settlement mint / contract
"transaction": "5KtR…" // settlement tx signature / hash
},
"signer": "IssuerPub…", // base58 receipt issuer (INFERENCE_RECEIPT_SIGNING_KEY)
"signature": "3wQm…" // ed25519 by signer over everything above
}
The receipt signature covers the entire object except signature itself.
payTo is the wallet that received the settlement: for platform-run
inference that is the platform receiver; for a third-party node operator it
is the operator's own wallet, which is what makes the receipt a proof of
payment to the operator.
Verification procedure
verifyInferenceReceipt() (and both verifiers built on it) runs these checks
in order; each is reported individually:
| Check | Meaning |
|---|---|
shape |
receiptType, signature, signer, job, payment all present and typed. |
receipt_signature |
ed25519 verify of signature over the receipt core, key signer. |
receipt_signer_trusted |
(when a signer is pinned) signer equals the pinned key. |
response_signature |
ed25519 verify of responseSignature over the job core, key responseSigner. |
prompt_binding |
(when raw prompt supplied) sha256(prompt) equals job.promptSha256. |
response_binding |
(when raw content supplied) sha256(content) equals job.responseSha256. |
token_totals |
tokensUsed == inputTokens + outputTokens, all non-negative integers. |
payment_fields |
network, payer, payTo, asset, transaction, amountAtomics all well-formed. |
The HTTP verifier and the CLI add one optional check on top:
| Check | Meaning |
|---|---|
onchain_settlement |
payment.transaction confirmed on payment.network (read-only RPC). |
The lane for onchain_settlement comes from the receipt's own
payment.network, compared in full against the canonical id. A verifier that
guesses the lane can report a devnet payment as a mainnet one, which is a false
statement about where money moved; both verifiers did exactly that until the
phase-4 proof run caught it. A network with no public endpoint (the local test
lane, a private cluster) is reported by its id and needs an explicit --rpc
rather than being silently looked up on mainnet.
A receipt is verified when every requested check passes. prompt_binding
and response_binding are optional because a third party may hold only the
receipt, not the raw text; the receipt still proves payment-to-job binding
without them.
Proving payment for work performed (operator flow)
- Run paid inference; keep the
inferenceReceiptfrom each response. - To prove a specific job was paid:
node scripts/inference-receipt-verify.mjs receipt.json --prompt "…" --content "…" --onchain. Exit 0 means the receipt signature, the response signature, both content bindings, and the on-chain settlement all check out. - To audit a stream of jobs server-side:
inference_jobsis queryable bypayerortx_hash(api/_lib/inference-jobs.jslistInferenceJobs).
Activation and lanes
A payment.network is a CAIP-2 id: solana: followed by the first 32 base58
characters of that cluster's genesis hash. The id therefore identifies the
ledger, which is what lets a receipt state where the money moved. The rail's
one definition of the Solana lanes lives in
api/_lib/x402/solana-networks.js.
- Local test lane (default for proof runs): a
solana-test-validatoron the operator's machine. It is the reproducible lane: unlimited SOL, an SPL mint the proof creates for itself, and no shared faucet to be rate-limited by. A test validator generates a fresh genesis on every reset, so the lane's id is derived at runtime fromgetGenesisHashand passed to the rail inX402_SOLANA_LOCAL_NETWORK. That variable is unset in every deployed environment, so the recognized networks there remain mainnet and devnet. The lane is named honestly: settling on a local validator while labelling the receipt as devnet would put a false chain id inside a signed attestation. - Devnet:
solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1, settled by the same self-hosted facilitator with every check above running identically. It is the shared public lane; its faucet is rate-limited per IP and is frequently dry on shared CI egress, which is why the local lane is the default. No real funds move on either. - Mainnet: the same receipt format with
payment.network=solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp(or any EVM lane the rail settles). Activation is settingINFERENCE_SIGNING_KEY(and optionally a distinctINFERENCE_RECEIPT_SIGNING_KEY) on the Cloud Run service env, an owner-gated deploy step. With the key unset, responses ship unsigned and no receipts are issued: that is the rollback position.
The proof run
scripts/inference-settlement-proof.mjs
settles one real metered job end to end and verifies its receipt. It runs a
real completion through the provider chain, signs the metered job, creates its
own 6-decimal SPL mint on the test ledger, builds an exact payment with the
reference client, puts it through verifyPayment → settlePayment, issues the
receipt, and verifies it (including a tamper check and the on-chain leg). Every
identity in the run is a throwaway keypair; no real asset appears anywhere.
Two production guards stay ON during the proof and are pointed at the run's own
throwaway payee and test mint rather than disabled: the facilitator's payTo
allowlist (X402_SELF_FACILITATOR_PAYTO_ALLOWLIST) and its settleable-mint pin
(X402_ASSET_MINT_SOLANA). A third, the DB-backed settle-credit gate
(api/_lib/x402/settle-credit.js, one
on-chain signature credits at most one payment), fails closed without a
database, so the proof brings a local Postgres rather than relaxing it. The
script header lists the containers.
The facilitator is served on loopback for the run. With the self-hosted
facilitator enabled the rail resolves it to ${APP_ORIGIN}/api/x402-facilitator
and calls it over HTTP, and APP_ORIGIN defaults to https://three.ws, so a
proof run left alone would ask production to co-sign a test-lane payment.
Interop requirement: memos
The reference x402 SVM client (@x402/svm, which
buildSolanaExactPayload delegates to)
attaches an SPL Memo to every exact payment it builds. Any facilitator
settling these payments must accept the Memo program
(MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr, and the legacy
Memo1UhkJRfHyvLMcVucJwxXeuD728EqVDDwQDxFMNo) as a no-op instruction: memo
owns no accounts and moves no lamports. Our own facilitator refused them until
this proof run surfaced it, which made every standards-built payment
unsettleable while our ring's own memo-free transactions passed. Covered by
tests/x402-facilitator-memo-interop.test.js.
Security notes
- Signing keys are ed25519 and MUST be distinct from every
X402_PAY_TO_*wallet and fromX402_RECEIPT_SIGNING_KEY(the secp256k1 EIP-712 key). These keys only attest; they never custody funds. - The domain tags are load-bearing: never sign untagged bytes with these keys, and never accept an inference artifact without its tag.
- The receipt commits to the settlement transaction but does not itself prove
confirmation; run the
onchain_settlementcheck (or look the tx up) when finality matters. An RPC outage must read as "unverifiable", never as "confirmed".