Skip to Content
x207x207 Docs

Architecture

The components of x207, how they connect, and how one voucher travels from a paid call to a creditor's claim.

x207 is a barter protocol for AI agents on NEAR. This page shows the engine underneath: mutual credit, netting and clearing in one circle contract. The contract is the only place where a circle is true. Every other component reads it, calls it, or helps someone use it. Anyone can replace the solver, the keeper and the facilitator; none of them holds funds.

Testnet only. No mainnet deploy has been made. See Deployments and Security and limits.

Components

                    x402 call (HTTP 402 / PAYMENT-SIGNATURE)
   Buyer agent  <------------------------------------------>  Seller agent
        |                                                          |
        | uses @x207/scheme (client)                               | uses @x207/scheme (server)
        |                                                          v
        |                                                    Facilitator
        |                                              /verify  /settle  /supported
        |                                                          |
        |                                         register_cumulative (signed voucher)
        v                                                          v
   +-------------------------------------------------------------------------+
   |                  x207-circle contract  (NEAR)                           |
   |  members, stakes, vouchers, obligations, clearing check, positions,     |
   |  claims, defaults, params, freeze, upgrade                              |
   +--------+----------------------------+-------------------------+---------+
            | NEP-297 events             ^ submit_clearing         ^ close_epoch, commit_epoch,
            v                            |                         | finalize_epoch, prune_epoch
   Backend: indexer --> SQLite     Solver (reads read API,         Keeper (anyone)
   read model --> read API,        computes cycles, submits)
   HTTP 207 report, marketplace,
   access broker
            |
            +--> Frontend dashboard (polls the read API, reads RPC views)
            +--> Solver (obligation graph)
            +--> Agents (read state)
            +--> MCP server (read tools)
ComponentRepoWhat it is
ContractscontractsThe x207-circle contract, the account-sale locker, DAO helper scripts, tests, mocks. See Contracts.
SDKsdkTypeScript packages: @x207/core (voucher signing, contract client, event parser, onboardMember), @x207/scheme (x402 batch-settlement binding for client, server and facilitator), @x207/mcp (MCP server, read tools by default, signs nothing), and a reference facilitator. See SDK.
BackendbackendIndexer that turns contract events into a SQLite read model, the read API, the HTTP 207 report, the settlement worker, the marketplace book and the access broker. See Read API.
FrontendfrontendThe dashboard: clearing pages, account pages (onboarding, settlement; need a wallet), marketplace pages. Polls the read API every 5 seconds and reads testnet RPC views. See Dashboard.
SolversolverOpen clearing solver: reads the frozen obligation graph, computes the largest cycle-only clearing with min-cost flow, submits it. Also the barter matching (x207-barter). See Solver.
AgentsagentsSix demo agents (translate, summarize, scrape, image, clean, compute) that sell behind an x402 paywall and buy from each other with signed vouchers. See Agents.
x402 callverify, settleregister_cumulativeclose_epoch, commit_epoch,finalize_epoch, prune_epochsubmit_clearingNEP-297 eventsobligation graphBuyer agentSeller agentFacilitatorx207-circle contractKeeperSolverBackend: indexer, SQLiteread model, read APIFrontend dashboardAgentsMCP server, read tools

The backend also hosts an optional appraiser: POST /x207/appraise asks a model on NEAR AI Cloud (inside a TEE) for a value in credit for a barter asset and stores proof. It is advice only; no contract reads it. See Appraiser.

Layers

The system has seven layers, from the agent to the observer.

LayerJobWhere
Agent interactionThe x402 exchange between buyer and sellerSDK, agents
CommitmentSigned cumulative vouchersSDK, contract
AccountingPair obligations and per-member debt against the limitContract
ClearingCancel cycles of debt, checked on chainSolver, contract
SettlementResidual paid in USDT, claimsContract, backend worker
Risk and governanceStake, limits, freeze, upgrade, DAO ownerContract
ObservabilityEvents to read model, dashboard, reportBackend, frontend

Data flow: a voucher to a settlement

  1. Request. A buyer calls a seller's endpoint. The seller answers 402 PAYMENT-REQUIRED with an x402 v2 offer: x207 batch-settlement next to exact.
  2. Voucher. The buyer retries with PAYMENT-SIGNATURE: an ed25519-signed cumulative voucher (fields circle, payer, payee, resource, unit, epoch, seq, cumulativeAmount). See Vouchers and x402 scheme.
  3. Serve. The seller asks the facilitator /verify. When it is valid the seller serves the call at once and returns PAYMENT-RESPONSE. Registering on chain happens after, so in this default mode a voucher the contract later refuses has already been served. A register-first mode waits for the chain instead; see x402 scheme.
  4. Register. The facilitator calls register_cumulative. The contract checks both parties are active, the voucher is inside the epoch before the cutoff, and the payer's debt stays within its limit.
  5. Close. After the epoch length, anyone calls close_epoch. The obligation graph is frozen and the proposal window opens.
  6. Clear. Any solver reads the graph from the read API and calls submit_clearing with edges. The contract checks them in one pass and keeps the proposal with the largest cleared_total. See Epochs and clearing.
  7. Commit. After the proposal window, anyone calls commit_epoch. Each member gets a net position: due for a net debtor, claimable for a net creditor.
  8. Pay. Net debtors pay their residual in USDT during the payment window, by ft_transfer_call with {"action":"settle"} or from Intents (mt_on_transfer). A member with auto-settle on is paid from stake. See Residual and settlement.
  9. Finalize. After the payment window, anyone calls finalize_epoch. A debtor still due defaults: its stake covers it, then the reserve. Limits are recomputed.
  10. Claim. Creditors call claim for USDT on their NEAR account or in their Intents balance.
  11. Observe. The indexer reads NEP-297 events into the read model. The dashboard, the read API, the 207 report and the MCP server read from it.
call endpoint402 PAYMENT-REQUIREDPAYMENT-SIGNATURE voucherverifyserve call, PAYMENT-RESPONSEregister_cumulativesubmit_clearingpay residual in USDTclaimclose_epoch freezes the graphcommit_epoch sets due and claimablefinalize_epoch, debtor still due defaultsBuyerSellerFacilitatorCircle contractSolverBuyerSellerFacilitatorCircle contractSolver

Where trust sits

  • The contract holds stake and pays claims. A solver's proposal changes nothing unless the contract's check passes: no edge clears more than is owed, and every member's cleared inflow equals its outflow.
  • A voucher signature is the only gate for registration, so any account can submit one.
  • The facilitator, solver, keeper and indexer can be run by anyone. The deployed ones are run by the x207 team on testnet.
  • The read API and dashboard are views of chain state. The contract is the source of truth.

Source

Edit on GitHub

x402 scheme

x207 is a binding of the x402 batch-settlement scheme on the network x207:<circleId>. Headers, entry fields, facilitator endpoints and reason codes.

Contracts

The x207-circle smart contract on NEAR - what it holds, what it enforces, how to build and test it.

On this page

ComponentsLayersData flow: a voucher to a settlementWhere trust sitsSource