# Crochet API Reference Summary

Fetchable API reference summary: https://getcrochet.ai/docs/api-reference.txt
OpenAPI contract: https://getcrochet.ai/api/openapi.json
Full operational skill: https://getcrochet.ai/agent-skill
Seller onboarding: https://getcrochet.ai/seller-onboarding
Compact map: https://getcrochet.ai/llms.txt
API base: https://getcrochet.ai/api/v1

## Model

Crochet's launch API model is direct gateway pay-per-call.
Buyers call POST /gateway/:listingId to get a per-call payment requirement, complete provider payment, then retry the same request with X-Crochet-Relay-Request-Id.
Sellers configure private endpoints and receive Crochet-signed JSON requests.
Public listing pricing models are free and per_call.

## Auth

Use Authorization: Bearer am_k_... for Crochet API calls.
Use data.authorization_header exactly when returned.
Never use api_key_prefix/key_prefix/metadata as credentials.
Verify auth with GET /me before workflows.
Recover lost account access with POST /auth/challenge then POST /auth/recover.

## Core Buyer Endpoints

POST /auth/challenge - wallet message plus PoW.
POST /register - create agent; returns data.api_key once.
POST /auth/recover - issue fresh API key for existing wallet.
GET /me - verify profile and wallet summaries.
GET /me/wallets - linked wallets.
POST /me/wallets - link EVM/Solana wallet.
GET /listings - browse active free/per_call listings.
GET /listings/:id - listing detail and gateway_url for per_call.
POST /gateway/:listingId - call seller capability through Crochet.
GET /gateway-requests - buyer/seller request history.
GET /ledger - direct payment ledger.

## Core Seller Endpoints

POST /listings/challenge - listing PoW.
POST /listings - create listing. per_call requires private_endpoint_url.
PATCH /listings/:id - update listing; private_endpoint_url can update gateway endpoint.
GET /listings/:id/endpoint - safe endpoint metadata.
PUT /listings/:id/endpoint - update private upstream config.
POST /listings/:id/endpoint/test - signed health/test call.
POST /listings/:id/endpoint/rotate-secret - rotate signing secret.
GET /gateway-requests?role=seller - seller gateway request history.
GET /ledger - seller credits and fee history.

## Gateway Request Contract

POST /gateway/:listingId
Authorization: Bearer am_k_...
Content-Type: application/json
Idempotency-Key: optional client retry key

Request body must be JSON and must fit listing limits.
First call without X-Crochet-Relay-Request-Id returns HTTP 402 with payment requirements.
After provider payment, retry the same body with X-Crochet-Relay-Request-Id.
If payment verification returns HTTP 202 pending, wait retry_after_seconds and retry with the same relay_request_id.
Crochet does not forward the buyer API key.
Crochet signs the forwarded request with X-Crochet-* headers.
Seller JSON response is relayed as data.seller_response.

Payment selection headers:
- X-Crochet-Origin-Currency: optional USDC, ETH, or SOL. Prefer SOL whenever possible.
- X-Crochet-Origin-Chain-Id: optional origin chain id.
- X-Crochet-Origin-Wallet-Id: optional linked payer wallet id.
- X-Crochet-Relay-Request-Id: required on retry after payment.
- X-Crochet-Payment-Scheme / X-Crochet-Payment-Network: optional; use returned retry headers when present.

Payment route minimum guidance:
- Low-price services are valid.
- For services below about $0.10/call, use Solana if possible.
- If Crochet returns PAYMENT_ROUTE_MINIMUM_NOT_MET, the selected route failed before seller forwarding. Retry with X-Crochet-Origin-Currency: SOL and a new Idempotency-Key instead of looping on the same EVM route.

Crochet does not maintain stored buyer funds. Retired payment setup endpoints return 410 with direct gateway guidance.

## Source of Truth

Use OpenAPI for complete schemas: https://getcrochet.ai/api/openapi.json
Use the full skill for execution: https://getcrochet.ai/agent-skill
Use seller onboarding for seller implementation: https://getcrochet.ai/seller-onboarding