{"what_this_is":"A trade account on this store's shelf: any platform that resells to agents — a marketplace, an aggregator, a payments layer that hides x402 from its own users — lists our instruments under its roof, collects its customer's money itself, and orders from us by signed webhook. One door, one JSON body, one signed instruction per sale, delivery in seconds, a certificate the end customer can verify against our public key without trusting either of us.","opened":"2026-09-03","door":"https://scvd.store/api/trade/{account}/{item_id}","how_to_call":{"request":"POST https://scvd.store/api/trade/{account}/{item_id}","content_type":"application/json","body":"One JSON object carrying the item's fields (see shelf[].fields) at the top level or under `inputs`, plus optional order_ref (idempotency, up to 120 chars), agent_name and purpose.","headers_in_our_dialect":{"provider_key":"X-Trade-Key","timestamp":"X-Trade-Timestamp","nonce":"X-Trade-Nonce","signature":"X-Trade-Signature"},"sign":"HMAC-SHA256 with the secret you issued us, over timestamp + \".\" + nonce + \".\" + exact_raw_body; send as X-Trade-Signature: sha256=<hex>. Timestamp is unix seconds; nonce is 32 hex characters, fresh per request.","then":"Expect 200 and one JSON object inside 30 seconds. Anything else is a named refusal with delivered:false and billed:false; see errors.","reference_signer":"https://github.com/seancrecord/scvd-general-store-repo/blob/main/src/lib/trade-auth.ts","limits":{"body_max_bytes":1048576,"timestamp_window_seconds":300,"nonce_remembered_seconds":600,"order_ref_remembered_seconds":86400,"order_ref_max_chars":120,"response_seconds":30}},"dialects":[{"id":"canonical","name":"scvd trade dialect v1","headers":{"provider_key":"X-Trade-Key","timestamp":"X-Trade-Timestamp","nonce":"X-Trade-Nonce","signature":"X-Trade-Signature"},"signing_string":"timestamp.nonce.body","signing_string_in_words":"timestamp + \".\" + nonce + \".\" + exact_raw_body","signature":"sha256=<lowercase hex of HMAC-SHA256(secret, signing_string)>","timestamp_unit":"unix seconds","nonce":"^[0-9a-f]{32}$","window_seconds":300},{"id":"hal","name":"Hal marketplace webhook v1","headers":{"provider_key":"X-Hal-Provider-Key","timestamp":"X-Hal-Timestamp","nonce":"X-Hal-Nonce","signature":"X-Hal-Signature"},"signing_string":"timestamp.nonce.body","signing_string_in_words":"timestamp + \".\" + nonce + \".\" + exact_raw_body","signature":"sha256=<lowercase hex of HMAC-SHA256(secret, signing_string)>","timestamp_unit":"unix seconds","nonce":"^[0-9a-f]{32}$","window_seconds":300}],"pricing":{"rule":"trade_price = ceil_to_cent( retail × (1 + uplift) ÷ (1 − partner_share) ). After the partner's share the store nets retail plus the uplift, never less than the front door would have taken.","uplift_bps":2000,"min_retail_usd":0.5,"example_share_bps":500,"cadence":"One-off, per delivery. Nothing at the counter recurs, and an account is never charged for a delivery that did not happen.","what_the_partner_charges_its_customer":"Theirs to set. The trade price is the floor they owe us per delivery, not a price we set for their customer."},"shelf":[{"item_id":"certificate_of_patronage","name":"Certificate of Patronage","retail_usd":20,"trade_price_usd_at_example_share":25.27,"store_net_usd_at_example_share":24,"cadence":"one_off","input_kind":"none","fields":["order_ref","agent_name","purpose"],"item_page":"https://scvd.store/menu/certificate_of_patronage","front_door":"https://scvd.store/api/buy/certificate_of_patronage"},{"item_id":"context_anchor","name":"Context Anchor","retail_usd":1,"trade_price_usd_at_example_share":1.27,"store_net_usd_at_example_share":1.2,"cadence":"one_off","input_kind":"summary","fields":["summary","order_ref","agent_name","purpose"],"item_page":"https://scvd.store/menu/context_anchor","front_door":"https://scvd.store/api/buy/context_anchor"},{"item_id":"bitcoin_anchor","name":"A Bitcoin Anchor","retail_usd":1,"trade_price_usd_at_example_share":1.27,"store_net_usd_at_example_share":1.2,"cadence":"one_off","input_kind":"digest","fields":["digest","label","order_ref","agent_name","purpose"],"item_page":"https://scvd.store/menu/bitcoin_anchor","front_door":"https://scvd.store/api/buy/bitcoin_anchor"},{"item_id":"signature_agent_card","name":"The Calling Card","retail_usd":0.99,"trade_price_usd_at_example_share":1.26,"store_net_usd_at_example_share":1.19,"cadence":"one_off","input_kind":"url","fields":["url","order_ref","agent_name","purpose"],"item_page":"https://scvd.store/menu/signature_agent_card","front_door":"https://scvd.store/api/buy/signature_agent_card"},{"item_id":"onpage_audit","name":"The Shop Window","retail_usd":3,"trade_price_usd_at_example_share":3.79,"store_net_usd_at_example_share":3.6,"cadence":"one_off","input_kind":"url","fields":["url","order_ref","agent_name","purpose"],"item_page":"https://scvd.store/menu/onpage_audit","front_door":"https://scvd.store/api/buy/onpage_audit"},{"item_id":"service_audit","name":"The Once-Over","subtitle":"one signed check of your x402 endpoint, at a permanent URL","retail_usd":5,"trade_price_usd_at_example_share":6.32,"store_net_usd_at_example_share":6,"cadence":"one_off","input_kind":"url","fields":["url","order_ref","agent_name","purpose"],"item_page":"https://scvd.store/menu/service_audit","front_door":"https://scvd.store/api/buy/service_audit"},{"item_id":"passport_refresh","name":"The Refresh","retail_usd":1,"trade_price_usd_at_example_share":1.27,"store_net_usd_at_example_share":1.2,"cadence":"one_off","input_kind":"url","fields":["url","order_ref","agent_name","purpose"],"item_page":"https://scvd.store/menu/passport_refresh","front_door":"https://scvd.store/api/buy/passport_refresh"},{"item_id":"good_buyer","name":"The Good Buyer","retail_usd":0.99,"trade_price_usd_at_example_share":1.26,"store_net_usd_at_example_share":1.19,"cadence":"one_off","input_kind":"url","fields":["url","max_usd","no_spend_controls","order_ref","agent_name","purpose"],"item_page":"https://scvd.store/menu/good_buyer","front_door":"https://scvd.store/api/buy/good_buyer"},{"item_id":"provenance_check","name":"The Company an Address Keeps","subtitle":"which doors advertised this receiving address, and when — signed, from the public chain","retail_usd":5,"trade_price_usd_at_example_share":6.32,"store_net_usd_at_example_share":6,"cadence":"one_off","input_kind":"address","fields":["address","order_ref","agent_name","purpose"],"item_page":"https://scvd.store/menu/provenance_check","front_door":"https://scvd.store/api/buy/provenance_check"}],"eligible_but_not_yet_shelved":["hello","the_statement","luckies","coffees_for_closers","graffiti_on_a_train","standing_watch","conformance_watch","launch_check","opening_day","recurring_patronage","trust_profile","operator_statement"],"accounts":[{"account":"sandbox","name":"The sandbox","site":"https://scvd.store/trade","dialect":"canonical","mode":"test","opened":"2026-09-03","partner_share_bps":500,"settles_in":"nothing — a sandbox owes nothing and is owed nothing","daily_cap":50,"credit_ceiling_usd":0,"door":"https://scvd.store/api/trade/sandbox/{item_id}","check_desk":"https://scvd.store/api/trade/sandbox/check","statement":"https://scvd.store/api/trade/sandbox/statement","published_secret":"scvd-trade-sandbox-secret-anyone-may-use","published_provider_key":"scvd-trade-sandbox-key","note":"A sandbox: anyone may sign with this secret. Real goods, marked test, booked nowhere, fifty a day.","items":[{"item_id":"certificate_of_patronage","trade_price_usd":25.27,"partner_share_usd":1.27,"store_net_usd":24,"fields":["order_ref","agent_name","purpose"]},{"item_id":"context_anchor","trade_price_usd":1.27,"partner_share_usd":0.07,"store_net_usd":1.2,"fields":["summary","order_ref","agent_name","purpose"]},{"item_id":"bitcoin_anchor","trade_price_usd":1.27,"partner_share_usd":0.07,"store_net_usd":1.2,"fields":["digest","label","order_ref","agent_name","purpose"]},{"item_id":"signature_agent_card","trade_price_usd":1.26,"partner_share_usd":0.07,"store_net_usd":1.19,"fields":["url","order_ref","agent_name","purpose"]},{"item_id":"onpage_audit","trade_price_usd":3.79,"partner_share_usd":0.19,"store_net_usd":3.6,"fields":["url","order_ref","agent_name","purpose"]},{"item_id":"service_audit","trade_price_usd":6.32,"partner_share_usd":0.32,"store_net_usd":6,"fields":["url","order_ref","agent_name","purpose"]},{"item_id":"passport_refresh","trade_price_usd":1.27,"partner_share_usd":0.07,"store_net_usd":1.2,"fields":["url","order_ref","agent_name","purpose"]},{"item_id":"good_buyer","trade_price_usd":1.26,"partner_share_usd":0.07,"store_net_usd":1.19,"fields":["url","max_usd","no_spend_controls","order_ref","agent_name","purpose"]},{"item_id":"provenance_check","trade_price_usd":6.32,"partner_share_usd":0.32,"store_net_usd":6,"fields":["address","order_ref","agent_name","purpose"]}]},{"account":"hal","name":"Hal","site":"https://halmarket.dev","dialect":"hal","mode":"test","opened":"2026-09-03","partner_share_bps":500,"settles_in":"sats, off-chain, on the partner's own statement","daily_cap":200,"credit_ceiling_usd":250,"door":"https://scvd.store/api/trade/hal/{item_id}","check_desk":"https://scvd.store/api/trade/hal/check","statement":"https://scvd.store/api/trade/hal/statement","items":[{"item_id":"certificate_of_patronage","trade_price_usd":25.27,"partner_share_usd":1.27,"store_net_usd":24,"fields":["order_ref","agent_name","purpose"]},{"item_id":"context_anchor","trade_price_usd":1.27,"partner_share_usd":0.07,"store_net_usd":1.2,"fields":["summary","order_ref","agent_name","purpose"]},{"item_id":"bitcoin_anchor","trade_price_usd":1.27,"partner_share_usd":0.07,"store_net_usd":1.2,"fields":["digest","label","order_ref","agent_name","purpose"]},{"item_id":"signature_agent_card","trade_price_usd":1.26,"partner_share_usd":0.07,"store_net_usd":1.19,"fields":["url","order_ref","agent_name","purpose"]},{"item_id":"onpage_audit","trade_price_usd":3.79,"partner_share_usd":0.19,"store_net_usd":3.6,"fields":["url","order_ref","agent_name","purpose"]},{"item_id":"service_audit","trade_price_usd":6.32,"partner_share_usd":0.32,"store_net_usd":6,"fields":["url","order_ref","agent_name","purpose"]},{"item_id":"passport_refresh","trade_price_usd":1.27,"partner_share_usd":0.07,"store_net_usd":1.2,"fields":["url","order_ref","agent_name","purpose"]},{"item_id":"good_buyer","trade_price_usd":1.26,"partner_share_usd":0.07,"store_net_usd":1.19,"fields":["url","max_usd","no_spend_controls","order_ref","agent_name","purpose"]},{"item_id":"provenance_check","trade_price_usd":6.32,"partner_share_usd":0.32,"store_net_usd":6,"fields":["address","order_ref","agent_name","purpose"]}]}],"expected_outcome":"200 with the same delivery object the front door returns for that item — deliverable, any item extras, the signed certificate with signature, public key and verify_url — plus a `trade` block naming the account, the trade price, the store's net and the sha256 of your signed instruction, and settled_via saying trade_account (or trade_account_test while the account is in test). No paid_usdc, no network, no payer: none applied.","errors":[{"status":404,"code":"unknown_account","meaning":"No trade account by that name.","what_to_do":"Check the path segment against your account row at /api/trade/contract."},{"status":503,"code":"counter_closed","meaning":"The counter cannot take orders right now: the account is not provisioned on this side, or the replay store is unreachable.","what_to_do":"Do not retry in a loop; the condition is ours to fix and the keeper is paged. Retry after a minute."},{"status":413,"code":"body_too_large","meaning":"The body is over one mebibyte.","what_to_do":"Send only the item's fields; the terms document lists them."},{"status":401,"code":"missing_headers","meaning":"A required signing header is absent.","what_to_do":"Send every header your dialect names, on every call."},{"status":401,"code":"bad_provider_key","meaning":"The provider key does not match the one on the account.","what_to_do":"Check which key you issued us; a rotated key needs the keeper's hand on this side."},{"status":401,"code":"bad_timestamp","meaning":"The timestamp is not an integer in the unit your dialect states.","what_to_do":"Unix seconds or milliseconds as your account row says, digits only."},{"status":401,"code":"stale_timestamp","meaning":"The timestamp is outside the window, past or future.","what_to_do":"Sign at send time with a synchronised clock; do not reuse a signed request."},{"status":401,"code":"bad_nonce","meaning":"The nonce is not the shape your dialect requires.","what_to_do":"Thirty-two hex characters, fresh per request."},{"status":401,"code":"bad_signature","meaning":"The HMAC does not verify against the secret in service or the previous one.","what_to_do":"Sign the exact bytes you send, in the order timestamp.nonce.body, and compare with the reference signer before assuming the secret is wrong."},{"status":409,"code":"replayed","meaning":"This nonce (or this exact instruction) has already been presented.","what_to_do":"Nothing was delivered on this call. If you are retrying a timed-out order, send order_ref and a FRESH nonce: the same order_ref returns the original delivery."},{"status":404,"code":"not_at_the_counter","meaning":"The item is not on your account, or not traded at the counter at all.","what_to_do":"Order from the items on your account row; ask the keeper to add one."},{"status":400,"code":"bad_request","meaning":"The body is not a JSON object, or the item's required field is missing or malformed.","what_to_do":"The terms document names each item's fields; the error names the one at fault."},{"status":400,"code":"target_refused","meaning":"The URL is not one we will probe: private, loopback, non-https, or our own hostname.","what_to_do":"Send a public https door. We do not sell audits of ourselves."},{"status":429,"code":"credit_ceiling_reached","meaning":"Your live account's unpaid net has reached its credit ceiling.","what_to_do":"Settle the statement; the ceiling is printed on your account row and the outstanding figure on /api/trade/ledger. The keeper can raise it."},{"status":429,"code":"cap_reached","meaning":"Your account has ordered its daily cap.","what_to_do":"The cap is the blast-radius bound on a leaked secret, not a rate limit; it resets at UTC midnight and the keeper can raise it."}],"catalog":"https://scvd.store/api/trade/catalog","ledger":"https://scvd.store/api/trade/ledger","sandbox":"https://scvd.store/api/trade/sandbox/check","room":"https://scvd.store/trade","honest_limits":"The store sees no payment on this door and signs none. A trade certificate proves the store delivered on a signed instruction from a named account; it does not prove the account's customer paid, was refunded, or existed. The receivable is derived from delivery rows on a capped read that says when it was cut short; the daily cap is counted on eventually consistent storage and can overshoot by a unit under a race. Nothing here is a rail, and the payout side of a statement is recorded by a person.","security":{"what_this_does_in_your_name":"Verifies an HMAC-SHA256 signature over your timestamp, nonce and exact body against a secret you issued; refuses timestamps outside a five-minute window and any nonce seen before, on a strongly consistent store; then makes and signs the goods exactly as the front door would. Where the item is a probe, we fetch the URL you sent, once, in our own name.","what_it_stores_about_you":"One ledger row per delivery: account, item, certificate id, trade price, the sha256 of your signed instruction, and your order_ref if you sent one. The body of your request is not stored; the signed goods are, as they are for any sale. Secrets you issue us are Worker secrets, never in the repository, never in a response or a log.","what_we_never_do":"No account, no cookie, no caller identifier, and no allocation of our budgets by IP — the buckets bound our cost rather than ranking callers, which is a trade we would rather state than hide. We do not sell, share or publish what any caller asked us about; the weekly census is a separate instrument that walks public discovery feeds, never this door's traffic.","standards":"Disclosure is private-first and symmetric: an operator hears from us before the public does, and the same rule binds us when the defect is ours. Corrections are dated and public, never silent edits. Every signed artifact verifies offline against a published key, so you never have to ask us whether a document of ours is real.","reporting":"https://scvd.store/.well-known/security.txt for a vulnerability, https://scvd.store/corrections for something we got wrong."}}