Soukbase API

Base URL: https://soukbase.com. Machine description: /openapi.json (catalog at /.well-known/api-catalog). Reading needs no authentication. Sellers sign in with a wallet signature: see /.well-known/auth.md. There are no API keys. Checkout is not on this domain; it runs at the seller's APIbase Integrator shop. Read-only MCP: POST /mcp (tools: search_listings, get_listing, get_seller, list_categories, get_checkout, trust_get; same limits as the read group).

All bodies are JSON. All prices are strings with two decimals in USDC, for example "12.50". Every error has the same shape: {"error": "...", "code": "...", "field": "...", "next_action": "..."}. Match on code; the wording of error can change.

Routes

<!-- generated:routes -->

<!-- /generated:routes -->

POST /hooks/telegram is the operator's review webhook. It accepts only Telegram's calls with the bot's secret header and answers 403 to anyone else; it is not part of the API.

POST /hooks/integrator is the Integrator's order webhook (signed, see /docs/sellers.md). The public listing feed is GET /feed/products.jsonl, GET /feed/products.json (live listings only, licence CC BY 4.0 via soukbase.com, keep source_url and source_hash) and GET /feed/newest.xml (Atom, the 50 newest). All three answer ETag, If-None-Match and If-Modified-Since with 304.

Limits

<!-- generated:limits --> Rate limits. Every answer carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; a refused request gets HTTP 429 and Retry-After (seconds until the window resets). For reports only accepted reports count toward the daily limit; refused attempts are counted separately, per IP.

Seller limits (until tier T3, then the second row):

An open listing is one that is in review, approved and waiting to publish, live or paused. Rejected and removed listings do not count. Tier T0 cannot list.

Field limits.

• title: 1 to 120 characters; description: 1 to 2000 characters, plain text with paragraphs, lists and inline code; no HTML and no images.
• links: 1 to 20 https URLs, only with delivery_mode instant_links, each up to 2048 characters.
• refund_window_days: 0 to 30, default 14.
• details (reports): up to 2000 characters. client_ref: up to 64 characters.
• A repeated client_ref with the same content within 24 hours returns the existing listing (HTTP 200, Idempotent-Replay: true); different content gives idempotency_conflict.
• Search pages: 20 items by default, at most 100 (limit).

<!-- /generated:limits -->

Examples

Sign in and create a seller

Get a nonce, build the EIP-4361 message from the values in the answer, sign it with the wallet (EIP-191 personal_sign), and send both. The exact message and statement are in /.well-known/auth.md.

curl -s https://soukbase.com/api/v1/auth/nonce \
  -H 'content-type: application/json' \
  -d '{"address":"0xYourWalletAddress","purpose":"seller_bind"}'

{"nonce":"3f9c...","purpose":"seller_bind","expires_at":"2026-11-02T12:10:00.000Z","domain":"soukbase.com","uri_origin":"https://soukbase.com","chain_ids":[8453],"documents":[{"name":"seller-agreement","resource":"https://soukbase.com/legal/seller-agreement.md#sha256=..."}]}

curl -s https://soukbase.com/api/v1/sellers \
  -H 'content-type: application/json' \
  -d '{"handle":"acme-data","display_name":"Acme Data","contact_email":"owner@acme.example","country":"DE","consents":{"agreement":true,"sanctions":true,"public_receipts":true},"siwe":{"message":"...","signature":"0x..."}}'

{"handle":"acme-data","display_name":"Acme Data","wallet_address":"0x...","url":"https://soukbase.com/s/acme-data","status":"active","tier":"T1","class":"external","integrator_slug":null,"shop":{"slug":null,"storefront_url":null,"status":"not_connected","payout":{...}},"next_action":"Sign in ..."}

integrator_slug is optional: you can register without an Integrator shop and connect it later (below). When you send it, the shop is checked before anything is saved, with the same codes as the PATCH below.

A known wallet that sends the same request again, with the same handle, renews an expired binding and gets 200 with the same body.

Then sign a second message with purpose session and exchange it:

curl -s https://soukbase.com/api/v1/auth/siwe \
  -H 'content-type: application/json' \
  -d '{"message":"...","signature":"0x..."}'

{"token":"...","token_type":"Bearer","expires_at":"2026-11-03T12:00:00.000Z","address":"0x..."}

Check a handle

curl -s https://soukbase.com/api/v1/handles/acme-data

{"handle":"acme-data","available":false,"reason":"taken"}

reason is invalid_format, reserved or taken.

Create a listing

New listings go to review. What is checked, and what a person decides, is in /docs/moderation.md.

curl -s https://soukbase.com/api/v1/listings \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"category":"prompt_set","title":"Prompt pack for code review","description":"Tested prompts for reviewing pull requests.","delivery_mode":"instant_text","delivery_time":"instant","price_usdc":"5.00","refund_window_days":14,"rights_confirmed":true,"client_ref":"run-1"}'

{"listing":{"id":"...","status":"pending_review","version":1,"price_usdc":"5.00", "...":"..."},"idempotent_replay":false,"next_action":"A person reviews every listing. ..."}

Categories: dataset, prompt_set, template, report, ebook_audio, own_api_credits. Delivery modes: instant_text, instant_links, webhook. Delivery times: instant, 1h, 24h, 72h. Soukbase never stores the delivered goods: you paste them into your own Integrator shop.

Change a listing

curl -s -X PATCH https://soukbase.com/api/v1/listings/LISTING_ID \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"price_usdc":"6.00"}'

Changing price, stock or refund window keeps a live listing live and the new version is checked again. Changing title, description, category, links, delivery mode or delivery time creates a new version in review and takes the live version down. A rejected listing is submitted again by any edit. stock is only on this route (null means not limited).

Search listings

curl -s 'https://soukbase.com/api/v1/listings?q=prompts&category=prompt_set&price_max=10.00&delivery_mode=instant_text'

{"items":[{"id":"...","title":"...","price_usdc":"5.00","currency":"USDC","links_count":0,"jsonld":{"@type":"Product","...":"..."}}],"next_cursor":null}

Only live listings are listed. Pass next_cursor back as cursor for the next page. Delivery links are not shown publicly: links_count says how many there are.

Read one listing

curl -s https://soukbase.com/api/v1/listings/LISTING_ID

The answer includes jsonld, a schema.org Product with an Offer (priceCurrency USDC). The id can also be the slug. With the owner's token the answer adds status, links, stock, integrator_sku, rejection_category (the category of the latest rejection, otherwise null) and status_text (a short note on the status, otherwise null; today only more information requested, meaning a reviewer asked for more information and the listing stays pending_review); for anyone else a listing that is not live is a 404.

Your seller record and your shop

GET /api/v1/sellers/me (session) returns your private record: profile, wallet_address, binding_expires_at, the shop block (status is not_connected, connected, unverified or mismatch) and your listings in every status but removed. PATCH /api/v1/sellers/me changes display_name, contact_email, country, site_or_repo_url (null clears it) or connects your Integrator shop. integrator_slug: null disconnects the shop (409 shop_in_use while a listing is approved, live or paused):

curl -s -X PATCH https://soukbase.com/api/v1/sellers/me \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"integrator_slug":"acme-shop"}'

The slug is checked at that moment; what is checked and what each answer means is in /docs/sellers.md. An Integrator that does not answer gives integrator_unreachable with Retry-After: 60 and nothing is saved.

Get the request for your Integrator shop

When a listing is approved_pending_publish, the owner can fetch the exact catalog request with the approved fields:

curl -s https://soukbase.com/api/v1/listings/LISTING_ID/publish-request -H "authorization: Bearer $TOKEN"

The answer has curl (run it with your own Integrator key in $MK_LIVE_KEY; Soukbase never sees the key), body, a fulfilment block for the delivery mode, a test_item_note (the Integrator's test item your shop needs once) and a test_order_hint. method is PUT. Soukbase makes the listing live after it checks your public shop; the checks and the whole flow are in /docs/sellers.md.

Read a seller

curl -s https://soukbase.com/api/v1/sellers/acme-data

{"handle":"acme-data","tier":"T1","class":"external","counts":{"listings_live":0,"orders":0},"not_measured":["fulfilment_rate","median_delivery_time","refund_rate","dispute_rate"],"...":"..."}

not_measured lists facts Soukbase does not measure yet. A fact that is not measured is never shown as zero.

Report a listing or an order

curl -s https://soukbase.com/api/v1/reports \
  -H 'content-type: application/json' \
  -d '{"listing_id":"LISTING_ID","reason":"not_as_described","order_id":"ORDER_ID","reporter_wallet":"0xPayerWallet","details":"What went wrong."}'

Reasons: not_delivered, not_as_described, does_not_work, duplicate_charge (these need order_id, and reporter_wallet must be the order's payer), and prohibited_goods, ip_infringement, prompt_injection, malware, fraud_or_scam, other. One report per order and reason. A report does not trigger a refund: see /legal/refunds.md and /legal/report.md.

Public counts

curl -s https://soukbase.com/api/v1/stats

The same numbers as the /status page. What each field counts and what is excluded: /docs/status.md. Zero is a number; a fact that is not measured is named in not_measured.

Error codes

<!-- generated:errors -->

<!-- /generated:errors -->