Agents: buy inference on P2P

Offers, neutral matching, x402 or scoped keys, server-enforced budgets, agent-readable errors, MCP/A2A/OpenAPI. This page is part of the P2P AI chapter of the TokenOS documentation.

• Agents: buy inference on P2P TokenOS P2P is an OpenAI-compatible inference market: peers post a price per model, buyers pay per request with x402 (USDC on Solana) or with a tos_ key funded by credits. This page is the machine-facing contract: how an agent discovers what is for sale, asks for a neutral ranked match, pays, stays inside a human-signed budget, and reads errors. Everything here is a public, versioned HTTP surface — nothing is hidden in prompts or tool descriptions. Matching ranks by price first, then trust and measured first-token latency; wash-flagged peers are excluded. The reference seller TokenOS runs is listed like any other peer with firstParty: true and ranks after independent peers. Public statistics exclude TokenOS’ own traffic and test keys. Every match response carries neutral.neutralMatching and neutral.houseSellerFavored with the rule in plain words; if either ever changes, the response says so. Discover and match Two free endpoints, no key, CORS open, cacheable. Prices are per million tokens; quotes are upper bounds (input estimate + max_tokens ). Body: models[] or capability (chat · messages · responses · embeddings · audio · images), features (tools, json_mode, vision, streaming, context_length), max_output_usd_per_million , max_input_usd_per_million , max_quote_usd (per-request budget), min_trust , max_ttft_ms , privacy ( hosted_ok | local_only : skip hosted/relayed supply and return peer endpoints), sample (the body you will send), limit . Returns ranked matches with factual reasons[] and a quote that equals the 402 challenge for the same body. Read-only: no hold, no payment.
• Every live peer × model × price × capability, with per-peer signals from settled sessions (served, success rate, median TTFT, refund rate) and per-model price summaries. ?model= , ?capability= , ?route= filter.
• Public network statistics over the last 30 days — settled sessions, success rate, refund rate, median TTFT, per-model cheapest/median prices. Internal and test identities excluded.
• Demand board: models buyers asked for that no peer served, with the price points agents asked for (counts only; never prompts or buyer identities).

Try it: live match

The same POST /api/p2p/v1/match the agents call, against the live network. Move the constraints and read the reasons[] each peer was ranked on — price floor, trust, measured first-token latency, verification, bonding. Free, no key, nothing reserved.

Pay: x402 or a scoped key

The hosted gateway routes to the cheapest offer, then higher trust, with failover before anything is charged. Response headers carry x-tokenos-peer , x-tokenos-session , x-tokenos-match-reason and, when a failover happened, x-tokenos-rematched-from . Prompts travel gateway → seller only; TokenOS stores aggregate counts, never prompts or completions.

Budgets: human-signed, server-enforced

A principal (wallet) signs a mandate once on /p2p/budgets and mints scoped tos_ keys under it. The agent only ever holds the key. Enforcement happens in the gateway on every request — nothing in a prompt, tool description or client flag can raise a cap.

• Caps nest: perRequestUsd ≤ hourlyUsd ≤ dailyUsd ≤ totalUsd . Optional allowed.models / allowed.capabilities , maxUnitPrice , minTrust , expiresAt , approvalThresholdUsd , notify.email / notify.webhook . JSON Schema: /api/p2p/budgets/schema.json .
• Every request is quoted at its upper bound at the chosen peer’s price. If it would cross any window, the answer is 402 budget_cap_reached with quoteUsd , remainingUsd , window , resetsAt — before a hold is reserved.
• Requests above approvalThresholdUsd create an item in the principal’s Approvals Inbox (email / webhook if configured). The agent gets 402 approval_pending with approval.pollUrl ; once approved it retries with x-tokenos-approval: <itemId> . The allowance is single-use and capped at the approved quote (+10%).
• Session holds are sized to the remaining headroom so the sum of holds never exceeds a cap; unspent holds return when sessions close. Receipts are seller-signed settlements ( GET /api/p2p/budgets//receipts ); their sum equals the dashboard total.
• Revoking a budget revokes every key under it; the agent’s next request fails with 401 key_invalid .

Scoped-key budgets are enforced for credit-funded keys. Wallet-bound enforcement of x402 payers at the facilitator ( agent.payerWallet is recorded today) ships after the P2P money-path fixes are re-tested. TokenOS keeps the no-account x402 flow available under platform guardrails regardless — budgets are optional.

Errors an agent can act on

Every 4xx/5xx from /api/p2p/v1/* carries the same envelope: error.code (machine-readable), error.message (plain), error.next_action (what to do), error.docs (this page) — plus route-specific fields.

Where agents find this

• /.well-known/agent-card.json and /.well-known/agent.json — the signed A2A platform card (Ed25519 JWS) with P2P skills. /.well-known/x402 — facilitator pointer.
• /openapi.json — curated OpenAPI 3.1 of the agent surface (every parameter described, examples included); /api/openapi-full.json — every public route, admin and console routes removed.
• x402 Bazaar discovery — one resource per route sold over x402 ( chat/completions , messages , responses ; embeddings, audio and images are key-only) with accepts[] , input/output schemas and extensions.bazaar.info , at GET /api/x402-facilitator/discovery/resources (search, payTo, pagination).
• MCP tools on /api/mcp : p2p_offers , p2p_match , p2p_quote — all free and read-only; paying stays on the HTTP route so the money path is one code path.
• Skill: tokenos-p2p (SKILL.md) for agent frameworks that load skills — same facts as this page.

What TokenOS does not do

Protocol details for running your own buyer or seller node: Buy inference , Sell inference , P2P protocol reference . Payments on TokenOS are for metered usage only.

This request (quoted $0.0410) would cross the budget's dailyUsd cap

Wait for the window to reset (\`resetsAt\`), lower max_tokens / pick a cheaper peer, or ask the principal to raise the cap.

No online peer lists that model. Pick one from GET /v1/offers → models[] (or use "capability" in /v1/match).

Peers exist but none accepted within the failover budget. Retry shortly or relax min_trust / pin.

x402 challenge: pay accepts[].amount to payTo and retry the identical body with PAYMENT-SIGNATURE.

The key’s wallet has no credits for a session hold. Fund at /p2p/buy or use x402.

The route needs a tos_ key, or the key is revoked / past expiry. Mint a new one or use an x402 route.

The quote would cross a cap. Body carries quoteUsd, remainingUsd, window, resetsAt.

model_not_allowed / capability_not_allowed / price_above_cap / trust_below_min / budget_expired / budget_revoked

The budget forbids this request; the principal must change the mandate.

The request waits in the principal’s Approvals Inbox. Poll approval.pollUrl; retry with x-tokenos-approval: <itemId>.

Denied, expired, or the single-use allowance was already consumed.

Per-address or per-payer guardrail. Honour Retry-After.

x402 (no account) · scoped key (budgeted)

, <>Session holds are sized to the remaining headroom so the sum of holds never exceeds a cap; unspent holds return when sessions close. Receipts are seller-signed settlements (<C>GET /api/p2p/budgets/{

No preferential ranking for the reference seller, and no undisclosed house traffic in public statistics.

No budget raised by anything an agent says — only the principal’s wallet signature changes a mandate.

No prompt or completion storage at the gateway; funnel instrumentation is aggregate counts per hour.

No paid or money-moving tools in MCP directories; MCP stays read-only, HTTP x402 is the only payment path.

Browse the full TokenOS documentation or jump to the API reference, credits & pricing or FAQ.