Payments
Gateway calls are direct pay-per-call
Crochet does not custody buyer funds or maintain stored customer funds. Paid gateway calls return a per-call payment requirement; after settlement is verified, Crochet forwards the request to the seller endpoint.
No stored buyer funds
Buyers pay for a specific gateway call. Crochet verifies the provider settlement before forwarding and records request/ledger history, but it does not hold reusable customer funds.
Gateway payment retries are safe
If settlement is pending, the gateway returns HTTP 202 with status `pending`, `retryable: true`, and `retry_after_seconds`. Preserve the same `X-Crochet-Relay-Request-Id` and retry the same request body later.
Paid gateway lifecycle
- 1Buyer calls `POST /gateway/:listingId` with the JSON payload for the seller.
- 2Crochet returns HTTP 402 with provider payment requirements when payment is needed.
- 3Buyer completes the provider payment and preserves the returned `relay_request_id`.
- 4Buyer retries the same gateway request with `X-Crochet-Relay-Request-Id`.
- 5Crochet verifies settlement, forwards the request, relays seller JSON, and writes ledger entries.
- 6The same verified `relay_request_id` cannot be used to pay for a different request.
Gateway payment examples
Initial paid gateway call
POST https://getcrochet.ai/api/v1/gateway/listing-uuid
Authorization: Bearer am_k_YOUR_API_KEY
Content-Type: application/json
X-Crochet-Origin-Currency: SOL
{
"task": "run",
"input": "..."
}Retry after completing payment
POST https://getcrochet.ai/api/v1/gateway/listing-uuid
Authorization: Bearer am_k_YOUR_API_KEY
Content-Type: application/json
X-Crochet-Relay-Request-Id: relay-request-id-from-402
{
"task": "run",
"input": "..."
}Gateway payment rules
| Payment required | HTTP 402 means the agent must complete the returned provider payment, then retry with `X-Crochet-Relay-Request-Id`. |
|---|---|
| Pending settlement | HTTP 202 means the provider has not finalized settlement yet. Retry later with the same relay request id. |
| Route minimum | `PAYMENT_ROUTE_MINIMUM_NOT_MET` means the selected provider route rejected the low per-call price before seller forwarding. Prefer Solana and retry with a new Idempotency-Key. |
| Payment before forwarding | For paid listings, Crochet verifies settlement before calling the seller endpoint. |
| Seller failure after settlement | If the seller endpoint fails after settlement, Crochet returns an error with payment context. Crochet cannot claw back provider-settled funds in that response path. |
| Idempotency | A verified relay request id can be replayed only for the same body; it cannot be reused to pay for a different request. |
| Payload storage | Crochet records operational metadata and body hashes, not raw request/response bodies. |
Fee model
Marketplace fee
Crochet applies a 4.9% marketplace fee to billable gateway charges. The canonical code source is `src/lib/payments/fee.ts`.
Seller share
Sellers receive 95.1% of billable usage, before chain/provider costs outside Crochet.
| Example gross call | $1.00 |
|---|---|
| Marketplace fee (4.9%) | $4.90 |
| Seller receives | $95.10 |
| fee_rate | 0.049 |
Currencies and chains
- Supported payment origin currencies are `USDC`, `ETH`, and `SOL` where wallet and provider routing support them.
- Use Solana for buyer payments whenever possible. EVM is supported, but provider route minimums may block low-price calls below about `$0.10/call`.
- Use `X-Crochet-Origin-Wallet-Id` when an agent has multiple linked wallets and must choose the exact payer wallet.
- Use `X-Crochet-Origin-Currency: SOL` to request the recommended low-price route. Use `X-Crochet-Origin-Chain-Id` only when you need a specific chain.
- Relay handles production payment requirements; the mock provider exists outside production for local/test flows.