Documentation — ClawFarm

Buyer quickstart

Contact the ClawFarm team to receive a one-time cfk_* API key and bind a public Solana Mainnet wallet. Fund that wallet with native Mainnet USDC before sending paid traffic. Never provide the wallet's private key or seed phrase.

ClawFarm does not require an SDK. Call AIRouter from a trusted server environment using the issued key and a model returned by the models endpoint.

Environment

export CLAWFARM_GATEWAY_URL="<gateway-url>"
export CLAWFARM_API_KEY="<issued-cfk-key>"

Discover models

curl "$CLAWFARM_GATEWAY_URL/clawfarm/v1/models" \
  -H "Authorization: Bearer $CLAWFARM_API_KEY"

Send a chat completion

curl "$CLAWFARM_GATEWAY_URL/clawfarm/chat/completions" \
  -H "X-Api-Key: $CLAWFARM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-id>",
    "messages": [
      {"role": "user", "content": "What is proof-based settlement?"}
    ]
  }'

Authentication

Use either accepted header form. Do not send both, log the credential, or expose it in browser-delivered JavaScript.

Authorization: Bearer $CLAWFARM_API_KEY

# or
X-Api-Key: $CLAWFARM_API_KEY

API key

A one-time cfk_* credential issued during Buyer onboarding.

Bound wallet

The public Mainnet wallet registered to the active billing configuration.

Funding

Native Solana Mainnet USDC funds paid inference; maintain the balance before sending traffic.

HTTP routes

AIRouter exposes protocol-compatible request surfaces. Use the path matching the request and response format already used by your application.

GET /clawfarm/v1/models

Lists the model IDs currently exposed through ClawFarm.

GET /clawfarm/v1/model-quota

Returns quota information for the authenticated Buyer and selected model context.

POST /clawfarm/chat/completions

OpenAI-compatible chat completions.

POST /clawfarm/v1/responses

OpenAI-compatible Responses requests.

POST /clawfarm/v1/messages

Anthropic-compatible Messages requests.

POST /clawfarm/google/v1/models/<model>:generateContent

Google-compatible generated content, including the corresponding :streamGenerateContent form.

POST /clawfarm/models/<model>:generateContent

Short Google-compatible path, also supporting the streaming method suffix.

Asynchronous settlement

AIRouter authorizes traffic against the active billing configuration and its bound wallet, meters the request, persists a receipt, and queues the masterpool v3 settlement path. The inference response does not wait for on-chain finalization.

X-ClawFarm-Request-Nonce

Request identity used for payment, proof, and settlement lookup.

X-ClawFarm-Payment-Status

settlement_pending means a durable receipt exists and settlement is queued; it is not a final on-chain confirmation.

X-ClawFarm-Max-Charge-Atomic

Maximum authorized charge in atomic USDC units.

X-ClawFarm-Charge-Atomic

Metered charge when available on the response.

X-ClawFarm-Receipt-Hash

Receipt identity when emitted by the asynchronous settlement path.

Public proof and settlement lookup surfaces can resolve records by request nonce or receipt hash. Preserve those response values with your application logs, without logging the API key.

Provider onboarding

Contact the ClawFarm team. Provide the supported API protocol, upstream base URL, model catalog, pricing, quota, rate limits, timeout constraints, and the public Solana Mainnet provider wallet.

Deliver the upstream API key only through the secure channel agreed with the team. ClawFarm verifies the upstream, stores the key encrypted, configures AIRouter, and bootstraps ProviderAccountV3. Never send a provider private key, seed phrase, or wallet file.

Provider metadata

Endpoint, models, pricing, limits, and upstream credentials remain in the off-chain AIRouter operator layer.

ProviderAccountV3

Stores the provider wallet, pending provider USDC, status, and timestamps.

Current registration stake

register_provider_v3 initializes staked_usdc_amount to zero and transfers no upfront stake.

Configuration parameter

Mainnet GlobalConfigV3 stores a 100 USDC provider-stake parameter, but the current registration instruction does not collect it.

Open the full Provider onboarding checklist →

Current contract shape

Masterpool v3 is the protocol source of truth for payment and epoch settlement. AIRouter owns endpoint selection, model metadata, usage metering, receipt persistence, and settlement orchestration; those fields are not stored in ProviderAccountV3.

Payment recording

Records payer and provider identities, base charge, configured tax, payment index state, and epoch aggregates.

Vault movement

Tax moves to treasury and base USDC moves to provider pending when the payment is recorded.

Settlement batches

Authorized submissions commit usage, provider, and buyer roots with aggregate totals for an ended epoch.

Challenges

Accepted challenges invalidate bad pending batches; rejected challenges restore the batch to pending.

Claims

Finalized roots authorize Merkle-proof claims for provider USDC, provider CLAF, and Buyer CLAF.

Payment lifecycle

1. AIRouter authenticates the cfk_* key and resolves its active wallet-bound billing configuration.
2. AIRouter selects an eligible upstream provider and bounds the maximum USDC charge.
3. The upstream response is metered and a durable ClawFarm receipt is persisted.
4. The response returns with settlement_pending while asynchronous settlement is queued.
5. Masterpool v3 records the payment and moves tax and base USDC into their respective vaults.
6. After the epoch ends, an authorized submitter commits aggregate settlement roots.
7. A valid batch finalizes after review; Merkle proofs then authorize provider and Buyer claims.