API Endpoints

Base URL: https://agent-router.gaib.cloud (staging) | http://localhost:8080 (local)

All endpoints are under /v1/ except /health.

At a glance

Endpoint	Method	Auth	Description
/health	GET	--	Health check
/v1/models	GET	--	List models with pricing
/v1/topup	POST	x402	Fund balance with USDC
/v1/auth/keys	POST	SIWE	Create API key
/v1/auth/keys	GET	SIWE	List API keys
/v1/auth/keys/:id	DELETE	SIWE	Revoke API key
/v1/chat/completions	POST	API key	Inference (OpenAI-compatible)
/v1/usage/:wallet	GET	API key / SIWE	Balance & usage stats

---

Health

GET /health

Request

curl https://agent-router.gaib.cloud/health

Response 200

{ "status": "ok" }

---

List Models

GET /v1/models

No auth required. Returns all available models with pricing.

Request

curl https://agent-router.gaib.cloud/v1/models

Response 200

{
  "object": "list",
  "data": [
    {
      "id": "gemini/gemini-2.5-flash",
      "name": "gemini-2.5-flash",
      "provider": "gemini",
      "contextLength": 1048576,
      "promptPricePer1MTokens": 0.15,
      "completionPricePer1M": 0.60
    }
  ]
}

Prices are USD per 1M tokens (downstream cost before 20% markup).

---

Top Up

POST /v1/topup

Fund wallet balance via x402 USDC payment. Two-step flow:

Step 1: Get payment requirements

Request

curl -X POST https://agent-router.gaib.cloud/v1/topup \
  -H "Content-Type: application/json" \
  -d '{"amount": 5}'

Response 402

{
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "maxAmountRequired": "5000000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x...",
    "extra": { "name": "USDC", "version": "1", "decimals": 6 }
  }]
}

Step 2: Send with payment signature

Request

curl -X POST https://agent-router.gaib.cloud/v1/topup \
  -H "Content-Type: application/json" \
  -H "X-Payment: <base64-encoded-signature>" \
  -d '{"amount": 5}'

Response 200

{
  "balance_usdc": 5000000,
  "credited_usdc": 5000000
}

Field	Type	Description
amount	number	USD amount, minimum $1

---

Create API Key

POST /v1/auth/keys

Requires SIWE authentication in the request body.

Request

curl -X POST https://agent-router.gaib.cloud/v1/auth/keys \
  -H "Content-Type: application/json" \
  -d '{
    "message": "<siwe-message>",
    "signature": "0x...",
    "label": "my-app"
  }'

Response 201

{
  "id": 1,
  "key": "sk-a3f9e2b1c4d5...",
  "label": "my-app",
  "created_at": "2026-04-07T12:00:00.000Z"
}

WARNING

The key field is returned only once. Store it immediately.

Field	Type	Required	Description
message	string	yes	Prepared SIWE message
signature	string	yes	Hex-encoded wallet signature
label	string	no	Human-readable label

---

List API Keys

GET /v1/auth/keys

Pass SIWE auth as query parameters.

Request

curl "https://agent-router.gaib.cloud/v1/auth/keys?message=<siwe>&signature=<sig>"

Response 200

{
  "data": [
    {
      "id": 1,
      "label": "my-app",
      "created_at": "2026-04-07T12:00:00.000Z",
      "revoked_at": null
    }
  ]
}

---

Revoke API Key

DELETE /v1/auth/keys/:key_id

Requires SIWE authentication in the request body.

Request

curl -X DELETE https://agent-router.gaib.cloud/v1/auth/keys/1 \
  -H "Content-Type: application/json" \
  -d '{"message": "<siwe>", "signature": "0x..."}'

Response 200

{ "revoked": true }

---

Chat Completions

POST /v1/chat/completions

OpenAI-compatible. Requires Authorization: Bearer <api-key>.

curl

curl -X POST https://agent-router.gaib.cloud/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini/gemini-2.5-flash",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ],
    "max_tokens": 512
  }'

TypeScript

import OpenAI from 'openai'

const client = new OpenAI({
  baseURL: 'https://agent-router.gaib.cloud/v1',
  apiKey: 'sk-your-key',
})

const res = await client.chat.completions.create({
  model: 'gemini/gemini-2.5-flash',
  messages: [{ role: 'user', content: 'Hello!' }],
  max_tokens: 512,
})

Response 200

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "Hello! How can I help?" },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 9,
    "total_tokens": 29
  }
}

Request body

Field	Type	Required	Default	Description
model	string	yes	--	Model ID (e.g. gemini/gemini-2.5-flash)
messages	array	yes	--	Array of {role, content} objects
max_tokens	number	no	1024	Max completion tokens
temperature	number	no	--	Sampling temperature
top_p	number	no	--	Nucleus sampling
stream	boolean	no	false	Enable SSE streaming

Not supported

Requests with thinking or reasoning_effort parameters return HTTP 400. Strip these fields before calling the gateway.

Streaming

Set "stream": true. Response is standard OpenAI SSE:

data: {"id":"chatcmpl-...","choices":[{"delta":{"content":"Hello"}}]}

data: {"id":"chatcmpl-...","choices":[{"delta":{"content":"!"}}]}

data: [DONE]

---

Usage

GET /v1/usage/:wallet

Get wallet balance and per-key usage breakdown. Accepts API key or SIWE auth.

API key auth

curl https://agent-router.gaib.cloud/v1/usage/0xYourWallet \
  -H "Authorization: Bearer sk-your-key"

SIWE auth

curl "https://agent-router.gaib.cloud/v1/usage/0xYourWallet?message=<siwe>&signature=<sig>"

Response 200

{
  "wallet": "0xabc...",
  "balance_usdc": 4950000,
  "locked_usdc": 0,
  "available_usdc": 4950000,
  "keys": [
    {
      "api_key_id": 1,
      "label": "my-app",
      "request_count": 3,
      "total_prompt_tokens": 66,
      "total_completion_tokens": 174,
      "total_charged_usdc": 50000,
      "total_platform_revenue_usd": 0.008
    }
  ]
}

Field	Unit	Conversion
balance_usdc	micro-USDC	/ 1_000_000 = USD
available_usdc	micro-USDC	balance_usdc - locked_usdc
total_charged_usdc	micro-USDC	/ 1_000_000 = USD