API

AgentPass provides an OpenAI-compatible inference API at /api/v1. It uses the same wallet credit and admin-managed model prices as Chat. The wallet management API uses a signed-in session.

For the interface walkthrough, see API keys. The current inference API supports Models list and Chat Completions, including SSE. It does not implement the OpenAI Responses API.

Inference quickstart

1. Connect your wallet and sign in at API keys.
2. Create a key with inference permission. Copy the full key when it appears; it cannot be retrieved later.
3. Set AGENTPASS_API_KEY in your server environment and set AGENTPASS_BASE_URL to your AgentPass origin followed by /api/v1.
4. List models, choose an ID permitted by your key, and set it as AGENTPASS_MODEL. Check its prices and max_output_tokens before sending a completion.

Install the official openai package in your integrating application. The examples below run on a server. Set all three environment variables explicitly so an omitted base URL cannot route requests to a different service. The examples request 256 output tokens; lower that value if the chosen model's configured maximum is smaller.

These examples disable automatic SDK retries. Repeating an accepted inference request can incur a second charge; the endpoint does not provide an idempotency-key contract. If the catalog is empty, check enabled models and the key's model restrictions.

Authorization

Send Authorization: Bearer $AGENTPASS_API_KEY on every inference request. An app session cookie does not authorize these endpoints. API keys cannot create other keys, change models, access admin routes, or perform wallet transactions.

Keys start with sk-ap-, contain 256 random bits, and are stored as SHA-256 hashes. The database retains a masked prefix for display. A key expires after 90 days by default; choose 1 to 365 days when creating it. Revocation blocks new reservations. Already-reserved requests can finish and settle their charges.

List models

GET /api/v1/models requires models:read. It returns an OpenAI list object with data containing enabled models permitted by the key. Each entry includes id, object: "model", created, and owned_by. AgentPass adds name, max_output_tokens, and pricing with input_usd_per_million and output_usd_per_million. created is 0 because provider release dates are not tracked.

Create a chat completion

POST /api/v1/chat/completions requires chat:write, a .ai Agent ID, and enough wallet credit. Your messages are forwarded without an added AgentPass system prompt. Responses use chat.completion, choices, message, finish_reason, and standard token usage. Non-streaming responses include X-AgentPass-Cost-Usd with the billed amount.

Supported inputs:

• Text messages with system, developer, user, assistant, and tool roles. Text content parts are accepted.
• max_tokens or max_completion_tokens, up to the model limit. Omit both to use that limit. Do not send both.
• temperature, top_p, presence_penalty, frequency_penalty, stop, and seed.
• Function tools, tool_choice, parallel_tool_calls, assistant tool_calls, and tool_call_id for tool results.
• response_format using text, json_object, or a named .

Model support for tools, reasoning, structured output, and sampling controls varies. A provider rejection returns a sanitized error. n must be 1; store must be false if provided. user is accepted but not forwarded or stored. Requests accept at most 128 messages and a 256 KiB JSON body. Unknown parameters are rejected.

The workspace's thinking setting belongs to /api/chat. It is not an accepted top-level parameter for /api/v1/chat/completions; neither are reasoning or reasoning_effort in this release.

This release implements Models list and Chat Completions. Responses, embeddings, image/audio inputs and generation, files, batches, stored completions, and model retrieval by ID are not implemented. Use the SDK's chat.completions.create method. Integrations run on your server; cross-origin browser calls are not enabled.

Streaming and billing

With stream: true, the response is text/event-stream. Events contain OpenAI chat.completion.chunk objects; successful streams end with data: [DONE]. When requested, the final usage chunk has empty choices and the full token counts. AgentPass requests provider usage for billing even when the client does not ask to receive it.

Credit is reserved before contacting the provider. The wallet limit of 30 requests per minute is shared by Chat and all keys. A key may have a lower rate limit and a lifetime USD budget. Budgets include settled spending and pending reservations. They do not add credit or reset when you top up. The full output reservation must fit within both the budget and available credit.

Provider failures before output release the reservation. Interrupted streams and client disconnects settle the output already observed, then release the remainder. If final provider usage is missing, usage is estimated from input and output text. Charges remain capped at the reservation. Abandoned reservations release after five minutes. The upstream deadline is 90 seconds.

Errors before streaming use an OpenAI-style { "error": { "message", "type", "param", "code" } } object and an HTTP status. After streaming starts, failures are SSE error events without a success [DONE] marker. Every response includes X-Request-Id. A 429 response includes Retry-After: 60.

API key management

The API keys page shows masked keys, permissions, model restrictions, expiry, last inference time, spending, reservations, and the latest 50 API requests. Search matches names and prefixes; Active and Inactive filters narrow the cards. Full keys are shown once and are not saved in browser storage. Dismissing the creation dialog, navigating away, switching wallets, or signing out clears the displayed secret.

These endpoints require the wallet's session cookie and an X-AgentPass-Wallet header equal to the signed-in wallet. Mutations reject foreign origins; creation requires application/json. Inference Bearer credentials do not authorize management.

Create body:

Use null for allowedModels to allow all enabled models, including future catalog additions. Use null for budgetUsd to use the wallet balance as the spending limit. Budgets accept up to six decimals and a maximum of $10,000. A wallet can hold 20 active keys and create at most 50 keys per day. To change restrictions or rotate credentials, create a replacement and revoke the old key. Key creation and revocations are recorded in app.api_key_events; raw keys and prompts are not recorded.

Authentication

Auth uses EIP-712 and an httpOnly JWT cookie.

1. Get a nonce

Response:

The nonce expires after 5 minutes and can be used once.

2. Sign and verify

Sign the typed data with the wallet, then:

The response sets the agentpass_session cookie. The session lasts 7 days.

3. Read the session

4. Sign out

Credits

Credit, usage, topup history, and Chat requests require the signed-in session and an X-AgentPass-Wallet header matching that wallet. Login and balance reads never grant NFT credit.

Topup history

GET /api/topups returns { "topups": [...] } with the latest 50 credited payments for the wallet. Entries contain chainId, contractAddress, txHash, logIndex, paymentToken, amountPaid, amountUsd, paidAt, and creditedAt. Token amounts are integer strings and USD values are decimal strings. Timestamps use ISO 8601. This endpoint is read-only; credit is created only by the receipt-verifying indexer worker.

Get balance

Get usage

Chat

The Chat guide describes the workspace. The endpoint below returns one completed JSON response, not an SSE stream. It adds an AgentPass system prompt. The Chat and capability routes require a session cookie and X-AgentPass-Wallet matching the signed-in wallet.

Thinking capabilities

GET /api/chat/models returns a map of enabled model IDs to their supported effort levels:

These IDs illustrate the shape only. Use the actual catalog. Auto is always the default and is not included in efforts. The provider capability lookup is cached for five minutes; the authenticated route response is no-store. A failed capability lookup returns 503. Non-Auto requests are checked against the provider catalog before reservation.

Send a message

Response:

Rules:

• Requires a session.
• Requires a .ai Agent ID and enough credit for the reservation.
• Model must be enabled in the database catalog.
• thinking accepts auto, low, medium, or high; omitted means auto. Explicit effort must be supported by that model.
• The last 20 messages are sent.
• Each message is capped at 8,000 characters.
• Rate limit: 30 requests per minute per wallet, checked atomically with the reservation.
• Prices and output limits are snapshotted at reservation time. Charges are capped at the reserved amount.
• Reasoning tokens count as billable output. A successful response without valid output usage is billed using the reserved maximum output.
• Conversations are stored in the browser by the UI. This endpoint does not retrieve or persist conversation history.

Legacy airdrop

If the wallet is not in the snapshot, allocation is null.

Legacy protocol endpoints

The active dashboard uses credit, usage, and topup history endpoints. The endpoints below remain for historical claims and operator tools.

Protocol stats

Returns pass supply, holders, reward totals, recent mints, reward epochs, airdrop claims, and tax distributions.

Wallet activity

Returns passes with all wallet NFTs, pass as the latest NFT for compatibility, reward claims, airdrop claims, and the latest aggregate weight change. Holder counts use distinct owners.

Admin

The admin page uses this to gate the UI. Contract actions require their on-chain roles. Model management requires a session wallet in ADMIN_WALLETS.

Model catalog

GET /api/admin/models returns { "models": [...] }, including disabled entries.

PUT /api/admin/models creates or updates a model:

DELETE /api/admin/models accepts { "id": "openai/gpt-4o-mini" }. It removes availability, preserving historical usage and request pricing. Unknown IDs return 404. All three methods require an admin session. Mutations validate request origin and record the actor in app.model_changes.

Errors

Security

• The session cookie is httpOnly and SameSite Lax.
• Nonces are stored in Postgres and used once.
• The server never stores a private key.
• Prompts are not stored in the application database. The Chat interface saves local conversation history, and providers receive request content.
• Do not send secrets to the model.