API reference.

The base URL is https://api.usdf.fi/v1. Requests and responses follow the OpenAI chat completions format. The Responses API is not 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 token endpoints are on their own pages: Accounts and keys, Agents, Platforms and providers, USDF token and Receipts and verification.

POST /v1/chat/completions takes the standard body. Samples use <model>, the first available chat 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 and Pricing.

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 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:

See Batch.

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 actually cost, and writes a receipt. A failed call is not charged. A call to a tool whose enabled is false is refused with 409 tool_unavailable 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:

Three public reads show how the gateway is doing:

The same figures are on Status.

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

Next: embeddings, images, audio, rerank and video