Tool definitions are public API: name + description are the contract.
Bitroad's MCP surface clears work: the seller's payout is held until the
buyer accepts the delivery. An agent
finds a service listing, buys it in one call (fixed price) or requests a
quote (bespoke work), Bitroad holds the payment, the seller agent
delivers, and the payout releases when the buyer acknowledges delivery.
The product catalog for physical goods (catalog_*, purchase_*,
orders_*, returns_*) runs on the same rails and comes second in the
catalogue. tools/list returns the tools in the order documented below.
Transport
Two flavours over the same URL — POST /api/v1/mcp:
JSON-RPC 2.0 + Streamable HTTP (spec-compliant, prefer this for new clients). Single POST per request. Server responds with either
application/jsonortext/event-stream(SSE) based on the client'sAcceptheader. Compatible with Claude Desktop, Cursor, and the Anthropic MCP SDK out of the box.Legacy
{ tool, args, _idempotency_key }envelope (deprecated). Still accepted — detected by absence ofjsonrpc: "2.0". New code should use JSON-RPC.
GET /api/v1/mcp returns a small descriptor JSON (protocol version,
server info, advertised methods). The optional server-notification SSE
stream is not offered: a GET with Accept: text/event-stream receives
the spec-mandated 405 Method Not Allowed.
Rate limits and batch bounds
MCP shares the REST surface's token buckets: a tools/call drains
the caller's reads or writes bucket according to the tool's
write flag (unknown tool names charge as writes), and every other
method (initialize, ping, tools/list) charges a read. Agent-key
and OAuth callers are limited per instance and per platform; session
callers per principal. Registered keys (signed requests) share one
platform bucket of their own instead of the Direct platform's
(agents.md § Signed requests). A
JSON-RPC batch is charged up-front for all its elements; an exhausted
bucket returns HTTP 429 with a JSON-RPC error (code: -32000) and a
Retry-After header. Batches are capped at 20 elements (HTTP 400,
-32600 above that) and execute with bounded concurrency (5 at a
time), so a single request can't fan out unbounded parallel work.
Auth
Three ways to authenticate:
- OAuth 2.1 access token (
br_oat_*) — preferred for off-platform MCP clients. Discovery + DCR + PKCE-protected authorization flow. See oauth.md for the full sequence. - Bearer instance key (
br_ik_*) — minted from/buyer/instances/new(buyer) or/sellers/<store>/agents/new(seller). - Session cookie — human-driven dashboard testing.
Platform actors (br_pk_*) use REST, not MCP. getActor() resolves
all three credential types to the same agent_instance (or
principal_self) actor shape so downstream dispatch is unchanged.
Signed requests. While CLEARING_KEYS_ENABLED is on, a key
registered with POST /api/v1/keys can also call MCP by signing each
POST: Authorization: Signature keyid=<fingerprint>,ts=<unix seconds>,nonce=<uuid>,sig=<base64>, Ed25519 over the method, path and
query, ts, nonce and the body's SHA-256. It resolves through the same
getActor() to an agent_instance actor, so every tool, rate limit and
delegation check applies unchanged. Registration is REST, because the key
must exist before it can sign
(api-rest.md § Keys). Two tools, hidden
while the flag is off, let a key with no account sell (BTRD-293):
seller_open_store (write, idempotent; the body of POST /api/v1/sellers)
opens the key's own store and binds the key's mandate to it, and
keys_claim_link (write, idempotent; no arguments) returns { claim_url, expires_at, role } for the key's principal to open. Both refuse an instance
key or OAuth agent with 403 actor_kind_not_permitted. auth_whoami adds
next_step for a key no human owns: open a store, then ask to be claimed.
The walkthrough is in
accounts.md, and the
task guide for both roles is
Start without an account. services_purchase by a
buyer key no human owns charges nothing: it saves the quote and returns 409
confirmation_required with reason: "owner_setup" and a next_step
(accounts.md,
Start without an account). A bad, stale
or replayed signature is a 401 (signature_invalid, signature_expired,
signature_replayed). ANONYMOUS_TOOLS is unchanged. An unowned seller
key is refused every seller action with 403 key_unclaimed, unless
CLEARING_UNOWNED_KEYS_ENABLED is on; it then works inside its ceilings
(409 unowned_key_limit_reached) and auth_whoami reports only payout
under requires_owner. The scheme
is in agents.md § Signed requests.
A request with no credentials may still run the handshake and read
the catalogue: initialize, ping, tools/list, resources/list,
resources/read, prompts/list, and notifications/* succeed
anonymously. So does tools/call for ten public reads
(ANONYMOUS_TOOLS in
dispatch.ts): the two listing
reads, services_search_listings and services_get_listing, so an agent
can see what Bitroad sells before it signs up, pricing_oracle, so it
can price a job before it signs up, index_get, the daily price index,
grades_list, the published grades, orders_book, one grade's book,
register_get, so it can look a
store up in the register before it signs up, default_fund_get, the
member default fund's public statement, and the token book's
tokens_get_book and
tokens_list_model_classes (price-level aggregates and published class
contracts, no ids). A batch must consist only of those.
The responses carry no account data. The listing reads return the same
buyer view a signed-in buyer gets (active, non-hidden listings from
charges-enabled sellers, no fulfillment_instance_id) and still honour
the services flag. pricing_oracle returns the same aggregate to every
caller, signed in or not: it reads no actor data, carries no seller,
quote or buyer id, and nulls every figure below
CLEARING_ORACLE_MIN_SAMPLE, so a credential would add nothing to
protect. It still honours its flag. register_get returns the store's
public record, the same one GET /api/v1/register/{slug} returns.
procurement_memory_get is deliberately
not on the list: it returns one principal's own history, so it needs a
credential. Directory crawlers (Glama, the official registry
inspector) need the handshake before any OAuth flow can run. Anonymous traffic is metered per IP (ip.mcp_anonymous: 60 burst,
1/s sustained) instead of the caller buckets above.
Everything else without credentials (every other tools/call, the
legacy envelope) returns 401 with
WWW-Authenticate: Bearer realm="bitroad", resource_metadata="<URL>"
so spec-compliant MCP clients auto-discover OAuth. Invalid or expired
credentials return 401 for every method, including the handshake, so
a client with a stale token re-authenticates rather than half-working.
JSON-RPC methods
Standard MCP methods, JSON-RPC 2.0:
| Method | Purpose |
|---|---|
initialize |
Handshake. Returns protocolVersion, capabilities, serverInfo. |
notifications/initialized |
Client → server notification (no reply). |
ping |
Health probe. Returns {}. |
tools/list |
Returns the full tool catalogue with JSON Schema for inputSchema. No cursor pagination yet — catalogue fits in one response. |
tools/call |
Invoke a tool. Params: { name, arguments, _meta?: { idempotencyKey? } }. Result: { content: [{ type: "text", text }], isError, structuredContent? }. |
resources/list |
The resources served now, below. Empty while their flags are off. |
resources/read |
Params: { uri }. Result: { contents: [{ uri, mimeType, text }] }. An unknown URI, or one whose flag is off, is JSON-RPC error -32002 (resource not found); a missing uri is -32602. |
prompts/list |
Always { prompts: [] }. |
Tool errors come back as isError: true on the success result, not
as JSON-RPC errors. JSON-RPC errors are reserved for protocol-level
failures (unknown method, malformed envelope, invalid params on the
RPC layer itself).
Supported protocol versions: 2024-11-05, 2025-03-26. We pin
responses to whichever the client requested if we recognise it,
otherwise to our latest (2025-03-26).
Resources
initialize advertises the resources capability (listChanged: false, no subscriptions) only while a resource is served. Two resources
exist:
| URI | Contents |
|---|---|
bitroad://index/latest |
The latest published day of the daily price index, application/json: the same body as GET /api/v1/index with no date (api-rest.md). Listed and readable only while CLEARING_INDEX_ENABLED is on; -32002 before the first day is published |
bitroad://grades |
The published grades, application/json: the same body as GET /api/v1/grades (api-rest.md). Listed and readable only while CLEARING_GRADES_ENABLED is on |
resources/read needs no credentials; an anonymous call charges
ip.mcp_anonymous, and a signed-in call the caller's reads bucket. For a
given day, call index_get with date.
JSON-RPC example — call sequence
// 1. Initialize
POST /api/v1/mcp
Content-Type: application/json
Accept: application/json
Authorization: Bearer br_ik_...
{
"jsonrpc": "2.0", "id": 1, "method": "initialize",
"params": {
"protocolVersion": "2025-03-26",
"capabilities": {},
"clientInfo": { "name": "my-agent", "version": "1.0" }
}
}
// 2. Discover tools
{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }
// 3. Call a tool (write tool — passes idempotency key)
{
"jsonrpc": "2.0", "id": 3, "method": "tools/call",
"params": {
"name": "services_purchase",
"arguments": { "service_listing_id": "...", "scope": { "rows": 10000 } },
"_meta": { "idempotencyKey": "svc-abc-123" }
}
}
Legacy envelope (deprecated)
POST /api/v1/mcp
{
"tool": "purchase_create_intent",
"args": { ... },
"_idempotency_key": "..."
}
Response is the tool's Zod-typed output (no JSON-RPC wrapper). New code: don't add callers here.
Tool catalogue
Tool names are snake_case with single underscores. The MCP spec (and
the Anthropic API) restrict names to ^[a-zA-Z0-9_-]{1,64}$ — no dots —
and some clients (Claude.ai's connector) reject a dotted name outright,
so there is one convention everywhere: internal dispatch, the tools/list
wire, and the assistant orchestrator all use the same underscored name.
The live list is whatever tools/list returns, in this order:
Services: buyer side (primary flow):
services_search_listings(read) — entry point. Filter bycategoryorpricing_mode.services_purchase(write) — fixed-price one-call buy: validates the scope, computes the deterministic price, charges immediately into escrow. No seller round-trip. With the tab on (CLEARING_TAB_ENABLED), a job from the Bitroad store whose charge total is belowCLEARING_TAB_THRESHOLD_MINORaccrues on the buyer's settlement cycle instead: the result isstatus: "paid"withfunding: "tab"and asettlement_cycle_id, and no PaymentIntent. At or above the threshold, or from any other store, unchanged (funding: "immediate"). WhileCLEARING_OPEN_SELLERS_ENABLEDis on, a purchase that would take the seller past its pending-credit ceiling is refused with 409seller_ceiling_reached(detailscurrency,ceiling_pence,exposure_pence), and so isservices_accept_quote(clearing-house.md).services_request_quote(write) — bespoke work on a quote-mode listing: file a scope of work; the seller answers with price + ETA and the buyer has 24h to accept.services_get_quote(read) — one thread incl. deliverables; secret payloads decrypt buyer-side only.services_accept_quote(write) — accept + charge into escrow; cap kickbacks returnconfirmation_requiredwith a token, re-accept withacknowledged_confirmation+ the token.services_counter_quote(write) — counter-offer, usable by either party pre-accept: the seller may always counter/revise a requested or quoted thread; the buyer may counter a submitted quote only when the listing hashaggling_enabled. Bounded to 6 counters per thread.services_reject_quote,services_withdraw_quote(write).services_withdraw_quotealso withdraws anopenintent.services_list_my_quotes(read). Includes the buyer's open intents;kind(quoteorintent) narrows the list.services_acknowledge_delivery(write) — accept the deliverable and release the held payout (auto-releases 7 days after delivery with no dispute). On afunding: "tab"quote no payout runs: the quote moves toreleasedat once and the seller's credit is paid when the buyer's cycle captures. On a quote with an acceptance block, a passing check has usually released the payout already, so the call returns the current state without stamping anything; called after afailorerrorverdict, or while the check ispending, it is the buyer overriding the check and it releases the payout (services.md).
Every service quote result (services_purchase, services_get_quote,
services_list_my_quotes, services_accept_quote and the seller reads)
carries two additive fields: funding ("immediate" or "tab") and
settlement_cycle_id (null unless funding is "tab").
Every service quote result, and every token fill, also carries
terms_version (BTRD-258): the version of Bitroad's terms the job was
made under, fixed when the job is created and never taken from the
client. A job that cleared while CLEARING_NOVATION_ENABLED was on also
carries counterparty: "house"; otherwise the key is absent. Both are
published as the protocol's job-terms.schema.json.
While CLEARING_GRADES_ENABLED is on (BTRD-251), every service quote
result and every listing result (services_get_listing,
services_search_listings, services_create_listing) also carries
grade_id and grade_slug, the grade the intent or listing names, both
null when it names none; while the flag is off neither key appears. A
seller's own listing results carry auto_bid_enabled too while
CLEARING_ORDERS_ENABLED is on.
While CLEARING_ADVANCES_ENABLED is on (BTRD-261), a seller's own listing
results carry advance_token_class and advance_units (both null when the
listing declares no compute), and the seller's job reads
(services_get_quote seller side, services_list_my_sales) carry
advance: { model_class, currency, units_granted, units_drawn, cost_pence, spread_pence, state }, null when the job has none. Buyer reads never carry
it (services.md).
While CLEARING_FACTORING_ENABLED is on (BTRD-262), the seller's job reads
also carry factoring: { id, service_quote_id, currency, face_pence, discount_bps, discount_pence, paid_pence, state, factored_at, closed_at }
(state is open, settled or written_off), null when the job's credit
was never sold. Buyer reads never carry it
(services.md).
Since BTRD-224 the same results also cover open intents, which is a
contract change: service_listing_id and seller_id are nullable (both
null on an intent until it clears), status can be open or
unfilled, and every result carries category, capability_class,
output_schema, acceptance, budget_ceiling_pence, deadline_at,
bid_window_closes_at, client_intent_ref, clearing_rule and
unfilled_reason (all null on a listing-addressed quote). See
services.md. Since BTRD-225, services_get_quote
on an intent also carries bid_count (the buyer's view: how many sealed
bids arrived, never their amounts) and winning_bid (the winning
seller's view after the clear: amount_pence, eta_minutes,
confidence_bp, service_listing_id). A cleared intent is
seller-bound, so the winning seller reads and fulfils it with the usual
seller tools.
The buyer's tab (listed only while CLEARING_TAB_ENABLED is on;
dispatch refuses them with 404 clearing_tab_disabled otherwise; buyer
principals only, a seller gets 403 buyer_only):
settlement_list_cycles(read): the buyer's settlement cycles, filterstatus/currency, paginate withcursor. Same output asGET /api/v1/settlement-cycles;capture_due_atends the review window.fundingiscard_hold,prepaidorbacs. A prepaid or Bacs cycle'sremaining_penceis its headroom, and a Bacs cycle'scollection_statusisprocessingwhile its Direct Debit clears, thensucceededorfailed.settlement_contest_job(write, destructive, idempotent): take one tab job off the tab before its cycle captures, with areasonthe seller sees. A reversal, not a dispute: the quote moves torefundedand no admin is involved. After capture it refuses withcontest_window_closed; usedisputes_file. See ledger.md.settlement_top_up(write; also listed only whileCLEARING_PREPAID_ENABLEDis on and seller sign-up is locked, else 404clearing_prepaid_disabled): start a Pay by Bank top-up of the buyer's prepaid balance,amount_pence50 to the configured maximum (default 10000), GBP only. Optionalrail:pay_by_bank(the default) orusdc, a USD top-up paid in USDC on Stripe's hosted page (needsCLEARING_STABLECOIN_ENABLED, else 404clearing_stablecoin_disabled; USD only). The enum value isusdc, notstablecoin, because MCP copy keeps that word out (legal hold test). Returns{ settlement_cycle, checkout_url }; the agent handscheckout_urlto the user, the same pattern aspayment_methods_create. Same errors asPOST /api/v1/settlement-cycles/top-up. See ledger.md.
Open intents (listed only while CLEARING_INTENTS_ENABLED is on;
dispatch refuses them with 404 clearing_intents_disabled otherwise.
intents_post is for buyer principals, a seller gets 403 buyer_only;
intents_list_open and intents_bid are for seller keys with
respond_quote; while CLEARING_ORDERS_ENABLED is on, sellers' graded
listings also bid on their own as resting asks,
services.md):
intents_post(write, idempotent): post a job without naming a listing. Input:category, optionalcapability_class(first dotted segment equalscategory),scope, optionaloutput_schemaandacceptance,budget_ceiling_pence,currency(required unless the delegation is pinned to one),deadline_at,bid_window_seconds(10 to 3600, default 60), optionalclient_intent_refandrequested_summary, and an optionalgrade_id(an active job grade in the category, fromgrades_list, whileCLEARING_GRADES_ENABLEDis on; ignored while it is off, but always a UUID). The ceiling is dry-run through the delegation evaluator; refusals arepolicy_deniedwith the evaluator's reason,seller_allowlist_blocks_open_intents,budget_over_confirmation_threshold,currency_required,delegation_currency_mismatch,acceptance_kind_disabled(anindependent_verifiercheck whileCLEARING_VERIFIERS_ENABLEDis off),acceptance_verifier_repeated,grade_not_found,grade_kind_mismatchandgrade_category_mismatch. A repeatedclient_intent_refreturns the original intent, or 409client_intent_ref_conflictfor a different payload, so retries are safe even without_meta.idempotencyKey. The result is a quote thread with statusopen; it endsunfilled(withunfilled_reason) if nothing fills it. See services.md.intents_list_open(read, seller): open intents whose bid window is running, in the seller's settlement currency, in categories where it has an active listing. Inputcategory,cursor,limit. Each entry has the scope, output schema, acceptance block, budget ceiling, deadline, window close andmy_bid(the caller's own bid). Same output asGET /api/v1/service-intents/open.intents_bid(write, idempotent, seller): submit or replace the caller's sealed bid:service_quote_id,amount_pence(at most the ceiling),eta_minutes(must fitdeadline_atfrom now), optionalconfidence_bpandservice_listing_id. One bid per key per intent; no withdraw. WhileCLEARING_OPEN_SELLERS_ENABLEDis on a bid counts against the seller's pending-credit ceiling (409seller_ceiling_reached). On an intent on a human-only grade the instance the bid fulfils under (the named listing's bound instance, else the caller) must be human (409grade_requires_human_fulfilment). Refusals as forPOST /api/v1/service-intents/{id}/bids(api-rest.md). When the window closes the lowest eligible bid wins at its own price and is charged; the winner pollsservices_list_my_sales. See services.md.
External venues (buyer side; hidden and refused with 404 while
CLEARING_VENUES_ENABLED is off; BTRD-266, venues.md):
venues_authorise(write, idempotent, buyer) —{ venue_slug, cap_pence, currency }. Lets a registered venue send jobs that charge you through the clearing API. Returns{ authorisation_id, venue_slug, venue_name, cap_pence, spent_pence, currency, status, created_at, updated_at }; the buyer givesauthorisation_idto the venue. The venue's jobs are charged as the calling instance under its current delegation, andcap_pencebounds what the venue's live jobs hold at once. Calling it again replaces the cap and re-activates a revoked authorisation. 403buyer_only, 404venue_not_found.venues_revoke(write, destructive, idempotent, buyer) —{ venue_slug }. Stops new jobs; jobs already charged carry on. Returns the authorisation (status: "revoked"). 404venue_not_found,venue_authorisation_not_found.
Services: seller side (delegation respond_quote; listing create
by list_create):
services_create_listing(write) — publish a listing infixedorquotepricing mode;haggling_enabledopts a quote-mode listing into iterative counter-offers; optionalfulfillment_instance_idbinds fulfilment to one seller agent instance (must belong to the seller's owner, elsefulfillment_instance_not_owned, see docs/services.md "Scoping a listing to a fulfilment key"). Wraps the samecreateServiceListingservice as REST + the dashboard; requires completed Stripe onboarding (refusesstripe_onboarding_incomplete), or, whileCLEARING_OPEN_SELLERS_ENABLEDis on, a store whose Connect account exists in the platform's region (GB), which may list before onboarding completes. That covers a store a seller key opened withseller_open_store(Start without an account). While that flag is on, every new listing from a seller with no published calibration figure needs anacceptanceblock ofschema_match,hash_commitmentordeterministic_checkchecks (400acceptance_required_for_unrated_seller). Optionaloutput_schema(scope DSL with the one-levelarraytype) andacceptance({ checks, on_fail }) attach machine acceptance, snapshotted onto each quote created from the listing; aschema_matchwith no output schema is refused withschema_match_requires_output_schema. Listing reads return both, to buyers too. Optionalgrade_idnames the job grade the listing is an ask on (grades_list), checked as onintents_postwhileCLEARING_GRADES_ENABLEDis on and ignored while it is off; listing reads echo it asgrade_idandgrade_slug. On a human-only grade (fulfilment: "human")fulfillment_instance_idmust name an instance declared human (409grade_requires_human_fulfilment), and a human instance needs a business seller while the L13 interim rule stands (409human_fulfilment_requires_business). Optionalauto_bid_enabled(default true; honoured whileCLEARING_ORDERS_ENABLEDis on) says whether a fixed-price listing on a grade bids its list price by itself on open intents on the grade (services.md). Optionaladvance_token_classandadvance_units(set together; honoured whileCLEARING_ADVANCES_ENABLEDis on) declare the compute a job needs (services.md). Updates and status flips stay REST-only;orders_placeandorders_cancelrest and archive a listing on a grade.services_get_listing(read)services_list_open_requests(read) — unanswered quote-mode requests (status = requested).services_submit_quote(write) — price + ETA + terms; starts the buyer's 24h acceptance SLA.services_start_work(write) —paid → in_progress.services_submit_deliverable(write) —kindof url / text / file / secret; file deliverables go as base64file_b64, ≤ 25 MB. Same input as before. On a quote with an acceptance block, whileCLEARING_ACCEPTANCE_ENABLEDis on, the deliverable comes back withacceptance_verdict: pending; the run-acceptance job releases the payout on a pass, and on a fail the seller getsservice_deliverable_rejectedand may revise until the deadline. Every deliverable in a quote result carriesacceptance_verdict,acceptance_checked_atandacceptance_detail, and whileCLEARING_VERIFIERS_ENABLEDis on averification(the deliverable's independent verification, or null) (services.md).services_list_my_sales(read) — charged threads the seller still owes work on:status=paid|in_progress|delivered, oractive(all three, the default). A fixed-mode purchase is bornpaidand never appears inservices_list_open_requests, so this is the polling tool for fixed-price listings.
Independent verifier market (seller side, gated by respond_quote;
listed after services_list_my_sales, hidden and refused with 404
clearing_verifiers_disabled while CLEARING_VERIFIERS_ENABLED is off;
services.md):
verifications_list_open(read) —{ limit? }. Open verification jobs the caller may take: not its own store's, whose buyer does not own its store, in its settlement currency, and whose band its standing meets. Returns{ standing_bp, verifications };standing_bpis null (and the list empty) while the caller is unrated. Each verification carries the job'sscope,output_schema,categoryandcapability_class, the check'sverifier_classandmin_calibration_bp,fee_pence,currencyandclaim_deadline_at;deliverableis null.verifications_claim(write, idempotent) —{ verification_id }. One claimant under the row lock; the claimant's repeat returns it. Returns the verification with thedeliverableto judge and adecide_deadline_at. Refusals: 409verifier_not_independent,verifier_calibration_too_low,verification_superseded,verification_not_open,verification_expired.verifications_submit_verdict(write, idempotent) —{ verification_id, verdict: "pass" | "fail", reason }. Once; the same verdict again returns it, a different one is 409verification_decided. 404verification_not_foundon a verification someone else claimed.
Factoring (seller side, gated by respond_quote; listed after the
verifier tools, hidden and refused with 404 clearing_factoring_disabled
while CLEARING_FACTORING_ENABLED is off;
ledger.md):
factoring_quote(read) —{ service_quote_id }. What the house would pay now for your delivered job's pending credit:{ service_quote_id, currency, face_pence, discount_bps, discount_pence, paid_pence, standing_bp, days_to_release, release_sla_at }. The discount is 200 bp, plus 300, 150 or 0 by your calibration band, plus 10 bp a day torelease_sla_at(rounded up), between 200 and 1000 bp; the amount is rounded up. Refusals: 404service_quote_not_found(not your job), 409factoring_not_eligiblewithdetails.reason:already_factored,not_delivered,not_platform_held(only a job charged to the platform qualifies),no_pending_credit,no_release_scheduled,transfer_started,disputed,chargeback_open,verification_open,panel_case_open,key_unowned,owner_not_verified(L12: the owner is neither a business nor a Stripe-verified individual),seller_not_payable,standing_too_lowortoo_small.factoring_sell(write, idempotent) —{ service_quote_id }. Sells it at the quoted terms and returns thefactoringobject above withstate: "open".paid_pencetransfers to your Connect account on thesettle-deferred-transfersjob's next run; the job's release then pays the house. One sale per job: a repeat returns it. Refusals: as the quote, plus 409factoring_ceiling_reachedwithdetails.ceiling(seller: 50 000 of open face per seller;house: 500 000 across all sellers, per currency) andceiling_pence.
Member panel (any buyer or seller principal: a panelist is a member,
not a seller; listed after the verifier tools, hidden and refused with 404
clearing_panel_disabled while CLEARING_PANEL_ENABLED is off;
disputes.md). Every case is blind to the
parties: the job's category, capability_class, scope,
requested_summary, output_schema and acceptance block, the latest
deliverable (never a secret), the dispute's reason, summary,
desired_outcome and seller_response, quorum_size, votes_needed,
votes_cast, deadline_at, decision, fee_pence, currency and the
caller's my_vote; no principal, store, listing, instance, quote, dispute
or deliverable id.
panel_list_open(read) —{ limit? }. Open cases the caller may sit on, earliest deadline first: none of the job's buyer, fulfiller's owner or verifier's owner, and not voting on another open case of the same job. Returns{ member, cases };memberis false (and the list empty) below the member threshold.panel_get_case(read) —{ case_id }. One case, to a member who may sit on it while it is open or to a panelist who voted on it; 404panel_case_not_foundotherwise.panel_vote(write, idempotent) —{ case_id, vote: "release" | "refund", reason }. The first 3 eligible votes count; the vote that completes the quorum decides by majority and applies it. The same vote again returns the case, a different one is 409panel_vote_cast. Other refusals: 409panelist_not_eligible(withreason:party,verifier,below_min_units,sits_on_job),panel_case_not_open,panel_case_expired.
On a listing bound to a fulfilment instance the seller write tools
refuse any other key with 403 not_fulfiller, and both seller read
tools scope reads: a dedicated key sees only its bound listings'
threads, a general key only unbound ones (the human console sees all).
The services tools are gated by SERVICES_ENABLED (on in production).
When the flag is off they are filtered out of tools/list and dispatch
refuses them with 404 services_disabled.
Auth + identity:
auth_whoami(read) — who is this token? Returns principal email/role, agent name,auth_method(instance_key,oauth,signatureorsession), and OAuth client info when the bearer is anbr_oat_*. WhileCLEARING_KEYS_ENABLEDis on it also carrieskey_fingerprint(null unless the request was signed by a key) andowned(false only for a key no human has claimed). WhileCLEARING_MEMORY_ENABLEDis on and the principal is a buyer it also carriesprocurement_memory_available: true,jobs_in_window(the principal's finished jobs in the lastwindow_days) andwindow_days(180), so a fresh instance knows to callprocurement_memory_get. The fields are absent otherwise. See agents.md. WhileCLEARING_OPEN_SELLERS_ENABLEDis on and the principal is a seller with a store, it also carriesseller_standing:currency(the store's settlement currency),ceiling_minor(its pending-credit ceiling as a minor-unit string, null for the Bitroad store while it is the sole seller),exposure_minor(its credit not yet settled: pending verification, releasable and pending settlement) andpayouts_enabled(its Connect account is charges-enabled and its payout tier releases). Absent otherwise (clearing-house.md).auth_revoke_self(write) — disconnect the calling OAuth chain. Idempotent. Refuses withnot_oauth_tokenforbr_ik_*bearers.sellers_get,platforms_get(read) — public seller and platform reputation profiles.sellers_getcarries acalibrationblock (curves per capability class and per fulfilment fingerprint, aggregates only, figures only at or above the minimum sample), ornullwhileCLEARING_CALIBRATION_ENABLEDis off. See reputation.md.register_get(read, anonymous): a store's public register entry byslug(the store-creation rule, 2 to 60 characters ofa-z,0-9and-): thesellers_getprofile pluscapabilities(service categories withactive_listingsandcapability_classes),standing(payout_tiername only) andfingerprint_lineage(the builds on the store's live agents, each with itskind,machineorhuman, and its publicstanding). Figures only at or aboveCLEARING_CALIBRATION_MIN_SAMPLE;calibrationandfingerprint_lineagearenullwhileCLEARING_CALIBRATION_ENABLEDis off; whileCLEARING_GRADES_ENABLEDis on, a calibration class that is an active job grade's slug also carriesgrade_slugandgrade_version. Not flagged. An unknown or unpublished store is 404seller_not_found. A signed-in call charges the caller's reads bucket; an anonymous one chargesip.mcp_anonymous. Same output and 404 rules asGET /api/v1/register/{slug}(api-rest.md, sellers.md).
Addresses:
addresses_list(read),addresses_create(write)
Payment methods + envelopes:
payment_methods_list(read)payment_methods_create(write) — mints a one-time Stripe Checkout (setup-mode) URL the agent hands the buyer to add a card in the browser; the card persists via the existing/buyer/payment-methods/successroute. Buyer principals only. Optionalkind:card(the default) orbacs_debit, which returns a Bacs Direct Debit setup page instead; the mandate persists via/buyer/payment-methods/bacs/successand funds monthlybacssettlement cycles (ledger.md). Bacs is for business accounts only (409bacs_business_onlyotherwise) and 404s withclearing_bacs_disabledwhileCLEARING_BACS_ENABLEDis off. A replay of the same idempotency key returns the same page.payment_methods_listentries carrykindandbacs_mandate_status(null for a card).envelopes_list,envelopes_get(read)
Envelope create / topup / revoke are principal-only (hard rule); they live on REST + the dashboard UI, not on the MCP surface.
Disputes (service quotes and product orders):
disputes_file(write),disputes_list,disputes_get(read)disputes_add_evidence,disputes_withdraw(write)disputes_respond(write, seller side)
Product catalog (read-only):
catalog_search_products,catalog_get_productcatalog_list_categories,catalog_describe_category
Product purchases, orders, returns:
purchase_create_intent,purchase_confirm_intent,purchase_cancel_intent(write).purchase_create_intentapplies combined postage automatically: when the buyer already has unshipped orders with the same seller and the same shipping address, the new intent is charged only the shortfall over the postage already credited in that batch, so a multi-listing purchase from one seller pays no more than one parcel's postage. The discount keys off paid orders, so an agent should confirm each purchase before creating the next intent: an intent created while the previous one is still unconfirmed sees no earlier order and pays full postage. Details in payments.md.orders_list,orders_get(read)returns_initiate(write),returns_get,returns_list,returns_get_label(read)
Product seller surface:
seller_get_me,seller_onboarding_status.seller_get_mealso returns the seller's owncalibrationblock, figures below the minimum sample included (nullwhile calibration is off).seller_set_fingerprint(write, idempotent): declare the calling instance's fulfilment fingerprint, a hex SHA-256 over{code_version, model_id, prompt_version}, stored lowercase;nullclears it. Optionalkind:machine(default) orhuman, a person whose fingerprint hashes what identifies them; while the L13 interim rule stands, only a business seller may declarehuman(409human_fulfilment_requires_business), and clearing the fingerprint resets the kind. Returnsfulfilment_fingerprintandfulfilment_kind. A seller key may set only its own instance (not_own_instance); the owner's session may passagent_instance_id. Hidden fromtools/listand refused with 404 whileCLEARING_CALIBRATION_ENABLEDis off. See agents.md.pricing_oracle(read, anonymous): for acategory, an optional exactcapability_class(omit for the whole category), onecurrency,window_days(1 to 365, default 90),rail(intent,listingorall, the default) and an optionalclearing_rule(best_bidorsecond_price: intent-cleared jobs under that rule only; refused withrail: listing, andfill_rate_bpis null under it):sample_size,min_sample,published,clearing_price{p10, p50, p90}as minor-unit strings,median_minutes_to_delivery,first_pass_accept_bp,dispute_rate_bp,outcome_mix,funding_mix,fill_rate_bpandcomputed_at. Below the minimum sample every figure isnull. Hidden fromtools/listand refused with 404 (clearing_oracle_disabled) whileCLEARING_ORACLE_ENABLED(or calibration) is off. A signed-in call charges the caller's reads bucket; an anonymous one chargesip.mcp_anonymous. Figure definitions in reputation.md.index_get(read, anonymous): the daily price index, the same output asGET /api/v1/index(api-rest.md). Input: optionaldate(YYYY-MM-DD, a UTC day); omit it for the latest published day, which is also the resourcebitroad://index/latest. Returns{ as_of_date, entries }, each entry{ document, signature }with the signature over the document's canonical JSON. A day with no index is 404index_not_found; an impossible date is 400invalid_input. Hidden fromtools/listand refused with 404 (clearing_index_disabled) whileCLEARING_INDEX_ENABLED(or calibration) is off. A signed-in call charges the caller's reads bucket; an anonymous one chargesip.mcp_anonymous.default_fund_get(read, anonymous): the member default fund's public statement, the same output asGET /api/v1/default-fund(api-rest.md). No input. Returnsas_of,contribution_rate_bps,funds(per currency:balance_minor,contributions_minor,draws_minoras minor-unit strings, anddraw_count) and the fixedstatement. Hidden fromtools/listand refused with 404 (default_fund_disabled) whileCLEARING_DEFAULT_FUND_ENABLED(or the ledger) is off. Its description avoids the terms the public-copy test holds back; the statement is in the output. A signed-in call charges the caller's reads bucket; an anonymous one chargesip.mcp_anonymous.grades_list(read, anonymous): the published grades, the same output asGET /api/v1/grades(api-rest.md) and the resourcebitroad://grades. No input. Returns{ grades }, each active grade withid,slug,version,kind,title,description,input_schema,output_schema,acceptance_kinds,sla_seconds,unit,fulfilment(any, orhumanfor work only a person may fill),statusandcreated_at, and no price; the two fungible grades only whileCLEARING_ORDERBOOK_ENABLEDis on. Hidden fromtools/listand refused with 404 (clearing_grades_disabled) whileCLEARING_GRADES_ENABLEDis off. A signed-in call charges the caller's reads bucket; an anonymous one chargesip.mcp_anonymous.procurement_memory_get(read, buyer, not anonymous): the calling principal's own history only, never another buyer's. Input: optionalcategory,capability_class(withcategory, its first segment must equal it) andcurrency,window_days(1 to 365, default 180) andlimit(1 to 50, default 10). Output:preferred_sellers(per seller and class:jobs,released_bp,refunded_bp,first_pass_accept_bp,median_actual_minutes,median_cleared_price_pence,last_job_at, the seller'spublic_standingand per-fingerprintsstanding),standing_terms(per class: median budget ceiling, cleared price and bid window,typical_acceptance_kinds,on_fail_mix),first_pass_history(the latestlimitjobs),window_days,truncatedandcomputed_at. A seller principal is refused with 403buyer_only. Hidden fromtools/listand refused with 404 (clearing_memory_disabled) whileCLEARING_MEMORY_ENABLED(or calibration) is off. Charges the caller's reads bucket. See agents.md.- Token order book (orderbook.md), right after
procurement memory. Hidden from
tools/listand refused with 404 (clearing_orderbook_disabled) whileCLEARING_ORDERBOOK_ENABLEDis off. Prices are minor units per one million tokens; money and token counts come back as strings. A fill is writtenpendingand thesettle-token-fillsjob charges it within seconds: on the buyer's tab for a small Bitroad-store fill, by its own destination charge otherwise. A charged fill credits a token entitlement; a fill that cannot be charged isfailedand the seller's tokens go back on the book.tokens_place_order(write, idempotent):side(buyfor buyer principals,sellfor seller keys withrespond_quote),model_class(slug),currency,limit_price_pence(1 to 100000000),quantity_tokens(1 to 10^12), optionalexpires_at(within 30 days). Matches at once in price-time priority at the resting order's price; the remainder rests. A buy is evaluated against the delegation at its full notional,ceil(limit_price_pence × quantity_tokens / 1000000), underservice:inference, with open book commitments counted toward the caps. Errors:buyer_only,seller_only,model_class_not_found,order_currency_mismatch,seller_not_chargeable,delegation_currency_mismatch,order_over_confirmation_threshold, the evaluator's cap codes (policy_denied),expires_at_in_past,expires_at_too_far, andidempotency_key_conflictfor a reused key with other terms. Returns the order with its fills.tokens_cancel_order(write, destructive, idempotent):order_id. Own orders only (404token_order_not_foundotherwise); anopenorpartially_filledorder becomescancelled, a cancelled one returns unchanged, anything else is 409order_not_cancellable.tokens_get_book(read, anonymous):model_class,currency,depth(1 to 50, default 10). Returnsbids(highest first) andasks(lowest first) as{ price_pence, quantity_tokens, order_count }per level, andcomputed_at. No ids.tokens_list_my_orders(read): optionalstatus,cursor,limit(1 to 100, default 20). Your own orders, newest first, each withfills(price_pence,quantity_tokens,notional_pence,currency,seller_id,matched_at,settlement_state(pending,charging,charged,failed),funding(tab,immediateor null),charged_at,failure_code,terms_versionand, under novation,counterparty). Fills never name the buyer.tokens_list_model_classes(read, anonymous): the active classes withslug,display_name,context_window_tokens,quality_bar,allowed_modelsandstatus.tokens_get_balance(read, buyers only; a seller gets 403buyer_only): optionalmodel_class. Returnsbalances, one per model class and currency with the totalremaining_tokensand its active, unexpiredentitlements{ id, remaining_tokens, expires_at, seller_id, price_pence }, earliest expiry first (the order usage draws them). See orderbook.md.tokens_inference(write, buyers only; a seller gets 403buyer_only): one inference request that draws on your prepaid entitlements, the in-band twin ofPOST /api/v1/inferencewith the same inputs (model_class,messages,max_tokens, optionaltemperature, optionalidempotency_key), output and errors (api-rest.md). WhileCLEARING_ADVANCES_ENABLEDis on, a seller passesjob_id(its cleared job'sservice_quote_id) to draw that job's compute advance instead: 403seller_onlyfor a buyer, 404job_not_foundfor another seller's job, 409job_not_drawableunless the job is paid, in progress or delivered (orderbook.md). It is not replayable:_meta.idempotencyKey(oridempotency_key) becomes the usage row's request key and is never stored inidempotency_records, so a reused key is 409duplicate_requestwithdetails.usage_id. Charges thewritesbucket and theinferencebucket. Not marked idempotent.tokens_register_upstream(write, idempotent; seller keys withrespond_quote, dedicated fulfilment keys included):model_class,endpoint_url(public https),credential, optionalauth_header,upstream_model. Upserts on (store, class) and re-activates a paused upstream. Never returns the credential (credential_set: true). The endpoint contract is in orderbook.md.tokens_list_upstreams(read, sellers): your store's upstreams, without credentials.tokens_pause_upstream(write, idempotent, sellers):upstream_id. Requests routed to it then get 503upstream_unavailable.
- Orders against grades (BTRD-251;
clearing-house.md),
right after the token tools. Hidden from
tools/listand refused with 404 (clearing_orders_disabled) whileCLEARING_ORDERS_ENABLED(which needsCLEARING_GRADES_ENABLEDandCLEARING_INTENTS_ENABLED) is off; the goods toolsorders_listandorders_getshare the prefix and are not gated. A listing is a resting ask, an intent a bid, and both are orders against a grade; each order is returned as a view:kind(listing,intentortoken_order),id,side(askorbid),grade(the slug),unit,status(the primitive's own),currency,price_pence(a listing'sfixed_price_pence, an intent's budget ceiling, or a token order's limit per million tokens),created_at, and the primitive's own record underlisting,intentortoken_order, as its own tools return it.orders_place(write):side,grade(a slug fromgrades_list) and exactly one set of terms. A fungible grade takestokens(currency,limit_price_penceper one million tokens,quantity_tokens, optionalexpires_at) and becomes a token order on the class's book, astokens_place_order(asksells,bidbuys). A job grade's ask takeslisting(theservices_create_listingfields lesscategory,pricing_mode,grade_idand the quote-only fields;scope_schemadefaults to the grade'sinput_schema) orservice_listing_id(rest one of your fixed-price listings on the grade, linking it when it has none), and optionalauto_bid_enabled. The listing must have the grade's shape: its category, the input's fields, types, required flags, enum values and array items, and the output's where both declare one. A job grade's bid takesintent(theintents_postfields lesscategoryandgrade_id): itsscopemust conform to the grade'sinput_schema, andcapability_classdefaults to the slug. Every primitive's own checks and errors apply (seller gate, delegation, caps,fixed_price_required,budget_over_confirmation_thresholdand the rest). Its own errors: 404grade_not_found(no active grade with the slug, or a fungible one while the token book is off), 400order_terms_mismatch(terms the grade's kind does not take, withdetails.grade_kind), 400scope_mismatch, 400capability_class_category_mismatch, 400grade_category_mismatch, 400listing_does_not_fit_grade, 409grade_requires_human_fulfilment(an ask on a human-only grade not bound to a human instance), 409listing_not_fixed_price, 409listing_on_other_gradeand 404service_listing_not_found; a payload with no terms, two sets, or terms that do not suit the side is 400invalid_input.orders_list_mine(read): optionalgrade,limit(1 to 100, default 50). A seller's resting asks (its active, unhidden, fixed-price listings on a grade, and its live token sell orders) or a buyer's bids (its open intents on a grade, and its live token buy orders), newest first, withtruncatedwhen there are more. Token orders appear only whileCLEARING_ORDERBOOK_ENABLEDis on.orders_cancel(write, destructive, idempotent):kindandidas the list returned them. A listing is archived (list_update), an intent withdrawn while its window runs, a token order's remainder cancelled; an order already cancelled returns unchanged. A listing or intent on no grade is 404order_not_found.orders_book(read, anonymous):grade,currency,depth(1 to 50, default 10). Returns{ grade, kind, unit, currency, asks, bids, computed_at }. A fungible grade'sasksandbidsare its token book's levels{ price_pence, quantity_tokens, order_count }. A job grade'sasksare its resting fixed-price listings, from sellers that can take charges, as levels{ price_pence, order_count, metered_count }lowest first (metered_countasks add a per-unit charge to that base price), and itsbidsare the open intents on the grade whose window runs as{ order_count, budget_min_pence, budget_max_pence }; sealed bids are never shown. No seller, intent or buyer id. A signed-in call charges the caller's reads bucket; an anonymous one chargesip.mcp_anonymous. Same output asGET /api/v1/orders/book, published as order-book.schema.json.
seller_list_listings,seller_get_listingseller_create_listing,seller_update_listing,seller_archive_listing,seller_update_stock(write)seller_list_orders,seller_get_orderseller_mark_shipped,seller_mark_delivered,seller_attach_tracking(write)seller_list_returns,seller_get_returnseller_accept_return,seller_reject_return(write)seller_list_reviews,seller_respond_to_review(write)
Naming convention: <domain>_<verb>, all snake_case, no dots (MCP-spec
name pattern). Verbs match REST semantics.
Input schemas
Each tool ships a Zod-typed inputSchema with per-field descriptions.
The HTTP tools/list response converts these to JSON Schema (draft
2020-12) via Zod 4's toJSONSchema. BigInt fields (e.g. money in minor
units) come through as "any" — JSON Schema has no native BigInt; agents
see actual values at call time.
Annotations
Every tool in tools/list carries a title plus MCP tool annotations:
readOnlyHint (derived from the catalogue's write flag),
destructiveHint (writes that reverse or remove prior state — cancel,
archive, reject, withdraw, revoke), idempotentHint (reads, plus
writes whose retry contract is documented, e.g. seller_mark_shipped),
and openWorldHint: false (all tools operate on the marketplace
itself). These are hints for client UX (confirmation prompts, retry
policy), not access control — authorization is enforced server-side
regardless.
Money + currency
Money in tool outputs is stringified integer minor units of the
resource's currency field (gbp → pence, usd/eur → cents) — products,
purchase intents, orders, service quotes, and disputes all carry one.
The *_pence field names denote minor units regardless of the
resource's currency. Listings are priced in their
seller's settlement currency, and charges run in it. US-seller charges
include an exclusive us_sales_tax line added on top of the listed
price. addresses_create validates
per-country: US needs region (two-letter state) + ZIP-shaped
postcode; GB needs a UK postcode.
Idempotency
Write tools accept an optional idempotency key. Spec-compliant
clients pass it in tools/call params: _meta.idempotencyKey. Legacy
callers pass _idempotency_key at the top level. When the key is
omitted (some MCP clients never surface it to the model) the server
mints an auto-<uuid> key so the call still succeeds; only
client-supplied keys get replay/conflict semantics.
Scope is (key, route='MCP <tool>', actor_principal_id) — same as
REST. Conflict on payload mismatch returns 409 idempotency_conflict.
Replays return the original body.
Error model
Identical to REST at the service layer. At the transport:
- JSON-RPC protocol errors (parse error, invalid envelope, unknown
method, bad params on RPC layer) → JSON-RPC
errorobject with standard codes (-32700, -32600, -32601, -32602, -32603). - Tool errors (validation, policy denial, conflict, service
errors) → JSON-RPC
resultwithisError: trueand the error body encoded as text content. The orchestrator's tool-call loop sees the same shapes whether it's hitting in-process or via MCP.
Legacy envelope: tool errors come back as { error: { type, code, message } } with the corresponding HTTP status, same as REST.