Tool names + descriptions are public API per api-mcp.md. The OpenAPI 3.1 spec at
GET /api/v1/openapi.jsonis hand-maintained and smoke-tested; api-rest.md is the authoritative route list.
Auth
Either:
Bearer br_ik_*whosedelegation.kind in ('seller','both')and whosedelegation.seller_idmatches the resource being touched, orSignature 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), orBearer br_pk_*(platform) — refused, sellers are managed by their owning principal not platform staff, orauthjs.session-tokencookie 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_urlwith the guard'sreason) and again before every call. - Credential. Sent as
Authorization: Bearer <credential>(default) orx-api-key: <credential>(auth_header: x_api_key). Stored AES-256-GCM encrypted and never returned or logged; reads showcredential_set: true. Register again to rotate it. - Model.
upstream_modelmust be one of the class'sallowed_models(400upstream_model_not_allowed). - Pause. A paused upstream refuses its buyers with 503
upstream_unavailableand 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.