Seller Endpoints

All seller endpoints require authentication via one of:

• si_seller_ API key: Authorization: Bearer si_seller_xxx (programmatic access)
• Privy session cookie (web UI)

A si_seller_ key cannot access buyer endpoints, and vice versa. Session cookies work for both.

Authentication — SIWE (Sign-In With Ethereum)

Get a seller API key using wallet signature auth. No browser needed.

Get Challenge

GET /v1/seller/auth/challenge?address=0xYourWallet

{
  "message": "www.surplusintelligence.ai wants you to sign in...",
  "nonce": "abc123def456",
  "expires_at": 1713312000000
}

Issue Key

POST /v1/seller/auth/keys
{
  "message": "<SIWE message from challenge>",
  "signature": "0x...",
  "label": "my-bot",           // optional
  "expires_at": 1713398400000  // optional, ms timestamp
}

{
  "key": "si_seller_abc123def456...",
  "id": "01JQ8G7YV3M4N5P6Q7R8S9T0AB",
  "wallet": "0xYourWallet",
  "label": "my-bot",
  "created_at": 1713312000000
}

Manage Keys

Once you hold one seller key (or a web session), you can mint and manage more programmatically, no browser required. Seller keys support create, list, and revoke. (Rename and per-key routing preferences are buyer-only, since a seller key carries no routing config.)

POST /v1/seller/keys
Authorization: Bearer si_seller_xxx
Idempotency-Key: 9f8c1e2b-...     # required
{ "label": "batch-bot" }
# → {
#     "id": "01JQ8G7YV3M4N5P6Q7R8S9T0AB",
#     "key": "si_seller_9f8c1e2b...",   # shown once
#     "key_prefix": "si_seller_9f8c1e2b",
#     "label": "batch-bot",
#     "created_at": 1713312000000
#   }

GET /v1/seller/keys
Authorization: Bearer si_seller_xxx

DELETE /v1/seller/keys/{keyId}
Authorization: Bearer si_seller_xxx

Offers

POST /v1/seller/offers
Authorization: Bearer si_seller_xxx
Idempotency-Key: 9f8c1e2b-...     # required
{
  "model": "claude-opus-4.6",
  "api_key": "your-provider-api-key",
  "seller_base_url": "https://api.venice.ai/api/v1",
  "pricing_mode": "cost_multiplier",
  "cost_multiplier": 0.50,
  "cap_daily_usd": 100.00,
  "payout_address": "0xOptional..."
}

PATCH /v1/seller/offers/{id}
Authorization: Bearer si_seller_xxx
{ "cost_multiplier": 0.45 }

DELETE /v1/seller/offers/{id}
Authorization: Bearer si_seller_xxx

GET /v1/seller/offers
Authorization: Bearer si_seller_xxx

GET /v1/seller/offers/{id}
Authorization: Bearer si_seller_xxx

Bulk Create

POST /v1/seller/offers/bulk
Authorization: Bearer si_seller_xxx
{
  "api_key": "your-provider-api-key",
  "base_url": "https://api.venice.ai/api/v1",
  "offers": [
    { "model": "claude-opus-4.6", "cost_multiplier": 0.5 },
    { "model": "gpt-5.4", "cost_multiplier": 0.5 }
  ]
}

Offer operations

POST /v1/seller/offers/bulk-cancel
Authorization: Bearer si_seller_xxx
# no body: cancels every active offer
# → 202 { "operation_id": "...", "object": "operation", "status": "queued", "created": 1713312000 }

POST /v1/seller/offers/bulk-update
Authorization: Bearer si_seller_xxx
{ "action": "cancel", "provider": "openrouter" }
# or { "action": "reset_health", "offer_ids": ["01JQ8G7YV3M4N5P6Q7R8S9T0AB"] }
# → 202 { "operation_id": "...", "object": "operation", "status": "queued", "created": 1713312000 }

POST /v1/seller/offers/{id}/reset-health
Authorization: Bearer si_seller_xxx

POST /v1/seller/offers/{id}/rotate-credential
Authorization: Bearer si_seller_xxx
{ "api_key": "new-provider-key" }

GET /v1/seller/operations/{id}
Authorization: Bearer si_seller_xxx
# → { "id": "...", "status": "succeeded", "processed": 12, "total": 12, "failed_count": 0 }

Model Discovery

POST /v1/seller/discover
Authorization: Bearer si_seller_xxx
{ "api_key": "your-provider-api-key", "base_url": "https://api.venice.ai/api/v1" }

Test Connection

POST /v1/seller/test-connection
Authorization: Bearer si_seller_xxx
{ "api_key": "your-provider-api-key", "base_url": "https://api.venice.ai/api/v1", "model": "claude-opus-4.6" }

Earnings

GET /v1/seller/earnings
Authorization: Bearer si_seller_xxx

GET /v1/seller/earnings?range=mtd
Authorization: Bearer si_seller_xxx

Earnings History

Cursor-paginated sale history, deeper than the 20-row earnings teaser. Params: limit (default 25, max 50), cursor, workspace_id. Returns recent_sales[] (the same row shape as the teaser, with no buyer) + next_token.

Filters, each combined with the others: from / to (inclusive; an ISO-8601 instant or a YYYY-MM-DD UTC day, which to covers whole), model (comma-separated, up to 20), offer_id (comma-separated, up to 10 of your own offers; any other is 404 offer_not_found), and settlement (comma-separated: pending, owed for credit-rail sales not yet paid out, paid, or confirmed for every settled sale, owed and paid together). A filtered page reads a bounded amount of history per call, so it can come back short, even empty, while next_token is still present; it then says truncated: true. Keep paging until next_token is absent. Several offers come back as one list, newest first, and their next_token only works with the same offer_id set (another set is 400 invalid_cursor). Filtered reads never return totals.

Usage Export

Your sales record as CSV. Redirects (302) to a short-lived presigned download. Params: from, to, limit, format=csv, workspace_id.

Bounded, not complete. A single export returns at most 50,000 rows (or a lower limit you pass). When rows remain beyond the cap the response carries x-si-export-truncated: true, and the CSV you downloaded is a partial record. Check that header on every export and narrow the from/to window until it is absent, especially before using the output as a reconciliation or tax ledger.

Columns: request_id, settled_at, model, input_tokens, output_tokens, seller_earned_usd, settlement_status, settlement_type, tx_hash. Rows are not filtered by outcome: pending and failed settlements are exported too, so within the row cap this is your raw ledger rather than an earnings summary. The settlement_status column is per-request: under batched payouts most rows stay accrued even after their earnings were paid, so read Settlement and payout lifecycle before treating an accrued count as unpaid exposure.

Health Log

GET /v1/seller/health-log
Authorization: Bearer si_seller_xxx

Payouts

GET /v1/seller/payouts
Authorization: Bearer si_seller_xxx

POST /v1/seller/payouts/withdraw
Authorization: Bearer si_seller_xxx
{ "self_submit": false }

# `destination` (optional) DELIBERATELY OVERRIDES the recipient frozen at accrual and
# consolidates every pending payout group into one transfer to that address. It is
# authorized by the API key alone — treat a seller key that can call this as able to
# redirect your earnings, and scope it accordingly.
# Response `status` is one of: scheduled | authorized | nothing_pending | held
#   scheduled      - claimed; the drain broadcasts it and we pay the gas
#   authorized     - `self_submit: true` only; carries the signed EIP-3009 `authorization`
#                    for you to broadcast yourself
#   nothing_pending- nothing is payable right now
#   held           - eligible but withheld; carries a `hold_reason`, and a `releases_at`
#                    (epoch ms) only when every withheld group clears on a clock
# See Settlement and payout lifecycle below.

POST /v1/seller/payouts/submitted
Authorization: Bearer si_seller_xxx
{ "payout_id": "...", "tx_hash": "0x..." }

Settlement and payout lifecycle

Your earnings and your payouts are two separate tracks, and conflating them is what produces the "my sales are up but my balance is not" question. Earnings accrue per request the moment each response completes. Payouts are batched: they are grouped by payout recipient and sent when a group becomes eligible, not once per request. So a request can be fully earned and fully paid while its individual row still reads accrued.

Request-level status vs payout position

The CSV from Usage Export carries a per-request settlement_status. Your payout position carries account-level amounts. They answer different questions.

Per-request settlement_status (one value per row in your usage CSV):

Payout position (account-level, from GET /v1/seller/payouts):

Why so many rows stay accrued

Because a batched payout pays a group, not a request, there is no one-for-one accrued to confirmed transition for most rows. When the system can cheaply join a paid batch back to an individual row it will flip that row to confirmed and stamp the hash, but that is a display-only writeback and it does not cover every row. Rows paid as part of a group legitimately remain accrued.

Worked example. Say you made tens of thousands of credit-rail sales worth 250 USDC. Your usage CSV shows tens of thousands of rows at settlement_status = accrued, and almost none at confirmed. Your GET /v1/seller/payouts history shows a handful of rows with status: "paid" that sum to ~250 USDC, each with its own Base tx_hash. Those batches paid the accrued rows. The rows were never rewritten one by one, so their status still reads accrued. Nothing is missing.

When earnings get paid

A payout group becomes eligible for an automatic payout when either of these is true:

• its available balance reaches 5 USDC, or
• its oldest available earning reaches 72 hours (the age_due_at on the group).

The 5 USDC floor is an operational knob rather than a contractual number, so read the current figure from threshold_usdc on the payout response rather than hard-coding it in your own tooling.

A scheduler evaluates eligibility on a roughly 10-minute cadence and pays the groups that qualify. Manual review is not part of the normal cycle. It applies only to exceptional states (a payout hold, or an attempt that needs operator recovery), covered below. A group's next_trigger tells you which rule it is waiting on:

Both triggers above belong to the automatic run. "Payout now" (POST /v1/seller/payouts/withdraw) has neither: a manual claim takes any group with an available balance and a payable recipient, however small and however recent. manually_claimable on each group is that same decision, so the button and the claim can never disagree. It is still subject to a hold.

How to confirm you were paid

The authoritative record of payment is your payout history and its Base transaction hash, never the per-request accrued count.

• In GET /v1/seller/payouts, a history entry with status: "paid" and a tx_hash is a completed payment. There is exactly one hash per seller per payout, so you can point at your own transaction on Base without it being entangled with any other seller's payment.
• The recipient wallet for each group is the group's recipient, frozen when those earnings accrued. recipient_source tells you only whether that destination is payable (resolved) or could not be resolved to an address (unresolved); it does not name which rule produced it.

Payout groups and recipient overrides

Balances are split across payout-recipient groups. You have one group per distinct payout recipient, so a seller whose offers all pay to the same wallet has exactly one. If some offers set a payout_address override, the recipient is frozen at accrual and those earnings form their own group with their own trigger and their own transaction. Merging them would pay one recipient money owed to another, so each group is claimed and paid independently. A seller with an offer-level override and an org default therefore sees two rows in groups, each reaching the 5 USDC or 72-hour trigger on its own.

If a payout looks stuck

These are exceptional and are not the normal cycle. If you see one, it is a signal to look closer, not to assume everything is fine.

• held (a group whose next_trigger is risk_hold or new_seller_hold, or a withdraw that returns status: held). A new_seller_hold is the ordinary first-payout waiting period and clears on its own: the group carries hold_release_at (ISO-8601) and a withdraw response carries releases_at (epoch ms). A risk_hold is a manual review and carries no countdown. If a hold does not lift when you expect it to, contact support.
• In-flight far longer than a cycle. A balance that sits in in_flight_usdc well beyond a normal payout window, rather than settling to paid, is worth reporting. In history that shows up as an entry stuck at claimed or submitting.
• needs_operator in your payout history. A payout attempt whose outcome could not be determined automatically (for example an on-chain broadcast with no readable receipt) is parked for operator recovery. The safe design is to hold it rather than risk paying twice, so this status is terminal for automation and will not self-resolve. Contact support with the payout_id.
• failed in your payout history. A recoverable failure, carrying an error. A later run re-drives it; if the same one persists across days, report it.

In any of these cases, contact support with your wallet address and, if you have it, the payout_id. Do not assume a stuck payout is normal batching latency.

Saved Provider Configs

Reusable saved provider-key cards (base URL + key fingerprint + hint, plus credential_kind / credential_prefix when known; the key itself is never returned). Cards are created as a side effect of creating an offer, so there is no create endpoint here: management is list + delete. List them, or DELETE /v1/seller/configs/{id} to remove one. Bulk offer creation, discovery, and health probes can reuse a saved key via reuse_key_fingerprint instead of re-sending api_key.

Rate Limits

Seller routes are metered in per-minute buckets, scoped to your API key (or your session, or your IP when neither is present). The bucket is aggregate per caller, not per path: every route in a class shares one counter.

429 responses include Retry-After (seconds), and every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (Unix timestamp).

A separate edge WAF rule also blocks any single IP past 6,000 requests per 5-minute window (about 1,200/min), before the application sees the request. This ceiling is shared by all keys and routes using that source address.

These route limits are API-abuse controls. They are not a marketplace-side spend ceiling for provider usage. For provider-quota protection, use cap_daily_usd and provider-side API-key limits where available. There is no per-week or per-month USD cap on marketplace seller offers today.

Key Storage and Deletion

Seller provider API keys are encrypted at rest with AES-256-GCM under AWS KMS envelope encryption: a per-secret data key is requested from KMS, used to encrypt the plaintext, and the ciphertext plus the KMS-encrypted data key are stored in a private S3 bucket. The server decrypts keys only when it needs to call the seller's provider endpoint or run seller-owned management actions such as discovery/test-connection/health reset.

Deleting an offer is currently a soft delete: active = false on the offer record, removed from routing, encrypted API key retained in storage. There is no self-serve hard-delete endpoint yet. Sellers should revoke deleted offer keys at their upstream provider if immediate invalidation is required.

See Security & Privacy for the full current trust model.

Error Responses

All errors follow the format:

{
  "error": {
    "message": "Human-readable description",
    "type": "authentication_error | authorization_error | invalid_request_error | rate_limit_error | server_error"
  }
}