API reference
Jev evaluations, model discovery, Chat Completions, and x402 response formats.
Base URL: https://agents.naven.network/ai-gateway/v1
Send JSON with Content-Type: application/json. Model discovery is free and requires no API key. Paid requests use PAYMENT-SIGNATURE. Responses set Cache-Control: no-store.
GET /models
Returns HTTP 200 with the Vercel model catalog compatible with this endpoint's bounded text Chat Completions contract. There is no pagination: data contains every currently compatible model. The catalog is refreshed automatically, so clients should discover models here instead of maintaining a static allowlist.
| Field | Meaning |
|---|---|
object | list. |
available | Whether the gateway is configured to accept new calls and has current pricing. This is not a provider uptime guarantee. |
updatedAt | ISO timestamp of the last successful catalog refresh, or null. |
stale | Whether current prices could not be obtained. Old entries can remain visible while new offers are disabled. |
data[].id, name, provider, description | Model identity and description. |
data[].object, owned_by | model and the model owner's identifier. |
data[].amount, priceUsd | Flat per-call amount as an atomic integer string and human-readable USDG string. |
data[].featured | Whether the model is a recommended starting point. |
data[].temperature | Whether the request may include temperature. |
payment.network, asset, payTo | Payment network, token contract, and recipient. payTo can be null when unavailable. |
evaluation | Jev availability, model identity, description, fixed amount, and human-readable priceUsd. |
available and stale apply to the text model catalog. evaluation.available reports whether Jev calls can currently be offered. Jev can remain available when text pricing is temporarily stale.
POST /evaluations
Accepts a Jev evaluation request. See Jev evaluations for every question type and limit.
{
"model": "typesafe-ai/jev",
"state": "The deployment failed twice after a migration.",
"questions": {
"escalate": {
"type": "boolean",
"instructions": "Should a human review this now?"
}
}
}An unsigned valid request receives a standard HTTP 402 offer for 3000 atomic units, or 0.003 USDG. A successful paid request returns HTTP 200 with object: "evaluation", Jev's typed answers, usage, and rounding metadata. There is no outer data wrapper.
POST /chat/completions
Accepts a Chat Completions request subject to the request limits:
{
"model": "google/gemini-2.5-flash-lite",
"messages": [{ "role": "user", "content": "Hello, Naven." }],
"max_tokens": 512,
"stream": false
}Without a PAYMENT-SIGNATURE, a valid available request returns HTTP 402. The complete x402 v2 offer is in the JSON body and in the base64-encoded PAYMENT-REQUIRED header. This route supports standard x402 clients that first request an offer and then repeat the request with payment.
With payment, the gateway checks the signed requirement against the current model price, verifies the authorization, generates the response, and settles the USDG amount. A successful response is HTTP 200 with a Chat Completion at the top level:
{
"id": "chatcmpl-example",
"object": "chat.completion",
"model": "google/gemini-2.5-flash-lite",
"choices": [{
"index": 0,
"message": { "role": "assistant", "content": "Hello!" },
"finish_reason": "stop"
}],
"usage": { "prompt_tokens": 8, "completion_tokens": 2, "total_tokens": 10 }
}IDs, content, usage, and additional provider fields vary. There is no outer data wrapper. finish_reason may be stop, length, or content_filter; a completed response can therefore be truncated or filtered.
The base64-encoded PAYMENT-RESPONSE header contains the x402 settlement receipt, including success, network, and transaction. Decode it with decodePaymentResponseHeader from @x402/core/http. Payment headers are exposed to browser clients through CORS.
Errors
Gateway errors have this shape:
{
"error": {
"message": "Choose a supported model from GET /ai-gateway/v1/models.",
"type": "gateway_error",
"code": "invalid_model"
}
}HTTP 402 uses the x402 offer format instead. Oversized bodies can receive a plain-text HTTP 413 response. Check the status and content type before assuming an error is JSON. See the status and recovery table for retry behavior.