API reference.

The base URL is https://api.usdf.fi/v1. Requests and responses follow the OpenAI chat completions format. Messages and stateless Responses are also served.

Two ways to pay for a request:

• No account: send the same body with no key to the same path under https://api.usdf.fi/x402 and pay per request in USDF.
• A prepaid balance: send Authorization: Bearer sk_… to the path below.

The model endpoints and the reads around them, with what each needs:

Public data, with no key. Each one backs a page of the site:

Every limit these reads share is in Rate limits. Account, agent, platform and receipt endpoints are on their own pages: Accounts and keys, Agents, Platforms and providers and Receipts. Every endpoint, token and receipt reads included, is in the API reference.

POST /v1/chat/completions takes the standard body. Samples use <model>.

curl https://api.usdf.fi/v1/chat/completions \
  -H "Authorization: Bearer $USDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 256
  }'

x-request-id: <request_id>
x-cost-units: <units>

{
  "id": "<request_id>",
  "object": "chat.completion",
  "model": "<model>",
  "choices": [{ "index": 0, "message": { "role": "assistant", "content": "…" }, "finish_reason": "stop" }],
  "usage": { "prompt_tokens": …, "completion_tokens": …, "total_tokens": … },
  "receipt": { "request_id": "<request_id>", "status": "ok", "cost": { … }, … }
}

The parameters the gateway reads:

• The deprecated functions and function_call are refused with 400 unsupported_parameter. Use tools.
• Fields that would change what the provider bills are dropped.
• Up to 16 images per request. More gets 400 too_many_images.
• The response id is the request id, also in the x-request-id header. A response that is not streamed carries the cost in x-cost-units; a stream carries it in its receipt line.

How the hold is sized

The prompt is held at two bytes per token, plus eight tokens per message and 16 per request, plus max_tokens. A model with long-context rates is held at one byte per token, so the hold never lands in a cheaper tier.

Without max_tokens, the model's default output budget is held, shrinking to what the balance covers. The charge is the provider's reported usage; the rest of the hold is released.

Set "stream": true for server-sent events in the standard chunk format.

The order of events:

data: {"id":"<request_id>","object":"chat.completion.chunk",…}

data: {"id":"<request_id>","choices":[],"usage":{…}}

: receipt {"request_id":"<request_id>","cost":{"units":"…","usd":"…","usdf":"…"},…}

data: [DONE]

The receipt arrives as a comment line just before [DONE]. Standard clients drop comment lines, so read the receipt by id afterwards with GET /v1/receipts/{id}. Every chunk's id is the request id.

curl -N https://api.usdf.fi/v1/chat/completions \
  -H "Authorization: Bearer $USDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "stream": true,
    "stream_options": {"include_usage": true},
    "messages": [{"role": "user", "content": "Hello"}]
  }'

POST /v1/completions serves only models whose endpoints include completions. prompt is a string, or an array of one string.

curl https://api.usdf.fi/v1/completions \
  -H "Authorization: Bearer $USDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "prompt": "The capital of France is",
    "max_tokens": 16
  }'

GET /v1/models lists what serves now. GET /v1/pricing is the full sheet, every listed model with its prices and routes.

The fields of GET /v1/pricing:

Each price sheet promises its rates for 30 days. Every sheet ever served is at GET /v1/pricing/sheets, and the signed catalog at GET /v1/catalog. Browse them on Models.

Compute locks

A compute lock fixes your price on a block of one model for a month. Each series is a token: one whole token is a million tokens of its model at the locked price, until the month ends. GET /v1/locks has the rules and, signed in, each series with its book.

With one of your account's keys or your session, POST /v1/locks/quote prices a buy, and POST /v1/locks/orders buys at market, places a limit order, or sells what you hold. Your requests for that model then use the lock first: the series' provider serves them, their tokens burn at the locked price, and the receipt names the series. GET /v1/locks/mine lists your holdings, orders and uses, and a holding can be withdrawn to your linked wallet.

A batch job runs at the upstream's batch rate. Submit it with a :batch model suffix or "batch": true, without stream. Add webhook_url to be told when it ends.

A job runs on a model whose price carries batch_input in GET /v1/pricing.

curl https://api.usdf.fi/v1/chat/completions \
  -H "Authorization: Bearer $USDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model with batch rates>:batch",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 256,
    "webhook_url": "https://example.com/usdf-hooks"
  }'

{
  "object": "batch.job",
  "id": "batch_…",
  "status": "submitted",
  "rate": "batch",
  "hold": { "units": "<units>", "usd": "<usd>", "usdf": "<usdf>" },
  "price": { … },
  "poll": "https://api.usdf.fi/v1/batches/batch_…",
  "result": "https://api.usdf.fi/v1/batches/batch_…/result"
}

Poll the job, then fetch its result: the completion and its receipt, which settles like every other request. Results return within 24 hours. The result is kept 7 days, then answers 410.

curl https://api.usdf.fi/v1/batches/<batch id> \
  -H "Authorization: Bearer $USDF_API_KEY"

curl https://api.usdf.fi/v1/batches/<batch id>/result \
  -H "Authorization: Bearer $USDF_API_KEY"

How a job ends:

The hold is taken at the standard rate and the charge is made at the batch_* rates when the result arrives.

A job is refused, and nothing is charged, in these cases:

GET /v1/tools is public. Each tool lists its price (flat per call, or a base plus a price per result), its enabled flag, and its input_schema.

POST /v1/tools/{id} with a key runs one. The body is the tool's input. A call takes a hold, charges what it cost plus 5% at most, with no minimum, and writes a receipt. A call the tool's upstream refused or never answered costs nothing; one that failed after the upstream answered is charged what the upstream billed for it. A call to a tool whose enabled is false is refused with 409 tool_unavailable before any hold.

web.search and web.scrape send the query or the page to a search service that keeps its own records, so they run for calls that opt in to retention: "provider": {"allow_retention": true} in the input, or the key's or the account's opt-in. A call without it is refused with 409 retention_required before any hold.

The tools, read live:

The sample sends the required fields of the tool's input_schema.

curl https://api.usdf.fi/v1/tools/<tool id> \
  -H "Authorization: Bearer $USDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

The headers the gateway reads and sends:

Two public reads show how the gateway is doing:

curl https://api.usdf.fi/health

Next: embeddings, images, audio, rerank and video