Corbanu API / Production

The API for
On Chain AI Trading Agents

Get market data, inference, and an ontology for the complex world of swaps, perp and spot assets all in one place

Protocol: OpenAI + Anthropic compatible
Funding: USDC · Solana / Base / Ethereum
Billing: At cost · 0% markup

Browser checkout

Create a key—or reload the one you have.

Fund a new account or top up an existing Corbanu API key from any supported payment wallet. You approve the exact amount; Corbanu never receives your seed phrase or private key.

What are you funding?

Create a new keyFund a wallet account and issue its first key. Top up an existing keyReload a cbn_… key created in Terminal or here.

Choose payment wallet and network

Amount to add

USDC

Exact amount, up to 6 decimal places. Your wallet shows the network fee before approval; Ethereum L1 usually costs more than Base or Solana.

Connected wallet Not connected

Connect a wallet to begin.

Generate inside Terminal

Already using Corbanu Terminal?

The wallet screen owns the complete key lifecycle: top up, create, inspect, and revoke.

CORBanu Terminal

› /wallet

Choose Corbanu API

› Top up balance

Enter a positive USDC amount, unlock, and confirm

✓ Payment settled

✓ API key revealed in secure view

Open Wallet

Run /wallet, then select Corbanu API.

Add balance

Select Top up balance, enter the exact amount, unlock your local wallet, and confirm.

Save the key

The first funded account creates a key. Copy it from the secure reveal; later use Manage keys to create or revoke keys.

Your Terminal wallet seed and private key stay local. Never paste either into a website, chat, support ticket, or API request.

API reference

Request inference, research and indexes.

Corbanu exposes OpenAI-compatible Chat Completions, Anthropic-compatible Messages, account telemetry, durable Deep Research jobs, and thematic index creation. The live model catalog is authoritative for model IDs, capabilities, privacy, and pricing.

Base URL https://api.corbanu.com

01 / Access

Authentication and discovery

Send the full key in the Authorization header from trusted server-side code. Never expose it in browser JavaScript, logs, source control, or a client bundle.

Before running the examples: store the complete key in a server-side environment variable named CORBANU_API_KEY. The examples assume that variable is already present; use your shell, deployment platform, or secrets manager to set it without committing the value.

Method	Path	Authentication	Purpose
GET	`/v1/models`	Public; optional key	Live model IDs, streaming support, privacy, and at-cost rates.
POST	`/v1/chat/completions`	Bearer key	OpenAI-compatible inference.
POST	`/v1/messages`	Bearer key	Anthropic-compatible inference.
GET	`/v1/account`	Bearer key	Balance, reservations, and legacy Plan status.
POST	`/v1/deep-research`	Bearer key	Start a durable research job using Plan capacity or prepaid balance.
GET	`/v1/deep-research/:id`	Owning bearer key	Read job status, stage, progress, and usage.
GET	`/v1/deep-research/:id/result`	Owning bearer key	Retrieve completed Markdown and source metadata.

Model catalog

curl -sS https://api.corbanu.com/v1/models | jq .

Authenticated account

curl -sS https://api.corbanu.com/v1/account \
  -H "Authorization: Bearer $CORBANU_API_KEY" | jq .

Model selection: query /v1/models at runtime. Send the returned id unchanged and use the endpoint appropriate to that model.

02 / Inference

Generate with either wire format

Requests and successful responses follow the selected compatibility format. Corbanu authenticates the key, reserves the maximum possible cost, forwards the request, and settles against authoritative usage when available.

model · required

An exact model ID from /v1/models.

messages · required

The provider-compatible conversation array.

max_tokens

Maximum output budget. The catalog reports each model’s ceiling.

stream

Use true only when the catalog reports supportsStreaming: true.

OpenAI / Request

curl -sS https://api.corbanu.com/v1/chat/completions \
  -H "Authorization: Bearer $CORBANU_API_KEY" \
  -H "X-Corbanu-Request-Id: inference-001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "corbanu/glm-5.3-flash",
    "max_tokens": 1024,
    "stream": false,
    "messages": [
      {"role": "user", "content": "Explain this market move."}
    ]
  }'

OpenAI / Response shape

{
  "id": "chatcmpl_…",
  "model": "corbanu/glm-5.3-flash",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "…"},
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 120,
    "completion_tokens": 240,
    "total_tokens": 360
  }
}

Anthropic / Request

curl -sS https://api.corbanu.com/v1/messages \
  -H "Authorization: Bearer $CORBANU_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "X-Corbanu-Request-Id: messages-001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "corbanu/kimi-k3",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Write an investment memo outline."}
    ]
  }'

Streaming

curl -N https://api.corbanu.com/v1/chat/completions \
  -H "Authorization: Bearer $CORBANU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "corbanu/glm-5.3-flash",
    "max_tokens": 1024,
    "stream": true,
    "messages": [
      {"role": "user", "content": "Summarize the thesis."}
    ]
  }'

Safe retries: provide a unique X-Corbanu-Request-Id of at most 128 letters, digits, dots, colons, underscores, or hyphens. Reusing an inference request ID returns 409 instead of spending twice.

Billing headers: responses include X-Corbanu-Request-Id, X-Corbanu-Price-Version, and the initial reservation in X-Corbanu-Reserved-Microusd.

03 / Deep Research

Start once. Poll safely. Retrieve Markdown.

Deep Research is asynchronous and provider-backed. It performs web research, reports coarse progress, and returns a durable report with source metadata and an authoritative usage and cost summary.

Prepaid balance or legacy Plan

Every valid cbn_… key can use Deep Research. An active legacy Plan allowance is used first. If no Plan is active or its allowance cannot cover the request, Corbanu places a $2.00 hold on the key account’s prepaid balance and settles it to the worker’s authoritative total provider cost with no markup. Research prompts and source material leave Corbanu infrastructure; responses are marked X-Corbanu-Privacy: non-private.

question · required

The research prompt, from 1 through 50,000 characters.

title · optional

A report title, from 1 through 500 characters.

token_budget · required

A positive safe integer used for legacy Plan reservation and request identity. Prepaid jobs settle in USD from actual provider cost.

X-Corbanu-Request-Id

A stable idempotency key. Retry the same body with the same value.

1 / Start job

curl -sS https://api.corbanu.com/v1/deep-research \
  -H "Authorization: Bearer $CORBANU_API_KEY" \
  -H "X-Corbanu-Request-Id: research-market-structure-001" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How did US equity market structure change after decimalization?",
    "title": "US market structure after decimalization",
    "token_budget": 25000
  }' | jq .

202 / Accepted

{
  "id": "936d…",
  "status": "QUEUED",
  "token_budget": 25000,
  "billing": "api_balance",
  "corbanu": {
    "private": false,
    "backend": "deep-research-service"
  }
}

2 / Poll status

export CORBANU_RESEARCH_JOB_ID="936d…"

curl -sS \
  "https://api.corbanu.com/v1/deep-research/$CORBANU_RESEARCH_JOB_ID" \
  -H "Authorization: Bearer $CORBANU_API_KEY" | jq .

3 / Retrieve result

curl -sS \
  "https://api.corbanu.com/v1/deep-research/$CORBANU_RESEARCH_JOB_ID/result" \
  -H "Authorization: Bearer $CORBANU_API_KEY" | jq -r '.result.markdown'

Status response

id, status, stage, safe task progress, usage, and the non-private backend disclosure. Active jobs return 202; terminal jobs return 200.

Result response

result.markdown, title, status, source manifest, timestamps, token usage, xAPI search cost, generation cost, and total provider cost.

Billing and idempotency: a prepaid start returns X-Corbanu-Price-Version and X-Corbanu-Reserved-Microusd; the hold is released on an explicit rejection. Retrying the same body with the same request ID returns the same job. Reusing that ID with different research content or a different token budget returns 409 request_id_conflict.

04 / Index creation

Create once. Review weights. Retrieve the index.

Create a thematic basket from frozen transcripts and fundamentals using the Corbanu API. The website uses these same calls. Download OpenAPI →

Index pages support Claim with X using Task Node’s X authentication callback. API clients start the creator-authorized flow with POST /v2/indexes/{id}/claim-x; the creator completes authorization in the same browser. Public responses expose x_claim, a signed claim receipt, and generation_origin. Current model-scored indexes are labeled AI generated, including those with user-written themes. Creator identity and provenance reference →

Agents: use your existing Corbanu balance and API key

Send Authorization: Bearer $CORBANU_API_KEY to https://api.corbanu.com. The same key works for account balance, preview creation, status, results and cutoff revisions. These calls need no MetaMask connection, browser cookie, Origin header or separate DeepSeek key.

Agent quickstart (Markdown) → · OpenAPI schema → · Download Python start/resume example → · Agent discovery →

0 / Check your existing API account

curl --fail-with-body -sS https://api.corbanu.com/v1/account \
  -H "Authorization: Bearer $CORBANU_API_KEY" > account.json
jq '{walletAddress, balance: .corbanuApi}' account.json

availableMicrousd is the spendable balance after reservations; 1,000,000 microusd = $1. Read index pricing from the catalog. Preview, reweight and lock currently charge $0, so no minimum deposit or legacy Plan subscription is required. Corbanu API credit does not fund stock purchases.

Website publication and API privacy

Choose the model, prompt, reasoning, weighting and relevance cutoff. DeepSeek V4.1 Flash runs with up to 200 concurrent company requests. Completed company scores survive retries. Preview and lock currently charge $0. Website-created indexes automatically lock and publish on completion. API requests remain private when publish_on_completion is omitted or false. Explicitly set it to true to publish automatically with the accepted disclosure; poll publication.status until published. Creator wallet claiming is separate.

Change the cutoff using saved scores

The review page shows the effective minimum relevance. To change it without another model run, send POST /v2/indexes/previews/{id}/reweight with your Corbanu key, a new X-Corbanu-Request-Id, and {"preview_sha256":"<current hash>","relevance_cutoff":70}. Poll the returned status_url for a separate revised preview. Its weights use relevance scores at or above the cutoff; confidence is a separate value. The original preview stays saved.

1 / Read options and disclosure

curl --fail-with-body -sS \
  https://api.corbanu.com/v2/indexes/catalog \
  > catalog.json

2 / Define your index

# Read the disclosure before accepting it.
# These are illustrative choices; specify your own methodology and conflicts.
jq -n --slurpfile c catalog.json '{
  mandate: {
    title: "Semiconductor equipment",
    phrase: "Companies making semiconductor production equipment."
  },
  model: "corbanu/deepseek-v4.1-flash",
  prompt_id: "thematic_v1", reasoning_effort: "high",
  deterministic: false, external_funds: false,
  weighting: "market_cap", relevance_cutoff: 70,
  disclosure: {
    version: $c[0].disclosure.version,
    sha256: $c[0].disclosure_sha256,
    accepted: true, conflicts: "None"
  }
}' > index-request.json

3 / Start once

curl --fail-with-body -sS \
  https://api.corbanu.com/v2/indexes/previews \
  -H "Authorization: Bearer $CORBANU_API_KEY" \
  -H "X-Corbanu-Request-Id: semiconductor-example-001" \
  -H "Content-Type: application/json" \
  --data-binary @index-request.json > started.json

INDEX_ID=$(jq -r .id started.json)

4 / Poll progress

curl --fail-with-body -sS \
  "https://api.corbanu.com/v2/indexes/previews/$INDEX_ID" \
  -H "Authorization: Bearer $CORBANU_API_KEY" \
  > status.json

jq '{id,status,progress,preview_sha256}' status.json
# Repeat this GET while queued or running.

5 / Download index JSON

# Once status is completed:
curl --fail-with-body -sS \
  "https://api.corbanu.com/v2/indexes/previews/$INDEX_ID/result" \
  -H "Authorization: Bearer $CORBANU_API_KEY" \
  > index.json

jq '.payload.construction.weights' index.json
jq '.payload.scores[] | {ticker,score,confidence,reasoning_block}' index.json

6 / Confirm the inspected result

jq '{preview_sha256}' status.json > lock-request.json
curl --fail-with-body -sS \
  "https://api.corbanu.com/v2/indexes/$INDEX_ID/lock" \
  -H "Authorization: Bearer $CORBANU_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @lock-request.json | jq .

Signed output

payload.request, scores with confidence and explanations, exact construction.weights, exclusions, token contracts, source provenance and verification status. Weight units sum to 10¹². Locking signs and pins an encrypted copy on IPFS.

Request behavior

The same request ID and body resume the same job. A changed body returns 409. Retrieve a result before completion and the API returns 409. Deterministic external-fund requests return 503 while qualified replay is unavailable.

Method	Endpoint	Purpose
POST	`/v2/indexes/previews/{id}/reweight`	Build a new preview from all saved scores with an explicit cutoff and source hash; no new inference.
GET	`/v2/indexes`	Your saved previews and locked baskets; owner authentication required.
GET	`/v2/indexes/published`	Public index leaderboard; newest published records first.
GET	`/v2/indexes/published/{id}`	Full published artifact, weights and scoring explanations.
POST	`/v2/indexes/{id}/claim-challenge`, `/claim`	Prove the creator payout wallet using MetaMask.
POST	`/v2/indexes/{id}/publish`	Explicitly publish a locked index with the current disclosure acceptance.
POST	`/v2/indexes/{id}/felix-quotes`	One firm holding quote; provide total basket `amount_usdc_atomic`, `security_id`, `wallet`, and a `X-Felix-Session` header.
POST	`/v2/indexes/{id}/felix-orders/report`	Report a user-broadcast transaction using its `report_token` and `tx_hash`. A reporting retry does not send another purchase.

Publishing makes the supplied inputs and index public. Other investors require creator-enabled external funds and verified deterministic replay. Personal MetaMask purchases use an existing Felix wallet login, Ethereum USDC and ETH; every holding is signed separately. Contract and simulated-wallet tests pass; a live funded purchase has not been verified. Creator compensation is based on commissions or affiliate revenue; payout terms and settlement are not configured.

Create an index → · My indexes → · Browse published indexes →

04 / Operations

Balances, errors, and privacy

Read /v1/account to reconcile the wallet-owned balance before and after inference. Treat the response body’s structured error.type as the machine-readable failure reason when present.

Status	Meaning	Client action
`400`	Invalid JSON, model, endpoint, budget, or unsupported streaming.	Correct the request; do not retry unchanged.
`401`	Missing, invalid, revoked, or expired key.	Replace the credential.
`402`	Insufficient Corbanu API balance.	Top up the same key account, then send a new request ID.
`409`	Duplicate/conflicting request ID or research result not ready.	Inspect status; preserve the original request identity.
`429`	Plan quota reached and prepaid balance cannot cover the research hold.	Top up the key account or honor `Retry-After` and the Plan reset headers.
`503`	The requested model or research backend is unavailable.	Retry with backoff or choose another listed model.

API balance

corbanuApi.balanceUsd, reservedUsd, and availableUsd distinguish total funds from active reservations.

Privacy

Inspect each catalog entry’s privacy value. Deep Research is explicitly non-private and identifies its backend in every job response.

Operating notes

Know the boundary.

Wallet-owned balance

Keys created by the same wallet draw from one shared dollar balance. Revoking a key does not move the balance.

At-cost model calls

Model usage is charged against the balance with no Corbanu markup. Query /v1/models for current per-model pricing.

Keep keys server-side

Use environment variables or a secrets manager. Never ship an API key in browser JavaScript or commit it to a repository.

Deep Research billing

Deep Research works with the same cbn_… key as standard inference. Prepaid jobs use a temporary $2.00 hold and settle at the authoritative provider cost with no markup.

The API forOn Chain AI Trading Agents