An OpenAPI 3.1 spec is served at
GET /api/v1/openapi.json. Its path map is hand-maintained and covers the goods, services and seller routes; this document is the authoritative route list. The clearing, settlement, token, factoring, panel, verification, instance, delegation and chat routes are documented here but not yet in the spec.
Bitroad's REST surface clears work: the seller's payout is held until the
buyer accepts the delivery. An agent
searches /service-listings, buys a fixed-price service in one call or
requests a quote, Bitroad holds the payment, the seller delivers, and
the payout releases on acknowledgement. The product catalog for physical
goods (/products, /purchase-intents, /orders, /returns) runs on
the same rails and is documented after the services routes.
Conventions
- Versioned under
/api/v1/. - Money values are stringified integer minor units (bigint) of the
resource's
currencyfield (gbp→ pence,usd/eur→ cents). Products, purchase intents, orders, service quotes, and disputes all exposecurrency; the*_pencefield names denote minor units regardless of currency. - All POST/DELETE require
Idempotency-Key(there are no PATCH routes); the exceptions are listed under Idempotency. Replays return the original response. Hash mismatch returns 409idempotency_conflict. - Auth: bearer
br_pk_*(platform), bearerbr_ik_*(instance),authjs.session-tokencookie (humans), or, whileCLEARING_KEYS_ENABLEDis on, a request signed by a registered key (Authorization: Signature …, see Keys). - Errors share one envelope:
Types:{ "error": { "type": "policy_denied", "code": "per_tx_cap_exceeded", "message": "...", "details": { ... }, "request_id": "..." } }unauthenticated,forbidden,policy_denied,confirmation_required,validation,idempotency_conflict,not_found,conflict,payment_failed,payment_action_required,rate_limited,server_error.
Services marketplace
The primary flow. Search listings, buy a fixed-price service in one
call or request a quote for bespoke work, and Bitroad holds the charge
in escrow until the buyer acknowledges the deliverable. Every route
below returns 404 while SERVICES_ENABLED is off (it is on in
production).
Discovery (any commerce actor):
GET /api/v1/service-listings— active-listing search (q,category,pricing_mode, cursor pagination).?mine=truereturns the calling seller's own listings (any status).GET /api/v1/service-listings/{id}.
Buyer:
POST /api/v1/service-listings/{id}/purchase— fixed-price one-call purchase; creates the quote thread directly inacceptedand charges immediately. With the tab on, a sub-threshold job from the Bitroad store accrues on the buyer's settlement cycle instead (funding: "tab", see services.md). Every service quote response carriesfunding(immediateortab) andsettlement_cycle_id, andterms_version, the version of Bitroad's terms the job was made under (BTRD-258, the protocol'sjob-terms.schema.json). A job that cleared whileCLEARING_NOVATION_ENABLEDwas on also carriescounterparty: "house"; otherwise the key is absent. WhileCLEARING_OPEN_SELLERS_ENABLEDis on, 409seller_ceiling_reachedwhen the job would take the seller past its pending-credit ceiling (clearing-house.md).POST /api/v1/service-quotes— request a quote against a quote-mode listing;scopevalidated against the listing's scope schema.GET /api/v1/service-quotes— list mine (filterstatus,service_listing_id,kind:quoteorintent). Includes open intents, whoseservice_listing_idandseller_idare null.GET /api/v1/service-quotes/{id}— detail incl. deliverables (party-scoped; secret payloads decrypt buyer-side only).POST /api/v1/service-quotes/{id}/accept— accept + charge. Cap kickbacks return 409confirmation_requiredwith a token; re-accept withacknowledged_confirmation: true+confirmation_token. 409seller_ceiling_reachedas for a purchase.POST /api/v1/service-quotes/{id}/reject— buyer rejects a quote; also how the principal denies apending_principal_confirmationthread.POST /api/v1/service-quotes/{id}/withdraw— before quoted, or anopenintent while its bid window runs.POST /api/v1/service-quotes/{id}/acknowledge-delivery— releases the held payout immediately. On a quote with an acceptance block it returns the current state after a passing check, and overrides afail,errororpendingverdict (services.md).
Seller (delegation actions in parentheses):
POST /api/v1/service-listings— create (list_create). Optionaloutput_schemaandacceptanceattach machine acceptance terms. Optionalgrade_idnames the job grade the listing is an ask on, whileCLEARING_GRADES_ENABLEDis on (Grades); 404grade_not_found, 400grade_kind_mismatchorgrade_category_mismatchotherwise. Ignored while the flag is off, but always a UUID (400invalid_inputotherwise). A listing on a human-only grade (fulfilment: "human") must bind afulfillment_instance_idwhose fulfilment kind is human (409grade_requires_human_fulfilment); an update that activates or rebinds such a listing is held to the same rule. Binding a human instance needs a business seller (409human_fulfilment_requires_business, legal hold L13; agents.md). Optionalauto_bid_enabled(default true) says whether a fixed-price listing on a grade bids its list price by itself on open intents on the grade (services.md); honoured whileCLEARING_ORDERS_ENABLEDis on, ignored while it is off. WhileCLEARING_OPEN_SELLERS_ENABLEDis on, a seller whose Connect account exists may list before Stripe onboarding completes, and an unrated seller's listing needs a machine-checkableacceptanceblock (400acceptance_required_for_unrated_seller; also refused on an update that clears it).POST /api/v1/service-listings/{id}— update incl. status flips (list_update).output_schemaandacceptanceare kept when omitted and cleared withnull; quotes already created keep their snapshot.auto_bid_enabledis kept when omitted, and honoured only whileCLEARING_ORDERS_ENABLEDis on.
While CLEARING_GRADES_ENABLED is on, every listing and quote response
(and each GET /api/v1/service-intents/open entry) carries grade_id and
grade_slug, both null when it names no grade; while it is off neither key
appears. A seller's own listing responses carry auto_bid_enabled while
CLEARING_ORDERS_ENABLED is on.
GET /api/v1/sellers/me/service-quotes— incoming threads;?status=requestedis the open-requests poll.POST /api/v1/service-quotes/{id}/quote— submit price + ETA + terms (respond_quote).POST /api/v1/service-quotes/{id}/start—paid → in_progress(respond_quote).POST /api/v1/service-quotes/{id}/deliver— JSON body;kindofurl/text/secretinline,filevia base64file_b64+file_name+file_mime_type(≤ 25 MB, lands on R2) (respond_quote). On a quote with an acceptance block the deliverable comes backacceptance_verdict: pending.
Admin (is_admin principal session):
POST /api/v1/admin/service-quotes/{id}/cancel—reasonrequired; refunds in full when the thread was charged.POST /api/v1/admin/service-quotes/{id}/force-release—deliveredthreads only.POST /api/v1/admin/sellers/{id}/tier— override a seller's verification tier (basic,verified,premium).GET /api/v1/admin/anomaly-pausesandPOST /api/v1/admin/instances/{id}/lift-pause— the anomaly pause queue (anomaly.md). The full admin list is in admin.md.
Open intents (feature-flagged)
A buyer agent posts a job without naming a listing
(services.md). The routes return 404 unless
CLEARING_INTENTS_ENABLED and SERVICES_ENABLED are on. The MCP twin
is intents_post; sellers bid through intents_list_open and
intents_bid (api-mcp.md).
POST /api/v1/service-intents(principal_selforagent_instance, buyer principals only): post an open intent. Body:category, optionalcapability_class,scope, optionaloutput_schemaandacceptance,budget_ceiling_pence,currency(required unless the delegation is pinned),deadline_at(ISO 8601),bid_window_seconds(10 to 3600, default 60), optionalclient_intent_refandrequested_summary, and an optionalgrade_id(as on a listing, Grades).Idempotency-Keyrequired; writes oneintent.postaudit row. Returns the quote thread with statusopen. Errors: 403buyer_only, 403policy_denied(the evaluator's reason, orseller_allowlist_blocks_open_intents), 409budget_over_confirmation_threshold, 409delegation_currency_mismatch, 409client_intent_ref_conflict, 400currency_required,deadline_before_bid_window,deadline_too_far,acceptance_kind_disabled,acceptance_verifier_repeated,schema_match_requires_output_schema,scope_too_large,grade_kind_mismatch,grade_category_mismatch, and 404grade_not_found.GET /api/v1/service-quotes?kind=intent: list my intents (above). The detail read (GET /api/v1/service-quotes/{id}) addsbid_countfor the buyer (a count, never an amount) andwinning_bidfor the winning seller after the clear.GET /api/v1/service-intents/open(seller,respond_quote): open intents whose bid window is running, in the caller's settlement currency and in a category where it has an active listing. Querycategory,cursor,limit(1 to 100, default 20). Each intent carriesscope,output_schema,acceptance,budget_ceiling_pence,currency,deadline_at,bid_window_closes_atandmy_bid(the caller's own sealed bid, or null). No buyer identity. Oneintent.list_openaudit row.POST /api/v1/service-intents/{id}/bids(seller,respond_quote): place or replace the caller's sealed bid. Body:amount_pence,eta_minutes, optionalconfidence_bp(0 to 10000) and optionalservice_listing_id.Idempotency-Keyrequired; the path id is part of the hashed payload, so one key cannot replay across two intents. Oneintent.bidaudit row. Errors: 404intent_not_found, 409intent_not_open, 409bid_window_closed, 409bid_currency_mismatch, 400bid_over_budget, 400bid_eta_exceeds_deadline, 403no_active_listing_in_category, 404service_listing_not_found, 400listing_category_mismatch, 403not_fulfiller, 403policy_denied(seller_action_not_allowed), 409seller_ceiling_reachedwhileCLEARING_OPEN_SELLERS_ENABLEDis on, 409grade_requires_human_fulfilmenton an intent on a human-only grade unless the instance the bid fulfils under (the named listing's bound instance, else the caller) is human, and 409human_fulfilment_requires_businessfor a human instance of a seller that is not a business (L13).GET /api/v1/admin/intents/demand(admin principal session): the demand log. Querysince,until(ISO 8601, default the last 30 days by post time) andcurrency. Returnssince,untilandrows, one per category, capability class and currency, each withunfilled_count,distinct_principals,median_budget_ceiling_pence(string, an actual ceiling from the group),by_reasonandearliest_posted_at/latest_posted_at. No buyer identities.
Independent verifiers (feature-flagged)
Every route 404s while CLEARING_VERIFIERS_ENABLED is off (BTRD-259;
services.md). Seller side,
gated by the delegation's respond_quote action. The MCP twins are
verifications_list_open, verifications_claim and
verifications_submit_verdict (api-mcp.md).
GET /api/v1/verifications/open: open verification jobs the caller may take. Querylimit(1 to 100, default 50). Returns{ standing_bp, verifications }; each verification carries the job's terms (scope,output_schema,category,capability_class),verifier_class,min_calibration_bp,fee_pence,currencyandclaim_deadline_at, anddeliverable: null. Oneverification.list_openaudit row.POST /api/v1/verifications/{id}/claim: claim one. Empty body;Idempotency-Keyrequired. Returns the verification with thedeliverableanddecide_deadline_at. Errors: 404verification_not_found, 409verifier_not_independent,verifier_calibration_too_low,verification_superseded,verification_not_open,verification_expired.POST /api/v1/verifications/{id}/verdict: the claimant's verdict. Bodyverdict(passorfail) andreason(1 to 2000 chars);Idempotency-Keyrequired. Errors: 404verification_not_found, 409verification_decided,verification_not_claimed,verification_expired.
Factoring (feature-flagged)
Every route 404s while CLEARING_FACTORING_ENABLED is off (BTRD-262;
ledger.md). Seller side, gated by the delegation's
respond_quote action. {id} is the service quote id of the seller's own
job. The MCP twins are factoring_quote and factoring_sell
(api-mcp.md), which describe the shapes and the refusal
reasons.
GET /api/v1/factoring/jobs/{id}/quote: what the house would pay now for the job's pending credit. Errors: 400invalid_id, 404service_quote_not_found, 409factoring_not_eligible(details.reason). Onefactoring.quoteaudit row.POST /api/v1/factoring/jobs/{id}/sell: sell it. Empty body;Idempotency-Keyrequired. Returns the factored credit (state: "open"); a repeat on the same job returns it. Errors: 404service_quote_not_found, 409factoring_not_eligible,factoring_ceiling_reached(details.ceiling:sellerorhouse).
Clearing (feature-flagged)
The external clearing API for venues (BTRD-266;
venues.md). Every route 404s while CLEARING_VENUES_ENABLED
is off. Authenticated by a venue key only: Authorization: Bearer br_vk_…,
or a request signed by the venue's registered Ed25519 key
(signed-request.md). Any other credential is
403 actor_kind_not_permitted; a suspended venue or owner is 401
venue_suspended. Each venue draws on its own venue.writes /
venue.reads buckets at its tier (see Rate limits), and
every call writes one audit_log row with actor kind venue. Bodies are
capped at 64 KiB. Money in responses is integer minor units as strings.
POST /api/v1/clearing/jobs: send a matched job. Body (venue-job-input.schema.json):venue_job_ref,buyer_authorisation_id(from the buyer'svenues_authorise),seller_slug(its register entry),grade_slug(an active job grade),scope(conforms to the grade's input schema),acceptance(kinds the grade supports),price_pence,currency,deadline_at, optionalsummary. Charges the buyer as the authorising agent under its current delegation. 201 with the job (venue-job.schema.json), whosestatesays how the charge went (paid,pending_principal_confirmation,cancelledon a decline); 200 with the same job whenvenue_job_refalready names it.Idempotency-Keyoptional and honoured. Errors: 400invalid_input,deadline_in_past,acceptance_kind_not_in_grade,schema_match_requires_output_schema,scope_mismatch,fees_exceed_price; 403policy_deniedcodes from the buyer's delegation; 404grade_not_found,seller_not_found,venue_authorisation_not_found; 409venue_job_ref_conflict,venue_authorisation_revoked,venue_cap_exceeded(details.cap_pence,details.spent_pence),currency_mismatch,seller_not_payable,seller_ceiling_reached,buyer_mandate_unavailable.GET /api/v1/clearing/jobs/{id}: one of the venue's jobs:state,acceptance(the latest deliverable'sverdict,checked_at,buyer_acknowledged; null before the first),payout_state(not_charged,held,released,refunded),fees(application_fee_pence,platform_fee_pence,venue_fee_pence,verifier_fee_pence,advance_repayment_pence),venue_fee_state(pending,owed,paid,void),terms_versionand, while novation is on,counterparty. 404venue_job_not_foundfor another venue's job.POST /api/v1/clearing/jobs/{id}/cancel: cancel before delivery, frompending_principal_confirmation,paidorin_progress; a charged job is fully refunded first. Empty body; idempotent, andIdempotency-Keyhonoured. Returns the job. 409venue_job_not_cancellablefrom delivery on.
Member panel (feature-flagged)
Every route 404s while CLEARING_PANEL_ENABLED is off (BTRD-260;
disputes.md). Any buyer or seller principal
(principal_self or agent_instance): a panelist is a member, not a
seller. The MCP twins are panel_list_open, panel_get_case and
panel_vote (api-mcp.md); the case shape, blind to the
parties, is described there.
GET /api/v1/panel/open: open cases the caller may sit on. Querylimit(1 to 100, default 50). Returns{ member, cases };memberis false andcasesempty below the member threshold. Onepanel.list_openaudit row.GET /api/v1/panel/{id}: one case, to a member who may sit on it while it is open or to a panelist who voted on it. Errors: 400invalid_id, 404panel_case_not_found.POST /api/v1/panel/{id}/vote: cast a vote. Bodyvote(releaseorrefund) andreason(1 to 2000 chars);Idempotency-Keyrequired. The vote that completes the quorum of 3 decides by majority and applies the decision. Errors: 404panel_case_not_found, 409panel_vote_cast,panelist_not_eligible,panel_case_not_open,panel_case_expired.
Settlement cycles (feature-flagged)
A buyer's settlement cycles: card holds that carry sub-threshold
jobs on a tab (ledger.md). Both routes
return 404 unless CLEARING_TAB_ENABLED, CLEARING_LEDGER_ENABLED and
SERVICES_ENABLED are all on. Cycles are opened by the purchase path,
not by a route, except a prepaid cycle, which a top-up opens. The MCP
twins are settlement_list_cycles, settlement_contest_job and
settlement_top_up (api-mcp.md).
Buyer (principal_self or agent_instance):
GET /api/v1/settlement-cycles: list mine (filterstatus,currency;page_size1 to 100, default 20;cursoris the previous page'snext_cursor).GET /api/v1/settlement-cycles/{id}: one of mine. Another principal's cycle is 404.POST /api/v1/settlement-cycles/{id}/capture: capture now (ledger.md). Closes anopencycle with reasonprincipal_request, or brings aclosedcycle'scapture_due_atforward to now; the worker captures it within a minute. Returns the cycle. Empty body,Idempotency-Keyrequired. A cycle already capturing or captured returns unchanged; anopencard-hold cycle with nothing accrued is 409settlement_cycle_nothing_accrued. On a prepaid cycle it closes the balance, even with nothing spent, and the unused rest is refunded.POST /api/v1/settlement-cycles/top-up: start a Pay by Bank top-up of a prepaid balance (ledger.md). 404 unlessCLEARING_PREPAID_ENABLEDand the tab flags are on and seller sign-up is locked. Body{ "amount_pence": 1000, "currency": "gbp" }(amount_pencea positive integer or digit string, 50 toCLEARING_PREPAID_MAX_TOPUP_MINOR, default 10000;currencyoptional, GBP only),Idempotency-Keyrequired. Optional"rail":"pay_by_bank"(the default) or"usdc", a USD top-up paid in USDC through Stripe (payments.md);usdc404sclearing_stablecoin_disabledunlessCLEARING_STABLECOIN_ENABLEDis on, and takes USD only (the default currency for that rail). Returns{ settlement_cycle, checkout_url }: the cycle inauthorisingand the hosted page to send the buyer to (null once paid). Errors: 400prepaid_currency_unsupported,prepaid_top_up_too_small,prepaid_top_up_too_large; 409prepaid_top_up_pending(another top-up's page is still payable;details.checkout_urlis that page), 409prepaid_balance_active(one open balance per currency at a time), 409tab_disabled; 403buyer_only.POST /api/v1/service-quotes/{id}/contest: take one tab job off the tab before capture (ledger.md). Body{ "reason": "…" }(1 to 500 characters, shown to the seller),Idempotency-Keyrequired. Returnsservice_quote_id,status(refunded),refund_id,refunded_pence,currency,settlement_cycle_idandcycle_accrued_pence. Errors: 409contest_window_closedonce the cycle is capturing or later (file a dispute instead), 409quote_not_on_tab, 409quote_not_contestable, 403buyer_only, 429tab_contest_rate_limited.
The path id is part of the hashed idempotency payload on both writes, so one key cannot replay across two cycles or quotes.
Each cycle carries id, currency, funding, status,
payment_method_id, exposure_limit_pence, authorised_pence,
accrued_pence, captured_pence, refunded_pence,
settlement_cost_pence, remaining_pence, collection_status and
prepaid_remainder_pence (amounts as strings of minor units; captured
and settlement_cost are null until known; remaining_pence is a
prepaid or Bacs cycle's headroom, null on a card-hold cycle;
prepaid_remainder_pence is what a prepaid cycle refunded when it
finished; collection_status is a Bacs cycle's Direct Debit,
processing, succeeded or failed, null otherwise), funding is
card_hold, prepaid or bacs, opened_at, closes_at,
capture_due_at, capture_reason, captured_at, settled_at,
failed_at, failure_code and dispute_hold_at. Stripe ids are not
returned.
The detail read also returns jobs, one entry per job accrued on the
cycle, oldest first:
| Field | Notes |
|---|---|
service_quote_id |
The quote thread |
listing_title |
The service listing's title, or null |
paid_at |
When the job accrued |
status |
The quote's status |
amount_pence |
The charge total that accrued: price plus any exclusive US sales tax |
refunded_pence |
Non-failed refunds on the quote |
credit_state |
Where the seller credit sits: pending_verification, releasable, pending_settlement, settled, or reversed when nothing is left |
Pricing oracle (feature-flagged)
GET /api/v1/pricing-oracle: what jobs shaped like this cleared at
(reputation.md). Public: no
credentials, metered per client IP under ip.public_reads, and
Cache-Control: public, max-age=300. Returns 404
clearing_oracle_disabled unless CLEARING_ORACLE_ENABLED,
CLEARING_CALIBRATION_ENABLED and SERVICES_ENABLED are all on. The
MCP twin is pricing_oracle (api-mcp.md), with the same
output.
Query parameters:
| Parameter | Required | Notes |
|---|---|---|
category |
yes | A service category |
capability_class |
no | Exact class; its first segment must equal category. Omit for the whole category |
currency |
yes | gbp, usd or eur. Figures never mix currencies |
window_days |
no | 1 to 365, default 90 |
rail |
no | intent, listing or all (default) |
clearing_rule |
no | best_bid or second_price: only intent-cleared jobs under that rule. Refused with rail=listing; fill_rate_bp is null under it |
The body echoes the query (with clearing_rule null when omitted) and carries sample_size, min_sample,
published, fill_rate_bp, clearing_price ({p10, p50, p90},
strings of minor units), median_minutes_to_delivery,
first_pass_accept_bp, dispute_rate_bp, outcome_mix
(released_bp, refunded_bp, cancelled_bp), funding_mix
(immediate_bp, tab_bp) and computed_at. Below the minimum sample
every figure is null. No seller, quote or buyer id is ever returned. A
bad query is 400 invalid_query with the Zod issues in details.
Price index
The daily, signed price index: what each grade of work cost on Bitroad,
per currency (clearing-house.md). This
section is also the index's public methodology; every document links
here. The heading carries no "(feature-flagged)" so that link stays
stable, but every route returns 404 clearing_index_disabled unless
CLEARING_INDEX_ENABLED, CLEARING_CALIBRATION_ENABLED and
SERVICES_ENABLED are all on. Public: no credentials, metered per client
IP under ip.public_reads, and Cache-Control: public, max-age=300. The
MCP twins are the index_get tool and the bitroad://index/latest
resource (api-mcp.md), with the same output.
| Route | Notes |
|---|---|
GET /api/v1/index |
The latest published day, or ?date=YYYY-MM-DD for a given UTC day. Returns { as_of_date, entries }, ordered by kind, class and currency. An impossible date is 400 invalid_query; a day with no index, or no index published yet, is 404 index_not_found |
GET /api/v1/index/{kind}/{class} |
One grade over the 30 most recent as-of days, newest first: { kind, class, entries }. kind is service or tokens; class is a lowercase dotted path (a category, capability class or token model class). A bad kind or class is 400 invalid_class; a grade with no entries returns an empty list |
GET /api/v1/index/key |
The key that signs the index: algorithm (ed25519), key_id, public_key (base64 of the raw 32-byte key) and public_key_pem. 404 index_key_not_configured while the index is published unsigned |
Each entry is { document, signature }. signature is the base64
Ed25519 signature over the document's canonical JSON, or null while the
index is published unsigned.
Methodology
- Publication. Once per UTC day, after 01:00 UTC, for the previous
day (
as_of_date). Every window ends at 00:00 UTC after that day, so the figures for a day do not depend on when they were computed. - Service entries (
kind: service), over the 30 days before the close. A grade is a service category, covering every job in it, or a capability class of two or more segments, covering that class exactly. The figures are the pricing oracle's definitions:cleared_price({ p25, p50, p75 },percentile_discover released and refunded jobs, strings of minor units;p50is the median),median_delivery_seconds(released jobs, one-minute resolution),first_pass_accept_bp(jobs with an acceptance verdict that passed first time) andunfilled_demand(intents posted in the window that ended unfilled).human_machine_spreadis thep50cleared price of the grade's human-fulfilled jobs minus that of its machine-fulfilled jobs, a signed string of minor units (negative when people are cheaper), once each fulfilment kind has at leastCLEARING_INDEX_MIN_SAMPLEjobs in the window and a cleared price, andnullotherwise. Who fulfilled a job is the kind snapshotted with its fulfilment fingerprint (agents.md). - Token entries (
kind: tokens), over the 24 hours of the as-of day, per model class: charged fills only.vwap_price_pence(volume-weighted average price per one million tokens, rounded half up),last_price_pence,fill_countandtotal_tokens(a string). - Minimum sample. An entry is
published: trueonly with at leastCLEARING_INDEX_MIN_SAMPLE(default 10) jobs or fills behind it. Below that it carriessample_sizeand no figure. No document carries a seller, buyer, quote, order or fill id.
Every document also carries version (v0), as_of_date, kind,
class, currency, window ({ from, to }), sample_size,
min_sample, published, methodology_url (this section), statement,
signer ({ algorithm, key_id }, or null while unsigned) and
computed_at. A service document whose class is an active job grade's
slug also carries grade_slug and grade_version while
CLEARING_GRADES_ENABLED is on (Grades).
{
"document": {
"version": "v0",
"as_of_date": "2026-11-02",
"kind": "service",
"class": "synthetic_data.tabular",
"currency": "gbp",
"window": { "from": "2026-10-04T00:00:00.000Z", "to": "2026-11-03T00:00:00.000Z" },
"sample_size": 12,
"min_sample": 10,
"published": true,
"cleared_price": { "p25": "300", "p50": "500", "p75": "800" },
"median_delivery_seconds": 3000,
"first_pass_accept_bp": 8000,
"unfilled_demand": 2,
"human_machine_spread": null,
"methodology_url": "https://bitroad.ai/docs/api-rest#price-index",
"statement": "This index is published for information only. …",
"signer": { "algorithm": "ed25519", "key_id": "<64 hex>" },
"computed_at": "2026-11-03T01:00:04.000Z"
},
"signature": "<base64>"
}
Verify a document
The signature covers the UTF-8 bytes of the document's canonical JSON:
keys sorted by UTF-16 code unit at every depth, no whitespace, and
strings, integers, booleans and null as JSON writes them. For these
documents that is RFC 8785 (JCS), so a JCS library rebuilds the same
bytes. Check that document.signer.key_id equals the key's key_id,
then verify the signature with the public key. With jq and OpenSSL 3:
curl -s https://app.bitroad.ai/api/v1/index/key | jq -r .public_key_pem > index-key.pem
curl -s https://app.bitroad.ai/api/v1/index > index.json
jq -cjS '.entries[0].document' index.json > doc.json
jq -r '.entries[0].signature' index.json | base64 -d > doc.sig
openssl pkeyutl -verify -pubin -inkey index-key.pem -rawin -in doc.json -sigfile doc.sig
jq -cjS writes sorted, compact JSON, which matches the canonical form
here because every key is ASCII and every number is a small integer.
Statement
Every document carries this statement:
This index is published for information only. It is not a benchmark within the meaning of the UK Benchmarks Regulation and may not be used to determine the amount payable under any financial instrument or financial contract.
Default fund (feature-flagged)
GET /api/v1/default-fund: the member default fund's public statement
(ledger.md). Returns 404
default_fund_disabled unless CLEARING_DEFAULT_FUND_ENABLED,
CLEARING_LEDGER_ENABLED and SERVICES_ENABLED are all on. Public: no
credentials, metered per client IP under ip.public_reads, and
Cache-Control: public, max-age=300. The MCP twin is default_fund_get
(api-mcp.md), with the same output. The wire shape is
published as docs/protocol/schemas/default-fund-statement.schema.json.
| Field | Notes |
|---|---|
as_of |
When the figures were read, ISO 8601 UTC |
contribution_rate_bps |
The share of each cleared job's platform fee credited to the fund, in basis points of the fee (1000 = 10%) |
funds |
One entry per currency, gbp, usd and eur in that order. Balances are never summed across currencies |
funds[].balance_minor |
What the fund holds, in minor units, as a string |
funds[].contributions_minor |
Contributions to date, net of contributions reversed with a refunded fee |
funds[].draws_minor |
What the fund has absorbed to date |
funds[].draw_count |
How many draws it has made |
statement |
The fixed statement below, word for word |
The Bitroad default fund is a discretionary loss-absorption pool funded from part of Bitroad's clearing fees. It is not an insurance product, a deposit guarantee or a promise of cover. Bitroad may draw on it to absorb a loss that a seller's own credit and bond do not cover; no buyer, seller or member has a right to a payment from it.
Grades (feature-flagged)
The published grades: contracts for classes of work that orders are placed
against (clearing-house.md). Public: no
credentials, metered per client IP under ip.public_reads, and
Cache-Control: public, max-age=300. Every route returns 404
clearing_grades_disabled unless CLEARING_GRADES_ENABLED and
SERVICES_ENABLED are on. The MCP twins are the grades_list tool and the
bitroad://grades resource (api-mcp.md), with
the same output as GET /api/v1/grades.
| Route | Notes |
|---|---|
GET /api/v1/grades |
{ grades }: the active grades by slug, one version each (the newest; an older one is retired) |
GET /api/v1/grades/{slug} |
{ slug, versions }: every version of one slug, newest first, active and retired. An unknown slug is 404 grade_not_found; a slug that is not two to four lowercase dotted segments is 400 invalid_slug |
The fungible grades (inference.large, inference.small) mirror the token
model classes, so both routes include them only while
CLEARING_ORDERBOOK_ENABLED is on too; otherwise a fungible slug is 404
grade_not_found.
Each grade carries exactly these fields, published as grade.schema.json:
| Field | Notes |
|---|---|
id |
This version's id: pass it as grade_id on a listing or an intent |
slug, version |
Stable dotted name and version, from 1. A job grade's slug is also a capability class; a fungible grade's is its token model class |
kind |
job (one unit of work per order) or fungible (divisible units on a continuous book) |
title, description |
Plain text |
input_schema |
The scope DSL an order's scope conforms to |
output_schema |
The scope DSL of the deliverable, or null when the grade does not type it |
acceptance_kinds |
The acceptance checks an order on the grade can carry: schema_match, hash_commitment, deterministic_check. Empty for a fungible grade |
sla_seconds |
Most seconds from charge to delivery, or null |
unit |
job or million_tokens |
fulfilment |
Who may fill an order on the grade: any seller instance, or human only, for work only a person can do. Every grade published today is any |
status |
active or retired |
created_at |
When the version was published |
No price, currency or fee appears: price lives on orders.
{
"grades": [
{
"id": "…",
"slug": "code_review.general",
"version": 1,
"kind": "job",
"title": "Code review",
"description": "An independent review of code the buyer supplies, …",
"input_schema": {
"artefact_url": { "type": "string", "required": true, "max_length": 2000, "description": "…" },
"focus": { "type": "enum", "required": true, "values": ["correctness", "security", "performance", "maintainability", "full"] },
"…": "…"
},
"output_schema": { "findings": { "type": "array", "required": true, "max_items": 500, "items": { "…": "…" } }, "…": "…" },
"acceptance_kinds": ["schema_match", "deterministic_check"],
"sla_seconds": 7200,
"unit": "job",
"fulfilment": "any",
"status": "active",
"created_at": "2026-11-04T06:00:00.000Z"
}
]
}
Procurement memory (feature-flagged)
GET /api/v1/procurement-memory: the calling principal's own
procurement history per capability class
(agents.md). Authenticated (a buyer's
session or instance key; principal_self and agent_instance actors),
metered under the caller's reads bucket. A seller principal gets 403
buyer_only. Returns 404 clearing_memory_disabled unless
CLEARING_MEMORY_ENABLED, CLEARING_CALIBRATION_ENABLED and
SERVICES_ENABLED are all on. The MCP twin is procurement_memory_get
(api-mcp.md), with the same output.
Query parameters:
| Parameter | Required | Notes |
|---|---|---|
category |
no | A service category |
capability_class |
no | Exact class; with category, its first segment must equal it |
currency |
no | gbp, usd or eur. Figures never mix currencies |
window_days |
no | 1 to 365, default 180 |
limit |
no | Jobs in first_pass_history, 1 to 50, default 10 |
The body carries window_days, computed_at, truncated,
preferred_sellers, standing_terms and first_pass_history; field
definitions are in agents.md. Money is
strings of minor units. Only the caller's own quote ids appear; no
other buyer's id is ever returned. A bad query is 400 invalid_input.
Token order book (feature-flagged)
The limit order book for inference tokens (orderbook.md).
Every route returns 404 clearing_orderbook_disabled unless
CLEARING_ORDERBOOK_ENABLED and SERVICES_ENABLED are on. Prices are
minor units per one million tokens; money and token counts are strings
in responses. A fill is charged by the settle-token-fills job and
credits a token entitlement (orderbook.md). The MCP twins
are the tokens_* tools (api-mcp.md), with the same
inputs and outputs.
| Route | Auth | Notes |
|---|---|---|
POST /api/v1/token-orders |
Session or instance key; Idempotency-Key required |
Body: side, model_class, currency, limit_price_pence, quantity_tokens, optional expires_at. Matches at once and returns the order with its fills. Each fill carries terms_version, and counterparty: "house" when matched while CLEARING_NOVATION_ENABLED was on (BTRD-258) |
GET /api/v1/token-orders |
Session or instance key | Your own orders with fills, newest first. Query: status, cursor, limit |
POST /api/v1/token-orders/{id}/cancel |
Session or instance key; Idempotency-Key required |
Own orders only (404 otherwise). Empty body |
GET /api/v1/token-book |
None, metered per IP under ip.public_reads |
Query: model_class, currency, depth (1 to 50, default 10). Price-level aggregates only. Cache-Control: no-store. A bad query is 400 invalid_query |
GET /api/v1/token-model-classes |
None, metered per IP under ip.public_reads |
The active classes. Cache-Control: public, max-age=300 |
GET /api/v1/token-entitlements |
Session or instance key; buyers only (403 buyer_only) |
Your prepaid token balance: balances per model class and currency, each with its active entitlements { id, remaining_tokens, expires_at, seller_id, price_pence }, earliest expiry first. Query: optional model_class. The MCP twin is tokens_get_balance |
POST /api/v1/token-upstreams |
Session or seller key with respond_quote; Idempotency-Key required |
Register or replace your store's upstream for one model class. Body: model_class, endpoint_url (public https), credential, optional auth_header (authorization_bearer or x_api_key), upstream_model (one of the class's allowed_models). The credential is never returned: the response says credential_set: true. Errors: seller_only, invalid_upstream_url (with the guard's reason), upstream_model_not_allowed, model_class_not_found. MCP twin tokens_register_upstream |
GET /api/v1/token-upstreams |
Session or seller key with respond_quote |
Your store's upstreams, without credentials. MCP twin tokens_list_upstreams |
POST /api/v1/token-upstreams/{id}/pause |
Session or seller key with respond_quote; Idempotency-Key required |
Pause one of your upstreams (404 token_upstream_not_found for another store's). Register again to re-activate. MCP twin tokens_pause_upstream |
POST /api/v1/inference |
Session or buyer instance key / OAuth token; buyers only (403 buyer_only), or a seller with job_id while CLEARING_ADVANCES_ENABLED is on |
Metered inference against your prepaid entitlements, or your job's compute advance, below |
Metered inference
POST /api/v1/inference spends token entitlements
(orderbook.md). It is a hand-rolled route on
the API host (every /api path is host-agnostic, so it answers on
app.bitroad.ai), 404 clearing_orderbook_disabled with the flag off.
- Body.
model_class;messages, 1 to 200 of{ role: system | user | assistant, content }with content up to 100 000 characters and at least one non-system message;max_tokens(1 to 8192); optionaltemperature(0 to 2); optionalidempotency_key; optionaljob_id(uuid). The whole body is at most 4 MB (413body_too_large). - Compute advances. While
CLEARING_ADVANCES_ENABLEDis on, a seller names its cleared job withjob_idto draw the compute advance the house bought for it (403seller_onlyfor a buyer, 404job_not_foundfor another seller's job, 409job_not_drawableunless the job is paid, in progress or delivered). With the flag offjob_idis ignored (orderbook.md). - Idempotency. The
Idempotency-Keyheader is optional and wins overidempotency_keyin the body; without either an auto key is used. The key is unique per buyer on thetoken_usagerow. The response carries the completion, so it is never stored for replay: reusing a key is 409duplicate_requestwithdetails.usage_id, whatever the earlier request's outcome. Retry a failed request under a new key. - Response (200).
{ id, model_class, seller_id, content, usage: { tokens_in, tokens_out, tokens_billed, partial_billing }, entitlement: { id, remaining_tokens } }, token counts as strings.idis the usage row. - Errors. 402
no_entitlement(buy tokens withPOST /api/v1/token-ordersfirst); 409insufficient_entitlementwhen the estimated input plusmax_tokensis more than any one entitlement holds (nothing is drawn; split the call); 409duplicate_request; 429rate_limitedfromwritesor theinferencebucket; 502upstream_error(the upstream failed; nothing billed, no upstream text echoed); 503upstream_unavailable(no active upstream, a paused one, a URL the SSRF guard now refuses, or the Bitroad store withoutORDERBOOK_PROVIDER_API_KEYor over the daily AI cap). Both 5xx carrydetails.usage_id. - Rate limits. The actor's
writesbucket, then the dedicatedinferencebucket (below). - Audit. One
inference.requestrow per call (the route) and, for every request that reached routing, oneinference.callrow in the usage transaction with the actor triple anddecision_reason usage:<id>. - No streaming.
Orders (feature-flagged)
Orders against grades (clearing-house.md,
BTRD-251): a listing is a resting ask and an intent is a bid. Each order is
an existing primitive, so these routes are thin wrappers: a fungible grade's
order is a token order on its class's book (Token order book),
a job grade's ask a fixed-price listing on the grade and its bid an open
intent on it (Open intents). Every route
returns 404 clearing_orders_disabled unless CLEARING_ORDERS_ENABLED,
CLEARING_GRADES_ENABLED, CLEARING_INTENTS_ENABLED and SERVICES_ENABLED
are on; a fungible grade also needs CLEARING_ORDERBOOK_ENABLED (404
grade_not_found otherwise). The goods routes GET /api/v1/orders and
GET /api/v1/orders/{id} are unchanged and not gated. The MCP twins are
the orders_* tools (api-mcp.md), with the same inputs and
outputs.
| Route | Auth | Notes |
|---|---|---|
POST /api/v1/orders/place |
Session or instance key; Idempotency-Key required |
Body: side (ask or bid), grade (a slug) and one set of terms: tokens for a fungible grade; listing (a new fixed-price listing; scope_schema defaults to the grade's input schema) or service_listing_id (rest one of yours), with optional auto_bid_enabled, for a job grade's ask; intent for a job grade's bid. Returns the order view. One order.place audit row |
GET /api/v1/orders/mine |
Session or instance key | Your resting orders on grades, newest first: a seller's graded fixed-price listings and live token sells, or a buyer's open graded intents and live token buys. Query: grade, limit (1 to 100, default 50). Returns { orders, truncated } |
POST /api/v1/orders/cancel |
Session or instance key; Idempotency-Key required |
Body: kind (listing, intent or token_order) and id, as the list returned them. Archives the listing, withdraws the intent or cancels the token order; one already cancelled returns unchanged. 404 order_not_found for a listing or intent on no grade |
GET /api/v1/orders/book |
None, metered per IP under ip.public_reads |
Query: grade, currency, depth (1 to 50, default 10). One grade's book, aggregates only. Cache-Control: no-store. A bad query is 400 invalid_query, an unknown grade 404 grade_not_found |
An order view carries kind, id, side, grade (the slug), unit
(job or million_tokens), status (the primitive's own), currency,
price_pence (a listing's fixed_price_pence, an intent's
budget_ceiling_pence, or a token order's limit_price_pence per one
million tokens), created_at, and the primitive's own response under
listing, intent or token_order. The terms are the primitive's inputs
less what the grade fixes, and the primitive's checks and errors apply. The
grade adds its contract: a bid's scope must conform to the grade's
input_schema (400 scope_mismatch) and capability_class defaults to
the slug (400 capability_class_category_mismatch for one in another
category); an ask must have the grade's shape (400
grade_category_mismatch or listing_does_not_fit_grade) and, on a
human-only grade, a human fulfilment instance (409
grade_requires_human_fulfilment). Resting a
listing also refuses 409 listing_not_fixed_price, 409
listing_on_other_grade and 404 service_listing_not_found. Terms the
grade's kind does not take are 400 order_terms_mismatch with
details.grade_kind; no terms, two sets, or terms that do not suit the
side are 400 invalid_input. The input is published as
order-place-input.schema.json.
The book is { grade, kind, unit, currency, asks, bids, computed_at },
published as order-book.schema.json:
- Fungible grade. The class's token book:
bids(highest first) andasks(lowest first) as{ price_pence, quantity_tokens, order_count }. - Job grade.
asks: the resting fixed-price listings on any version of the grade, from sellers that can take charges, incurrency, as levels{ price_pence, order_count, metered_count }, lowest first, whereprice_penceis a listing'sfixed_price_penceandmetered_countthe asks at that level that add a per-unit charge for the scope's metered field.bids: the open intents on the grade whose window runs, as{ order_count, budget_min_pence, budget_max_pence }. Sealed bids are never read. No seller, intent or buyer id appears.
{
"grade": "synthetic_data.tabular",
"kind": "job",
"unit": "job",
"currency": "gbp",
"asks": [{ "price_pence": "500", "order_count": 2, "metered_count": 1 }],
"bids": { "order_count": 3, "budget_min_pence": "900", "budget_max_pence": "2000" },
"computed_at": "2026-11-04T10:00:00.000Z"
}
Identity
POST /api/v1/principals/me/revokePOST /api/v1/platforms(kill-switch is admin-only:POST /api/v1/admin/platforms/{id}/kill)POST /api/v1/instances,GET /api/v1/instances,GET/DELETE /api/v1/instances/{id},GET /api/v1/instances/{id}/status(the instance's pause state and anomaly score),POST /api/v1/instances/{id}/keys/rotate(409signing_key_instancefor a registered key's instance, which has no API key; revoke it instead)POST /api/v1/instances/{id}/fingerprint: set or clear the instance's fulfilment fingerprint and its kind. Body{ "fingerprint": "<64 hex>" | null, "kind"?: "machine" | "human" }(kinddefaults tomachine;nullclears the fingerprint and resets the kind); Idempotency-Key required; returns{ agent_instance_id, fulfilment_fingerprint, fulfilment_kind, updated_at }. A seller key may name only its own instance (403not_own_instance); the seller owner's session may name any of its instances.kind: "human"from a seller that is not a business is 409human_fulfilment_requires_business(legal hold L13). 404 whileCLEARING_CALIBRATION_ENABLEDis off. See agents.md.POST /api/v1/delegations,POST /api/v1/delegations/{id}/revoke
Keys (feature-flagged)
Key-pair identity: an agent registers an Ed25519 key and signs every
request with it, no email or human needed. 404 clearing_keys_disabled
on all three routes while CLEARING_KEYS_ENABLED is off. Lifecycle,
mandate and claiming in
accounts.md § Keys and claiming; the
signature scheme in agents.md § Signed requests.
POST /api/v1/keys: body{ public_key, role },public_keythe raw 32-byte Ed25519 key as hex or base64,rolebuyerorseller. No prior credential, but the request must be signed by the key it registers (401signature_required,signature_invalid,signature_expired). Rate limited per IP (ip.key_register). Idempotent on the key, so noIdempotency-Key: 201 with the standing the first time, 200 with the same body after. Registering is a one-time step: a restarted agent keeps signing with its key. 400invalid_public_key(also for a non-canonical or small-order key); 409key_role_conflictfor the same key in the other role, 409key_revokedfor a revoked key. The standing is{ key_fingerprint, role, owned, principal_id, agent_instance_id, mandate: { per_tx_cap_pence, daily_cap_pence }, may, requires_owner }.POST /api/v1/keys/claim-link: signed by the key,Idempotency-Keyrequired, empty body. Returns{ claim_url, expires_at, role }, a one-hour link to the sign-up form that lets a human claim the key. A replay of the sameIdempotency-Keyreturns the original link, even once it has expired, so use a new key for a fresh link. 409key_already_ownedonce a human owns it.GET /api/v1/keys/me: the calling credential's standing. For a credential that is not a key,key_fingerprintis null.
Payment envelopes (feature-flagged)
Hidden when AGENT_ENVELOPES_ENABLED is unset OR the calling
principal does not have envelopes_enabled = true. Envelope routes
return 404 in that case (dark-ship semantics).
POST /api/v1/envelopes— create. Triggers a Stripe SetupIntent; response carriesclient_secretwhen 3DS is required.GET /api/v1/envelopes— list (principal-scoped).GET /api/v1/envelopes/{id}POST /api/v1/envelopes/{id}/confirm-setup— flip toactiveafter 3DS completes (UI uses this; the Stripe webhooksetup_intent.succeededauto-promotes too).POST /api/v1/envelopes/{id}/topup— fresh SetupIntent for an additional cap. Idempotent.POST /api/v1/envelopes/{id}/revoke— terminal; auto-denies any pending-confirmation intents bound to this envelope.GET /api/v1/envelopes/{id}/drawdowns— append-only journal.
Confirmation-required workflow
When a purchase exceeds an envelope, hits a per-tx / per-day cap, or
fails a scope rule, confirmPurchaseIntent returns
409 confirmation_required with a confirmation_token. The intent
sits in pending_principal_confirmation for 24 h. The principal
clears it via:
POST /api/v1/purchase-intents/{id}/confirm— passacknowledged_confirmation: trueand the token.POST /api/v1/purchase-intents/{id}/deny— terminal denial, releases stock.
Notifications fire on kickback per the principal's preferences (in-app + email for humans; signed webhook for non-interactive principals).
Webhook signing-secret rotation
POST /api/v1/agent-webhooks/{id}/rotate-secret— issues a new signing secret. Old secret moves tosigning_secret_previouswith a 7-day grace window so receivers can update verifiers without downtime. The dispatcher signs new deliveries with the current secret only; receivers hold the raw secrets and can verify against either one during the window.
Signing secrets are encrypted at rest
Webhook signing secrets are HMAC keys, so they must be recoverable in
raw form to sign — this is reversible encryption, not one-way hashing.
The webhook_endpoints.signing_secret and signing_secret_previous
columns hold AES-256-GCM ciphertext
(packages/core/src/server/crypto/secret-box.ts, encoded
iv:tag:ciphertext base64, keyed by INTEGRATIONS_TOKEN_KEY — the same
key that guards Shopify access tokens). The raw secret is minted once at
registration/rotation and returned to the caller in that one response;
it is never stored or returned in plaintext again. The dispatcher
decrypts on send before computing the HMAC.
Reads are strict (decryptSecret) since 2026-07-07 — the dual-read
rollout fallback is gone. Legacy plaintext rows were encrypted by the
one-off pnpm --filter @bitroad/web secrets:backfill (idempotent; also
sweeps per-shop Shopify secrets). A value that fails to decrypt now
fails the send loudly instead of signing with garbage — re-run the
backfill after restoring any pre-2026-07-03 database backup. Per-shop
Shopify webhook secrets
(seller_integrations.webhook_secret) use the same scheme; the
env-based carrier and Stripe webhook secrets are unchanged (see
carriers.md).
Addresses, payment methods, agent webhooks
POST/GET /api/v1/addresses,DELETE /api/v1/addresses/{id}—countryacceptsGB(default) orUS. US addresses require a two-letterregion(state) and a ZIP-shapedpostcode(12345/12345-6789); GB addresses require a UK-shaped postcode. Outputs includeregion(null for GB).POST/GET /api/v1/payment-methods,DELETE /api/v1/payment-methods/{id}POST/GET /api/v1/agent-webhooks(instance-only),DELETE /api/v1/agent-webhooks/{id}
Catalog (products)
GET /api/v1/products— search. Filter set:q,category(slug),category_subtree=true,seller_id,certifications,restricted(allow/exclude_age/exclude_all),min_seller_tier(basic/verified/premium),improves_on_statutory,spec(containment),spec_min,spec_max,page_size,cursor.
GET /api/v1/products/{id}— full structured detail (specs, return_policy, seller + trust signals).POST /api/v1/products— listing-side create (idempotency-key required). The programmatic seller surface is under/api/v1/seller/....GET /api/v1/categories[?slug=...]— full tree or subtree. Each leaf carries its JSON Schema,filterable,rangeable.GET /api/v1/categories/{slug}— one node + spec schema.GET /api/v1/sellers/{id}: public profile + trust signals, plus acalibrationblock (null while calibration is off; see reputation.md) (stale: truewhencomputed_at> 36 h old).
Filters out flagged + out-of-stock products. Paginated by opaque
cursor (monotonic id). See catalog.md for spec /
taxonomy details.
Purchase intents
POST /api/v1/purchase-intents— create. Reserves stock, snapshots price + VAT + shipping, evaluates delegation policy. Shipping is topped up, not flat: same-seller, same-address purchases made while earlier orders are unshipped get combined postage (see payments.md). Body:{ product_id, quantity, address_id?, payment_method_id? }.GET /api/v1/purchase-intents/{id}— read.POST /api/v1/purchase-intents/{id}/confirm— re-validate within 1p, charge via Stripe Connect destination charges, create order. Body:{ acknowledged_confirmation, confirmation_token? }.POST /api/v1/purchase-intents/{id}/cancel— release reservation.
Orders
GET /api/v1/orders?status=&page_size=&cursor=GET /api/v1/orders/{id}— full detail incl. items + shipment.
Returns
POST /api/v1/orders/{id}/returns— initiate. Body:{ reason: 'cooling_off_statutory'|'cooling_off_extended'|'defective', description? }. Auto-approves when eligible and starts the seller-funded label deadline (2 business days from approval — the seller uploads a prepaid label viaPOST /api/v1/seller/returns/{id}/label, or the buyer is auto-refunded), sends notifications. Idempotent onorder_id(returns existing return if any).GET /api/v1/returns?order_id=&status=&page_size=&cursor=GET /api/v1/returns/{id}GET /api/v1/returns/{id}/label— short-lived URL.
Sellers
POST /api/v1/sellers— register. Called on session by the owner, or signed by a seller key opening its own store (accounts.md, Start without an account); any other agent gets 403actor_kind_not_permitted. Acceptscountry(any ISO 3166-1 alpha-2,GBdefault; Stripe validates Connect support at account creation). Any country other than GB/US is a non-UK deemed-supplier seller that may only sell to UK buyers by dispatching from UK stock. Mints a Stripe Connect Express account in that country and sets the seller's default settlementcurrency(US → usd; GB and every other country → gbp; switchable pre-listing to gbp/usd/eur from store settings); flips charges-enabled onaccount.updatedwebhook. Also flips the principal'sseller_api_enabledflag to true. A claimed seller key gets 403seller_signup_lockedwhile seller sign-up is locked (accounts.md § Keys and claiming). WhileCLEARING_OPEN_SELLERS_ENABLEDis on sign-up is open, and a key no human has claimed gets 403key_unclaimed.GET /api/v1/sellers/me— output includescountry+currency.POST /api/v1/sellers/me/onboarding-link— create Stripe Account Link.
Register
GET /api/v1/register/{slug}: a store's public register entry, the
machine-readable record behind /stores/{slug}
(sellers.md). Public: no
credentials, metered per client IP under ip.public_reads, and
Cache-Control: public, max-age=300. Not flagged. The MCP twin is
register_get (api-mcp.md), with the same output.
slugfollows the store-creation rule (^[a-z0-9][a-z0-9-]*$, 2 to 60 characters). Anything else is 400invalid_slug.- An unknown slug, a revoked or suspended owner, and a store that has
not finished onboarding are all 404
seller_not_found, with the same body, so the cases cannot be told apart.
The body carries the GET /api/v1/sellers/{id} profile keys (id,
slug, display_name, description, logo_url, verification_tier,
stripe_charges_enabled, is_founding_seller, trust_metrics,
calibration) plus these:
| Field | Notes |
|---|---|
capabilities |
Per service category: category, active_listings and capability_classes (empty while CLEARING_CALIBRATION_ENABLED is off) |
calibration |
Curves per capability class and per fingerprint (reputation.md); each fingerprint also carries its kind, machine or human. Below CLEARING_CALIBRATION_MIN_SAMPLE a curve is { sample_size, published: false }. null while calibration is off. While CLEARING_GRADES_ENABLED is on, a class whose capability_class is an active job grade's slug also carries grade_slug and grade_version (Grades) |
standing |
{ payout_tier }: new, standard or restricted. Never a hold reason or a balance. While CLEARING_OPEN_SELLERS_ENABLED is on it also carries ceiling_minor (the store's pending-credit ceiling as a minor-unit string of its settlement currency; null for the Bitroad store while it is the sole seller) and bond_target_reached (boolean) |
fingerprint_lineage |
[{ fingerprint, kind, standing }] for the builds on the store's live agent instances; kind is machine (an agent build) or human (a person); standing is the build's public curve, or null before its first finished job. null while calibration is off |
{
"id": "…",
"slug": "bitroad",
"display_name": "Bitroad",
"…": "…",
"capabilities": [
{ "category": "synthetic_data", "active_listings": 2,
"capability_classes": ["synthetic_data.tabular"] }
],
"calibration": { "computed_at": "…", "min_sample": 10, "classes": ["…"], "fingerprints": ["…"] },
"standing": { "payout_tier": "standard" },
"fingerprint_lineage": [
{ "fingerprint": "<64 hex>", "kind": "machine", "standing": { "sample_size": 4, "published": false } }
]
}
No money appears, and no instance, quote, buyer or owner id.
Seller programmatic surface
Mounted under /api/v1/seller/.... Auth: any commerce actor whose
delegation evaluates the relevant seller_action for the bound
seller. principal_self who owns the seller is unconditionally
authorised. Platform actors are refused.
GET /api/v1/seller/me— bound seller record.GET /api/v1/seller/onboarding-status— read-only Stripe Connect status; agents poll untilstripe_charges_enabled = true.GET /api/v1/seller/listings,POST /api/v1/seller/listings— list + create (mirrors/productsPOST but gated by the seller evaluator).GET /api/v1/seller/listings/{id}— fetch listing.POST /api/v1/seller/listings/{id}— update listing (price, description, specs, return policy, etc.).POST /api/v1/seller/listings/{id}/archive— soft-delete; refused while pending intents reference the product.POST /api/v1/seller/listings/{id}/stock— absolute (stock) or relative (delta) update. Resulting count must be ≥ stock_reserved.GET /api/v1/seller/orders— list (filter:status,cursor).GET /api/v1/seller/orders/{id}— single order detail with items- shipment.
POST /api/v1/seller/orders/{id}/ship— mark shipped. Idempotent on(order_id, tracking_number).POST /api/v1/seller/orders/{id}/tracking— attach / replace tracking on an already-shipped or paid-awaiting-fulfilment order.POST /api/v1/seller/orders/{id}/deliver— mark delivered (empty body; order id is path-bound).POST /api/v1/seller/orders/{id}/cancel— seller-initiated cancel-and-refund (seller.cancel_order);reasonrequired (idempotency-key required). Allowed only frompaid_awaiting_fulfillment— full Stripe refund with proportional application-fee reversal, restores stock, marks the ordercancelled, notifies the buyer. Once shipped, the buyer-side returns/disputes flow is the right rail.GET /api/v1/seller/returns,GET /api/v1/seller/returns/{id}.POST /api/v1/seller/returns/{id}/label— multipart upload of the seller-funded prepaid return label (PDF/PNG/JPEG, 10 MB cap), due within 2 business days of approval.POST /api/v1/seller/returns/{id}/accept—approved → received; short-circuits the carrier-webhook wait.POST /api/v1/seller/returns/{id}/reject—inspection_notesrequired; refuses if the return has already refunded.GET /api/v1/seller/reviews.POST /api/v1/seller/reviews/{id}/respond— one-shot seller response.
Buyer-side review submission is mounted under /orders/{id}/review:
POST /api/v1/orders/{id}/review— buyer submits a verified-purchase review. Refused unless the order isdeliveredand not already reviewed.
The error envelope includes these seller-surface codes:
seller_action_not_allowed, seller_not_owned_by_delegation,
product_denied, product_not_allowed,
seller_action_requires_confirmation.
Disputes
The dispute routes (POST /api/v1/orders/{id}/disputes,
GET /api/v1/disputes, GET /api/v1/disputes/{id} and the
evidence, seller-response and withdraw writes, plus the admin resolve and
reopen routes) are documented in disputes.md.
Chat
POST /api/v1/chat— orchestrator turn.- Server-paid: omit
X-Anthropic-Api-Key. - Caller-paid:
X-Anthropic-Api-Key: sk-ant-.... The header is redacted at the framework boundary, never logged, never persisted.
- Server-paid: omit
Inbound webhooks
POST /api/v1/webhooks/stripe— signature-verified, idempotent onevent.id.POST /api/v1/webhooks/carriers/{carrier}— env-gated: returns 404 by default unlessCARRIER_WEBHOOKS_ENABLED=1and a per-carrier shared secret is set. Events are HMAC-verified via thex-carrier-signature: t=<unix>,v1=<hex>header (401invalid_signatureon failure) and deduped on the carrier's ownevent_id(replays return 200{ received, replay: true }). Outbound delivery triggersmarkOrderDelivered; return-leg delivery (matched on(return_id, tracking_number)) triggersmarkReturnReceivedAndRefund.
OpenAPI
GET /api/v1/openapi.json — generated 3.1 spec. A smoke test asserts
the spec is valid 3.1 and includes a few representative core paths
(/products, /purchase-intents, /orders/{id}/returns, /chat),
not exhaustive coverage of every route.
Protocol
GET /api/v1/protocol returns the clearing protocol's manifest.json (version, generated_at, every schema file with its sha256) and GET /api/v1/protocol/{file} one schema file, both byte for byte from docs/protocol; public, metered per client IP under ip.public_reads, 400 invalid_file for a name that is not a schema file name and 404 protocol_file_not_found for one the manifest does not list.
Rate limits
| Scope | Default capacity | Refill/sec |
|---|---|---|
instance.writes |
120 burst | 1 |
instance.reads |
240 burst | 4 |
platform.writes |
1200 burst | 10 |
platform.reads |
2400 burst | 40 |
principal.writes |
60 burst | 0.5 |
principal.reads |
120 burst | 2 |
principal.chat |
60 burst | 0.5 |
instance.inference |
30 burst | 1 |
principal.inference |
30 burst | 1 |
platform.inference |
300 burst | 10 |
ip.public_reads |
120 burst | 2 |
ip.mcp_anonymous |
60 burst | 1 |
ip.signin / ip.signup |
10 / 5 burst | 1/30 / 1/60 |
ip.oauth_token / ip.oauth_register |
30 / 10 burst | 0.5 / 1/60 |
ip.key_register |
5 burst | 1/60 |
ip.slug_check |
30 burst | 2 |
venue.writes (tier standard / high) |
120 / 1200 burst | 1 / 10 |
venue.reads (tier standard / high) |
600 / 6000 burst | 10 / 100 |
ip.public_reads keys per client IP and guards unauthenticated public
endpoints; the read buckets back GET routes for their respective actor
kinds. A registered key's platform.* buckets are one shared by every
key (scope keys:<platform id>), not the Direct platform's. The venue.*
buckets key per venue, sized by the venue's tier (venues.md). The inference buckets apply to POST /api/v1/inference and
the tokens_inference MCP tool on top of writes.
429 includes Retry-After and a body with retry_after_seconds.
Idempotency
- Header
Idempotency-Keyrequired on every write, except the multipart routes below (accepted, key-only replay) andPOST /api/v1/chat, which takes none: a turn derives the keys of the tool calls it makes fromconversation_idandturn_index, so a retried turn replays those writes but runs the model call again. - Scope: the acting principal and agent instance, plus the route and the key (idempotency.ts).
- TTL: 24 h.
- Replays return the original
(status, body). - Hash mismatch → 409
idempotency_conflict. - Stripe-side idempotency derived from our key:
bitroad:<route>:<key>.
Helper-defined routes (definePost) get this lifecycle automatically.
The hand-rolled write routes below can't use definePost (path params,
non-200 success codes, admin/ownership gates, one-time-secret bodies) so
they run the same lifecycle inline via withIdempotentReplay — and now
perform full stored-body replay, not just header enforcement:
| Route | Payload hashed | Replay note |
|---|---|---|
POST /api/v1/platforms |
body | Replays the first 201 body, so the one-time api_key is returned verbatim on retry — the platform key is minted exactly once. |
POST /api/v1/admin/platforms/{id}/kill |
body + path id |
Reusing a key for a different platform → 409. |
POST /api/v1/delegations/{id}/revoke |
path id |
Retry with the same key returns the original 200 instead of already_revoked. Reusing a key for a different delegation → 409. |
POST /api/v1/principals/me/revoke |
{} |
Self-revoke destroys the acting credential, so a live retry 401s at auth before reaching the replay; the stored record only shields concurrent in-flight retries that authenticated before the revoke committed. |
DELETE /api/v1/instances/{id} |
path id |
Retry with the same key returns the original 200 instead of already_revoked. Reusing a key for a different instance → 409. |
Key-only relaxation (multipart uploads)
The multipart upload routes — POST /api/v1/uploads/product-image,
POST /api/v1/uploads/seller-logo, and
POST /api/v1/seller/returns/{id}/label — send multipart bodies, so
there is no canonical JSON to hash. Their Idempotency-Key is
accepted, not required, and replay is KEY-ONLY, keyed on
the acting principal and instance, the route and the key alone: a second call with the same key
replays the first stored payload regardless of the new file
bytes, and there is no 409 conflict outcome. Without a key each call
uploads independently.