ai.bitroad/bitroad MCP server

Save a new shipping address. Set is_default_shipping=true to make it the default.

List the principal's saved shipping addresses. The agent does NOT need to call this every purchase — purchase_create_intent will use the principal's default shipping address if `address_id` is omitted.

Disconnect this OAuth connection by revoking the access+refresh chain that issued the token making this call. Idempotent: a second call returns `{ revoked: false, reason: 'already_revoked' }`. Refuses with `not_oauth_token` when called under an br_ik_* instance key — rotate those from the dashboard instead.

Return who this MCP credential acts as: principal email/role, agent name, client (Claude install) that issued the token, and when it was last used. Works for both br_ik_* instance keys and br_oat_* OAuth tokens; OAuth-specific fields are null when called under an instance key.

Fetch one category by slug, including the spec JSON Schema for leaf categories. Useful before building a structured purchase intent so the agent emits a valid spec query.

Fetch a single product by id. Returns full description, structured spec values, seller id, live stock, and any restricted-goods flags. Prefer this over re-running search when the agent already has the product id.

List the product catalog's category taxonomy. Optionally pass `slug` to scope to a subtree (e.g. 'electronics'). Each leaf carries its JSON Schema for specs, plus filterable / rangeable arrays so agents know which spec keys are queryable.

Search the product catalog (physical goods) by free-text query, optional category, or seller. Returns a paginated list of summaries with pence-denominated prices, available stock, and restricted-goods flags. Pass a concise phrase, not a full sentence. To find a service, use services_search_listings instead.

Attach an evidence item to an open dispute. The body is base64-encoded; per-item cap is 25 MB and per-dispute cap is 200 MB. Either the filing buyer or the seller-owner can upload.

File a dispute on a goods order (order_id; reasons: not_as_described, defective, not_received, fraud_unauthorized_charge, duplicate_charge, other) or a service quote (service_quote_id; reasons: service_not_delivered, service_quality, service_scope_mismatch, plus the generic three). Exactly one target. Filing on a service quote pauses its payout auto-release. A deterministic auto-classifier resolves clear-cut cases; the rest route to admin review with a 72h seller SLA.

Fetch one dispute by id with the full evidence trail and timeline. Buyer-side or seller-side caller — returns 404 if the dispute doesn't belong to either of the calling actor's roles.

List disputes for the authenticated principal (buyer-side: ones they filed; seller-side: ones filed against their orders). Filter by `status` (admin_review, awaiting_seller, resolved_for_buyer, resolved_for_seller, withdrawn).

Seller-side response to a dispute. Requires the seller delegation's `respond_dispute` action. Free-form text 1–4000 chars.

Buyer-only: withdraw an open dispute. Closed disputes cannot be withdrawn.

Fetch a single envelope by id. Returns the same shape as envelopes_list. Returns 404 when the envelope is not bound to the calling agent instance.

List the active and historical payment envelopes the calling agent instance can draw against. Each entry shows balance, scope, validity, and per-tx / per-day caps. Read-only — envelopes are created, topped up, and revoked by the principal in the dashboard.

Seller side (respond_quote): submit or replace your sealed bid on an open intent: amount_pence (inc-VAT, at most the budget ceiling), eta_minutes (now plus this must fit deadline_at), optional confidence_bp (0 to 10000) and optional service_listing_id (your active listing in the intent's category; a listing bound to another fulfilment key refuses with not_fulfiller). One bid per key per intent; a second call replaces it. There is no withdraw. When the window closes the lowest eligible bid wins (ties: lowest eta, then earliest) and is charged at its own price or, when second-price clearing is on and two or more sellers bid, at the lowest bid from another seller capped at the ceiling, so bid your true cost. The winner then finds the job in services_list_my_sales and fulfils it with services_start_work and services_submit_deliverable.

Seller side (respond_quote): list open intents you can bid on, in categories where you have an active listing and in your settlement currency, while their bid window runs. Each carries the scope, output_schema, acceptance block, budget_ceiling_pence, deadline_at and bid_window_closes_at, plus my_bid (your own sealed bid, if any). Bids are sealed: you never see anyone else's. Filter by category; page with cursor.

Post an open intent: describe the job instead of picking a listing. Give a category (optionally a capability_class such as code_review.security), the input scope, an optional output_schema and acceptance block, a budget_ceiling_pence, a deadline_at and a bid_window_seconds (10 to 3600, default 60). The ceiling must pass your delegation's caps as a dry run, and must sit below its confirmation threshold (budget_over_confirmation_threshold otherwise). currency is required unless your delegation is already pinned to one. The intent is a quote thread with status 'open' and no seller; read it with services_get_quote or services_list_my_quotes (kind 'intent'), withdraw it with services_withdraw_quote. An intent with no fill ends 'unfilled' with an unfilled_reason. Pass client_intent_ref to make a retry return the same intent.

Fetch a single order with line items, shipment / tracking, payment status, and any associated returns or disputes. Buyer-side view — for seller-side use seller_get_order.

List orders the authenticated principal placed (buyer-side view), paginated with a cursor. Optional status filter (e.g. 'paid_awaiting_fulfillment', 'delivered', 'cancelled'). Use this to find an order id before calling orders_get.

Returns a one-time Stripe Checkout URL to hand the user so they can add a payment card. The card is saved to their account automatically when they complete the hosted flow — no charge is made (setup mode only). Present the `checkout_url` to the user as a link to open in a browser; there is nothing else for the agent to do. Buyer principals only. Pass `kind: 'bacs_debit'` instead to set up a Bacs Direct Debit mandate that settles the monthly tab; business accounts only (others get 409 `bacs_business_only`), and only while Bacs settlement is enabled.

List the principal's saved payment methods (last4 + brand only — full card numbers are never exposed to agents). purchase_confirm_intent uses the principal's default method if no `payment_method_id` is passed.

Fetch a platform's public reputation profile by slug: KYC status, rolling-window orders/disputes/refunds, on-time-ship rate, dispute resolution p50/p95, anomaly-pause count. Decommissioned platforms include the banner and reason.

Price a job from data: for a service category (optionally one capability_class) in one currency over the last window_days (default 90), what jobs on Bitroad cleared at (clearing_price p10/p50/p90 as minor-unit strings), median_minutes_to_delivery, first_pass_accept_bp, dispute_rate_bp, outcome_mix, funding_mix and the open-intent fill_rate_bp. rail narrows to intent-cleared or listing-bought jobs; clearing_rule narrows to intents cleared at the best bid or at the second price. Aggregates only, no seller or buyer identity. Below min_sample jobs the answer is published: false with every figure null. Use it to set an intents_post budget_ceiling_pence or an intents_bid amount. Works without credentials.

Buyer side: what your principal has already learned buying services on Bitroad, so a fresh agent instance does not start from zero. Your principal's own history only, never another buyer's. Per capability class over the last window_days (default 180): preferred_sellers (your jobs with each seller, released and refunded shares, first-pass acceptance, median minutes and cleared price, the seller's public standing and per-fingerprint standing), standing_terms (your usual budget ceiling, cleared price, bid window, acceptance check kinds and on_fail mix) and first_pass_history (your latest jobs, newest first). Money is minor-unit strings. On a second_price clear the cleared price sits above the seller's claimed (bid) price by design. Call it on your first turn, before services_search_listings or intents_post; auth_whoami says when there is history to read.

Cancel a pending purchase intent and release the stock reservation.

Confirm a purchase intent — re-validates price within 1p tolerance, charges via Stripe Connect destination charges (per-seller application fee on item only), and creates the order. May return SCA / payment-action-required / declined errors.

Create a purchase intent for a product. Reserves stock, snapshots price + VAT + shipping, and consults the delegation policy. Returns an intent id; intents expire after 15 minutes if not confirmed. Combined postage: same-seller purchases to the same address while earlier orders are unshipped are only charged the postage difference, so confirm each purchase before creating the next intent; an intent created while the previous one is unconfirmed pays full postage.

Fetch a store's public register entry by slug, the machine-readable record behind /stores/<slug>: identity and trust metrics, capabilities (service categories with active listings and the capability classes it has finished jobs in), calibration curves per capability class, standing (payout tier name), and fingerprint lineage (the builds behind its live agents, each with the standing it carries). Aggregates only, no instance or buyer id; figures appear only at or above the calibration minimum sample, and calibration and fingerprint_lineage are null while calibration is off. Works without credentials.

Fetch a single return by id, including reason, status, restocking fee (if any), refund ledger, and the inspection trail once the parcel has arrived.

Fetch a short-lived signed URL for the return shipping label PDF. URL expires within minutes; re-call to get a fresh one. Only available once the return has progressed to label_ready.

Initiate a return on a delivered order. Uniform platform policy: a 30-day change-of-mind window from delivery, FREE, full refund, NO restocking fee, and the SELLER funds the return label. Reasons: cooling_off_statutory (days 0–14) and cooling_off_extended (days 15–30) are change-of-mind; defective is a faulty-item (CRA 2015) claim — full refund within 30 days, and past that it is recorded and routed for manual repair/replacement handling rather than denied. The seller must upload a prepaid label within 2 business days of approval or the buyer is auto-refunded. Idempotent on order_id.

List returns the authenticated principal filed (buyer-side view), paginated. Filter by `order_id` to find returns on a specific order, or by `status` (initiated, label_ready, in_transit, received, refunded, rejected).

Acknowledge that a returned parcel arrived and was inspected. Moves return: approved → received. The refund engine runs idempotently afterwards via the existing webhook flow.

Soft-delete a listing (is_active=false). Refuses while any purchase intents are still pending against it.

Attach or update tracking on an already-shipped order. Use mark_shipped for first ship; this is for late-arriving tracking only.

Create a product listing. Validates the payload against the leaf category's spec schema and the structured return policy. Restricted-goods classifier runs at write time; flagged listings are inserted but invisible until cleared.

Fetch a single listing the bound seller owns, including its full description, current stock + reserved counts, spec values, and any moderation state. Refuses if the listing belongs to a different seller.

Fetch the seller record bound to the calling principal or seller-side agent instance. Refuses when the caller has no seller record.

Fetch a single seller-scoped order with buyer shipping address (PII-redacted where the policy requires it), items, shipment, payment status, and any associated return/dispute. Refuses if the order isn't against this seller.

Fetch a single return filed against one of the bound seller's orders, with reason, status, restocking fee, inspection notes, and the refund ledger. Refuses if the return isn't on a seller-owned order.

List the bound seller's product listings, paginated. Includes archived/flagged listings by default — pass `is_active: true` to filter to live listings only. Returns slug, category, stock, price, and any moderation flags.

List orders placed against the bound seller's products (seller-side view), paginated. Filter by `status` (e.g. 'paid_awaiting_fulfillment' to find orders that need shipping). This is the seller-equivalent of orders_list.

List returns filed against the bound seller's orders, paginated. Filter by `status` (initiated, label_ready, in_transit, received, refunded, rejected) to triage what needs inspection. Seller-equivalent of returns_list.

List reviews left on this seller's orders, paginated. Filter by `responded: false` to find reviews that still need a seller response. A review's `rating` is 1-5; lower-rated ones are typically the highest priority to respond to.

Declare a shipped order as delivered (no carrier confirmation is wired). Only valid from shipped; already-delivered is a no-op success. Notifies the buyer, who can dispute if it never arrived. Orders still shipped after 10 days are auto-marked delivered by the platform.

Mark an order as shipped with a tracking number. Idempotent on (order_id, tracking_number) — same pair is a no-op success. Enqueues carrier polling automatically.

Read-only Stripe Connect onboarding status. Stripe Express onboarding itself is human-on-session; agents wait on this read until charges_enabled flips true before listing.

Reject a return after inspection. inspection_notes is required. Refuses if the return has already refunded.

Post the seller's response to a review. One response per review; subsequent attempts return already_responded.

Seller side: declare this agent instance's fulfilment fingerprint, a hex SHA-256 over your {code_version, model_id, prompt_version} (stored lowercase; null clears it). Bids and fulfilled jobs snapshot it, and Bitroad publishes a calibration curve per (seller, fingerprint) in sellers_get, so a fresh instance of the same build inherits its standing. Standing never crosses sellers. A seller key may set only its own instance; the seller owner's session may name any of its instances with agent_instance_id. Change it whenever the code, model or prompt changes. kind human declares a person instead of a build (the fingerprint then hashes what identifies them), which a human-only grade requires; while Bitroad's L13 interim rule stands, only a business seller may declare it.

Patch an existing listing the calling seller owns. Specs are re-validated against the leaf schema; return_policy is re-validated against the platform statutory floor. Buyers with pending intents get re-validated at confirm time, not blocked here.

Update a listing's stock count. Pass `stock` for an absolute value or `delta` for a relative change. Resulting stock must remain >= reserved.

Fetch a seller's public profile + trust signals (verification tier, dispute / refund / on-time-ship rates over a 90-day window, response times). Trust metrics carry a `stale: true` flag when the last computation is older than 36 hours.

Accept a submitted quote and charge immediately. Runs the same delegation caps and payment-envelope rails as goods purchases; cap kickbacks return confirmation_required with a token — re-accept with acknowledged_confirmation + the token after the principal signs off. Funds are held in escrow until the deliverable is accepted.

Explicitly accept the deliverable on a delivered quote. The acknowledgement is recorded immediately; the held payout releases as soon as the funds have settled in the seller's Stripe balance (instant when settled, otherwise the worker completes it — the returned status stays 'delivered' until then). Without this, funds auto-release 7 days after delivery unless a dispute is filed. On a quote with funding 'tab' no payout runs: the status moves to 'released' at once and the seller's credit is paid when the buyer's settlement cycle captures. On a quote with an acceptance block, a passing check has usually released the payout already, so this returns the current state. Called after a fail or error verdict (or while the check is pending), it is you overriding the check, and it releases the payout.

Post a counter-offer on a quote thread (price in pence, ETA in minutes, optional terms). Either side may counter: the buyer counters a submitted quote (requires the listing to have haggling enabled), the seller counters/revises a requested or already-quoted thread (always allowed pre-accept). Each counter overwrites the standing offer, keeps the thread in 'quoted', and restarts the buyer's acceptance SLA. Bounded to 6 counters per thread; past that, only accept or reject. No charge happens here — caps and confirmation are re-checked at accept against the latest offer.

Seller-side: publish a service listing (GPU compute, synthetic data, inference, vector hosting, code review, research). pricing_mode='fixed' lets buyers purchase in one call (set fixed_price_pence, optionally per-unit fixed_unit_* against a scope_schema field); pricing_mode='quote' (default) advertises a capability buyers request quotes against, with an optional min/max price band. scope_schema is the constrained field DSL a buyer's request must conform to. Set haggling_enabled=true to opt this quote-mode listing into iterative counter-offers (services_counter_quote). All *_pence values are minor units of the seller's settlement currency. Optional output_schema and acceptance attach machine acceptance: each quote created from the listing snapshots them, and a deliverable that passes the checks releases the payout at once. Requires completed Stripe onboarding — refuses with stripe_onboarding_incomplete otherwise.

Fetch a single service listing including its scope schema — the fields a quote request or purchase scope must provide — and, for fixed-price listings, the deterministic pricing formula (flat price plus optional per-unit block billing).

Fetch one service quote thread with its deliverables. Buyer or seller side. Secret deliverables are decrypted only for the buyer; everyone else sees a redaction. Also returns the buyer's own open intents: status 'open' or 'unfilled', null service_listing_id and seller_id, plus category, capability_class, budget_ceiling_pence, deadline_at, bid_window_closes_at and unfilled_reason.

List service quote threads the authenticated principal opened (buyer-side view), paginated, including open intents (service_listing_id and seller_id are null until an intent clears). Filter by status (requested, quoted, open, unfilled, paid, delivered, released, …) or by kind ('quote' or 'intent').

Seller-side: list charged threads you still owe work on, paginated. status=paid | in_progress | delivered, or active (all three, the default). The polling tool for fixed-price listings — a fixed-mode purchase is created already paid, so it never shows up in services_list_open_requests. Respond with services_start_work then services_submit_deliverable.

Seller-side: list unanswered quote requests (status=requested). The primary polling tool for seller agents — respond with services_submit_quote.

Buy a fixed-price service in one call: validates the scope, computes the deterministic price, creates the quote thread directly in accepted, and charges immediately, with no seller round-trip. The charge is held in escrow; the seller delivers via services_submit_deliverable and the payout releases when you call services_acknowledge_delivery (or 7 days after delivery with no dispute). Same delegation/envelope enforcement as services_accept_quote. When the buyer's tab is on, a small job from the Bitroad store (charge total below the tab threshold) accrues on the buyer's settlement cycle instead of charging the card per job: the result is status 'paid' with funding 'tab' and a settlement_cycle_id, and the cycle captures the total later. Otherwise funding is 'immediate'.

Reject a submitted quote (buyer-only). Also used by the principal to deny a quote sitting in pending_principal_confirmation after a cap kickback.

File a scope-of-work against a quote-mode service listing for bespoke work. The scope must conform to the listing's scope schema. The seller responds with a price + ETA; the buyer then has 24h to accept with services_accept_quote, which charges into escrow. Fixed-price listings refuse this: use services_purchase.

Search service listings (GPU compute, synthetic data, inference, vector hosting, code review, research, data labelling). This is the entry point to the primary Bitroad flow: find a listing, then buy it with services_purchase (pricing_mode 'fixed', one call) or file a scope with services_request_quote (pricing_mode 'quote'). Filter by category or pricing_mode. Every charge is held in escrow until the buyer accepts the deliverable.

Seller-side: mark a paid quote as in_progress. Requires the delegation's respond_quote action.

Seller-side: submit the deliverable on a paid/in-progress quote. kind=url|text|file|secret. Files are base64 in file_b64 (max 25 MB) with file_name + file_mime_type and land on object storage; secrets are envelope-encrypted and only the buyer can read them. Starts the buyer-acceptance window; re-submitting (a revision) restarts it. On a quote with an acceptance block the deliverable comes back with acceptance_verdict 'pending': Bitroad runs the checks within seconds, a pass releases the payout, and a fail (see acceptance_detail via services_get_quote) lets you revise until the deadline, after which the buyer is refunded.

Seller-side: answer a quote request with a price (pence), ETA in minutes, and optional terms. Requires the delegation's respond_quote action. Price must sit inside the listing's min/max band when one is set. Starts the buyer's 24h acceptance SLA.

Withdraw a quote request before the seller has quoted, or an open intent while its bid window runs (buyer-only).