Usage and cost

Every successful reply reports its charge and the model that served it. Credits are the account balance that pays for requests when a key or the chat app is set to credits: the signup credit every new account starts with, and credits bought by card. Credit charges debit that balance; USDC charges settle on chain.

On the response

"usage":  { "prompt_tokens": 18, "completion_tokens": 52, "total_tokens": 70 },
"katara": { "cost_usdc": "0.000018", "provider": "0xfFe5…38DC" }

cost_usdc is a decimal string in USDC. provider is the address of the provider that served you, or managed when a vendor answered. Both named-model and Cortex replies include katara.served.model, the concrete model id. Provider replies also name the bundle and provider in that block.

For a Credits request, the charge uses the existing cost_usd field with billing_method: "credits". Despite the legacy field name, display the amount as Credits without a dollar sign:

"katara": {
  "billing_method": "credits",
  "cost_usd": "0.000018",
  "served": { "model": "katara/deepseek-chat@1" }
}

A request paid with x402 also carries katara.payment: the scheme it was paid with, the network, the token and amount, the charge in the token’s base units, which is the amount in its PAYMENT-RESPONSE header. Its cost_usdc is that charge, the 0.025 USDC minimum included.

In a stream the katara object arrives as a final chunk with an empty choices array, after usage and before [DONE]. Chat labels each reply with the selected model’s friendly name, or Katara Cortex when Cortex was selected. The detail line shows the model that served it.

What counts as output

Output tokens are what you received, measured with the model’s own tokenizer: the assistant text, and for each tool call its name and its argument document. A model’s private syntax around a call, anything Katara refused, and the runtime’s own token report are not billed. Both the provider and Katara compute the count independently from the same delivered content, and a reply only settles when the two agree exactly.

Input tokens come from the runtime’s count of the rendered prompt, bounded by the size of your request.

Retries

Every request is charged at most once. A USDC reply settles against its own signed receipt, and a receipt can settle once. A Credits request finalizes one reservation for its delivered usage. A failed attempt on one provider is retried on another inside the same request and never charged. If you retry a request yourself after a timeout, that is a new request. The chat apps’ own service honours an Idempotency-Key header; the marketplace API does not read it.

Bounding cost

max_tokens bounds the output and so the maximum charge. The admission check uses it: a request whose maximum exceeds your spendable balance is refused before any work. Keep max_tokens honest for what you need and long prompts will fit in a smaller balance.

Reconciling

The portal’s usage page lists every request with its id, model, tokens, and cost. Match rows to your logs by x-katara-request-id. USDC settlements are visible on chain under your wallet address. Credits purchases, reservations and debits are available in the billing statements.