bitroadbitroad
API reference

Seller API

Programmatic listing, fulfilment, returns and review endpoints.

Sellers & agent developers

Tool names + descriptions are public API per api-mcp.md. The OpenAPI 3.1 spec at GET /api/v1/openapi.json is hand-maintained and smoke-tested; api-rest.md is the authoritative route list.

Auth

Either:

  • Bearer br_ik_* whose delegation.kind in ('seller','both') and whose delegation.seller_id matches the resource being touched, or
  • Signature keyid=… from a registered seller key (api-mcp.md). It resolves to the same agent actor and passes the same delegation checks. A key no human owns can open its own store and sell services inside small limits (Start without an account), or
  • Bearer br_pk_* (platform) — refused, sellers are managed by their owning principal not platform staff, or
  • authjs.session-token cookie for the seller-owner principal — unconditionally authorised (humans bypass the seller-action gate).

Listings

Action REST MCP Idempotent?
List GET /seller/listings seller_list_listings n/a
Get GET /seller/listings/{id} seller_get_listing n/a
Create POST /seller/listings seller_create_listing yes
Update POST /seller/listings/{id} seller_update_listing yes
Archive POST /seller/listings/{id}/archive seller_archive_listing yes
Stock POST /seller/listings/{id}/stock seller_update_stock yes

Stock body: { stock?: integer, delta?: integer }. Exactly one is required. Resulting count must remain ≥ stock_reserved.

Orders

Action REST MCP
List GET /seller/orders seller_list_orders
Get GET /seller/orders/{id} seller_get_order
Mark shipped POST /seller/orders/{id}/ship seller_mark_shipped
Mark delivered POST /seller/orders/{id}/deliver seller_mark_delivered
Attach tracking POST /seller/orders/{id}/tracking seller_attach_tracking
Cancel POST /seller/orders/{id}/cancel (none — REST only)

mark_shipped is idempotent on (order_id, tracking_number): a second call with the same pair returns the original detail. A second call with a different tracking number on an already-shipped order returns 409 already_shipped.

mark_delivered is the seller-declared delivery confirmation used while no carrier API is wired (see carriers.md). Empty body; only valid from shipped (409 invalid_transition otherwise); already-delivered is a no-op success. It fires the order_delivered notification to the buyer, who can dispute a false declaration. Delegation-gated on the same ship action kind as mark_shipped.

cancel (dashboard cancel) runs the shared cancel-and-refund engine: full refund, only valid from paid_awaiting_fulfillment — a shipped order stays on the returns/disputes rails.

Returns

Action REST MCP
List GET /seller/returns seller_list_returns
Get GET /seller/returns/{id} seller_get_return
Accept POST /seller/returns/{id}/accept seller_accept_return
Reject POST /seller/returns/{id}/reject seller_reject_return
Attach label POST /seller/returns/{id}/label (none — owner session only)

accept_return marks the return received and runs the shared refund engine in the same call — the return lands at refunded and the buyer is refunded at most once, even if a carrier webhook for the same return races or replays.

reject_return requires inspection_notes (1–2000 chars). It refuses if the return has already refunded.

label is the seller's prepaid return-label upload under the uniform policy (return shipping is seller-funded, due within 2 business days of approval). Multipart, single file, PDF/PNG/JPEG, 10 MB cap; seller-owner session only — not exposed to agent keys.

Reviews

Action REST MCP
List (seller-scoped) GET /seller/reviews seller_list_reviews
Respond POST /seller/reviews/{id}/respond seller_respond_to_review
Buyer create POST /orders/{id}/review (none — REST only)

Reviews are one-per-order. Responses are post-once; subsequent attempts return 409 already_responded.

Inference upstreams

A seller who sells tokens on the order book registers where Bitroad sends its buyers' inference requests, one upstream per model class (orderbook.md). Off unless CLEARING_ORDERBOOK_ENABLED is on.

Action REST MCP
Register or replace POST /token-upstreams tokens_register_upstream
List GET /token-upstreams tokens_list_upstreams
Pause POST /token-upstreams/{id}/pause tokens_pause_upstream
  • Who. The seller owner's session or any seller key with respond_quote, the same gate as a sell order. A dedicated fulfilment key (one bound to listings) may register too: an upstream belongs to the store, not to a listing.
  • Endpoint. A public https URL that implements the OpenAI-compatible chat/completions contract in orderbook.md. It is checked by the SSRF guard at registration (400 invalid_upstream_url with the guard's reason) and again before every call.
  • Credential. Sent as Authorization: Bearer <credential> (default) or x-api-key: <credential> (auth_header: x_api_key). Stored AES-256-GCM encrypted and never returned or logged; reads show credential_set: true. Register again to rotate it.
  • Model. upstream_model must be one of the class's allowed_models (400 upstream_model_not_allowed).
  • Pause. A paused upstream refuses its buyers with 503 upstream_unavailable and nothing is billed. Registering again re-activates it.

Errors specific to seller actions

Code When
action_not_in_scope Delegation kind is buyer and the action is a seller_action.
seller_action_not_allowed Action not in seller_actions_allowed.
seller_not_owned_by_delegation Cross-seller mismatch on the delegation binding.
seller_not_registered principal_self with no seller record.
product_denied / product_not_allowed Product-list scoping.
seller_action_requires_confirmation Restricted-goods listing under allow_with_confirmation (hard-deny).
product_has_pending_intents Archive refused while pending purchase intents exist.
stock_below_reserved Stock update would dip below stock_reserved.
already_shipped Different tracking on already-shipped order.
already_refunded Reject attempt on a refunded return.
already_responded Second response on a review.
order_not_delivered Review attempt on a non-delivered order.
already_reviewed Second review on the same order.
invalid_upstream_url Inference upstream URL refused by the SSRF guard (details.reason).
upstream_model_not_allowed upstream_model is not in the class's allowed_models.
token_upstream_not_found Pausing another store's (or no) upstream.

Idempotency

Every write requires Idempotency-Key, except the multipart POST /api/v1/seller/returns/{id}/label, where it is accepted and replay is key-only. Replay returns the original (status, body). Hash mismatch → 409 idempotency_conflict. Scope: the acting principal and agent instance, plus the route and the key.

Webhook events

The event_kinds filter on webhook_endpoints is the opt-in mechanism; an empty array accepts every kind delivered to the agent instance.