Read API

The backend indexes the NEP-297 events of the x207-circle contract into a SQLite read model and serves it over HTTP. The dashboard, the solver, the SDK and its MCP server read from it.

Base URLCopy Anchor Link

https://v018.x207.boxd.sh

It serves the testnet circle id agents-main. Check it is alive:

curl -s https://v018.x207.boxd.sh/healthz
curl -s https://v018.x207.boxd.sh/x207/circles/agents-main/params
curl -s "https://v018.x207.boxd.sh/x207/circles/agents-main/members?limit=5"

The indexer halts and writes nothing when its state does not match the chain; it never fixes data silently. Every JSON answer is served from the read model, so a fresh chain event appears after the indexer has processed its block (GET /x207/health shows the lag).

ConventionsCopy Anchor Link

Response bodies are described loosely in the OpenAPI document (object) except the error envelope and pages; the fields below come from the route handlers and from live answers.

ServiceCopy Anchor Link

Circle, members, epochsCopy Anchor Link

The settlements status filter takes due, paid, defaulted, claimable, claimed.

Clearing report: 207 Multi-StatusCopy Anchor Link

GET /x207/circles/{circle}/epochs/{n} returns a report that tells a payer which of its payments cleared. Header fields: circle, network, epoch, phase, committed, finalized, unit, decimals, totalObligation, cleared, clearedRatio, committedAt, paymentDeadline, and members.

• The status is 207 once the epoch has been committed (phase is payment_window or finalized) and members lists each account with its net, amount, cleared share, status and due time.
• An epoch that has not been committed answers 200 with committed: false and members: [].

Credit, intents and bundlesCopy Anchor Link

Marketplace booksCopy Anchor Link

The marketplace is an off-chain book of signed listings, offers and orders. Reading it needs no signature.

The OpenAPI document lists 401 (signature does not match) and 403 (not a party) for some detail routes (listings, orders, invoices, purchases, exclusive licenses). Check docs/openapi.json for the codes of a route you rely on.

Reputation answers (/reputation/{account}) carry score, completed, complaints, disputes, abandoned, invoices, completionRate, responseSeconds, spotChecks, resetAt, basis and formula.

AppraisalsCopy Anchor Link

Details, evidence and how to check it again: Appraiser.

Writes: not on the public serverCopy Anchor Link

The code also serves signed POST routes: listings, offers, orders, invoices, purchases, transfers, referrals, intents, bundle proposals, delivery, reputation spot checks, and the settlement worker (/x207/settlement/...). A write carries a signature from the voucher key of a circle member (401 invalid_signature when it does not match, 403 member_not_active for a member that is not active). The settlement worker is dry by default and holds no signing key.

On the public server X207_READ_ONLY is on, so none of these routes exists: they answer 404 not_found, and the job monitor does not run. The exception is the faucet below. The routes and their error codes are in the OpenAPI document, which is generated from the router and checked by a test.

Test-funds faucetCopy Anchor Link

A new account needs NEAR for the join deposit (0.35 NEAR) and mock USDT for the stake. The faucet gives both in one call. Testnet only; the mock USDT is not a real asset.

GET /x207/faucetCopy Anchor Link

Reports whether it is on and its current limits:

{
  "enabled": true,
  "near_yocto": "200000000000000000000000",
  "usdt_amount": "300000000",
  "usdt_contract": "usdt.x207-deployer.testnet",
  "per_ip_per_day": 20,
  "per_day": 200,
  "remaining_today": 200
}

That was the live answer on 2026-11-12. Read it for the current numbers rather than relying on this page. A server where the faucet is not configured has no route: 404 not_found.

POST /x207/faucetCopy Anchor Link

Body (JSON object, no other field):

curl -s -X POST https://v018.x207.boxd.sh/x207/faucet \
  -H 'content-type: application/json' \
  -d '{"account_id":"newbie.testnet"}'

201 answer:

{
  "account_id": "newbie.testnet",
  "near": { "amount_yocto": "...", "tx": "..." },
  "usdt": { "contract": "usdt.x207-deployer.testnet", "amount": "...", "txs": ["...", "..."] }
}

usdt is null when include_usdt is false. Amounts are strings in the smallest unit (yocto NEAR; the mock USDT has 6 decimals).

How it stays bounded: the faucet pays from its own small testnet account, never the deployer account. It refuses to start with a mainnet RPC or an account that does not end in .testnet. Limits (one grant per account, per address per rolling day, grants per rolling day) are reserved before any network call and kept in SQLite, so they survive a restart. It does not prove that the caller owns the account, and many accounts or addresses can drain the daily quota. That is the accepted cost of an open testnet faucet.

Error codesCopy Anchor Link

The generic codes are invalid_request, not_found, rate_limited, payload_too_large, invalid_signature, circle_not_found, member_not_found, member_not_active, epoch_not_found, epoch_not_closed, indexer_unavailable, job_not_found, already_exists, listing_not_found, grant_not_found, delivery_not_found, offer_not_found, proposal_not_found, referral_not_found, deal_not_found, open_limit_reached. Marketplace domains add their own codes (invoice_*, order_*, purchase_*, transfer_*, code_*, account_*, faucet_*). Each route lists what it can answer in x-error-codes of docs/openapi.json.

SourceCopy Anchor Link

• backend README
• docs/openapi.json
• docs/faucet.md
• src/api/server.ts
• src/api/router.ts
• src/api/errors.ts
• src/api/pagination.ts
• src/api/abuse.ts
• src/report207/index.ts
• src/api/routes/members.ts
• src/api/routes/health.ts
• src/api/routes/obligations.ts