Skip to main content
The ouroborai API is a Hono-based REST server running on Bun. Endpoints are organized by route group with different authentication requirements.

​
Authentication

Route GroupAuth MethodDescription
/ and /healthNonePublic endpoints
/agent/*x402 payment header$0.01 USDC per request
/portfolio/*, /market/*, /nfts/*, /predictions/*, /bridge/*API key (readonly)Rate limited
/swap/*, /automations/*, /launchpad/*, /v1/*API key (readwrite)Rate limited
/admin/*API key (admin)Rate limited

​
Root

Returns server name, version, and chain configuration. No authentication required.Response 200
{
  "name": "arbitrum-agent",
  "version": "0.1.0",
  "chain": "arbitrum-one",
  "chainId": 42161
}
Returns server health status with a timestamp. No authentication required.Response 200
{ "ok": true, "ts": 1709337600000 }

​
Agent

All /agent/* routes require x402 payment (or SKIP_PAYMENT=true in dev).
Submit a natural language prompt for the AI agent to process. Returns a job ID and thread ID for polling.
​
prompt
string
required
Natural language instruction (max 4000 characters).
​
threadId
string
Existing thread ID for multi-turn conversations. Omit to create a new thread.
​
context
object
Additional context object passed to the agent runner.
Response 202
{
  "jobId": "job_abc123",
  "threadId": "thread_xyz789",
  "status": "pending"
}
Errors
StatusDescription
400Missing or invalid prompt, exceeds 4000 chars
404Provided threadId not found
Retrieve the current status and result of an agent job.Response 200
{
  "id": "job_abc123",
  "status": "complete",
  "prompt": "What is my ETH balance?",
  "createdAt": 1709337600000,
  "updatedAt": 1709337601000,
  "result": {
    "text": "Your ETH balance is 1.5 ETH.",
    "steps": 2,
    "toolCalls": ["arb_portfolio"]
  }
}
Status values: pending, running, complete, failed, cancelled.Errors: 404 if job not found.
Cancel a running or pending job.Response 200
{ "success": true, "jobId": "job_abc123" }
Errors: 404 if job not found or already completed.
Retrieve a conversation thread with all messages.Response 200
{
  "id": "thread_xyz789",
  "messages": [
    {
      "id": "msg_001",
      "role": "user",
      "content": "Swap 50 USDC for ARB",
      "createdAt": 1709337600000
    },
    {
      "id": "msg_002",
      "role": "assistant",
      "content": "I've submitted a swap order...",
      "createdAt": 1709337601000,
      "toolCalls": ["arb_trade"]
    }
  ],
  "createdAt": 1709337600000,
  "updatedAt": 1709337601000
}
Returns all registered built-in and external skills.Response 200
{
  "skills": [
    { "name": "arb-trade", "url": "https://...", "external": false },
    { "name": "evm-l2s", "url": "https://ethskills.com/...", "external": true }
  ]
}

​
Swap

Requires readwrite API key.
Get a price quote without executing the trade.
​
tokenIn
string
required
Input token symbol (ETH, USDC, ARB, WBTC) or address.
​
tokenOut
string
required
Output token symbol or address.
​
amountIn
string
required
Amount in smallest unit (wei for ETH, 6 decimals for USDC).
​
dex
string
default:"uniswap"
DEX to quote from: uniswap or camelot.
Response 200
{
  "dex": "uniswap",
  "tokenIn": "USDC",
  "tokenOut": "ETH",
  "amountIn": "100000000",
  "amountOut": "50000000000000000",
  "priceImpactBps": 5,
  "route": ["0xaf88...", "0x82aF..."]
}
Execute a token swap on-chain.
​
tokenIn
string
required
Input token symbol or address.
​
tokenOut
string
required
Output token symbol or address.
​
amountIn
string
required
Amount in smallest unit.
​
dex
string
default:"uniswap"
DEX: uniswap or camelot.
​
slippageBps
number
default:50
Maximum slippage in basis points (50 = 0.5%).
Response 200: Returns transaction result with hash and amounts.Errors: 400 for missing fields, 503 if server wallet not configured.

​
Portfolio

Requires readonly API key.
Returns recent agent jobs scoped to the caller’s API key.
​
limit
number
default:50
Maximum results (max 100).
Response 200
{
  "jobs": [
    {
      "id": "job_abc123",
      "status": "complete",
      "prompt": "...",
      "createdAt": 1709337600000,
      "updatedAt": 1709337601000
    }
  ]
}
Returns positions across Aave V3 and GMX V2.Response 200
{
  "aave": {
    "totalCollateralBase": "1000000000",
    "totalDebtBase": "500000000",
    "healthFactor": "2000000000000000000"
  },
  "gmx": []
}

​
Market

Requires readonly API key.
Returns current prices for supported tokens (30-second cache). Data sourced from CoinGecko.Response 200
{
  "prices": {
    "ETH": { "price": 3500.50, "change24h": 2.5 },
    "USDC": { "price": 1.0, "change24h": 0.01 },
    "ARB": { "price": 1.85, "change24h": -1.2 }
  },
  "cached": false
}

​
NFTs

Requires readonly API key.
Returns NFTs owned by an address on Arbitrum (via Alchemy).
​
includeHidden
boolean
default:"false"
Include spam/hidden NFTs.
Response 200
{
  "nfts": [
    {
      "contractAddress": "0x...",
      "tokenId": "42",
      "name": "My NFT #42",
      "collection": "Collection Name",
      "imageUrl": "https://...",
      "isSpam": false
    }
  ]
}

​
Predictions

Requires readonly API key.
Returns top trending prediction markets from Polymarket.
​
limit
number
default:10
Number of markets to return.
Search prediction markets by query string.
​
q
string
required
Search query.
Retrieve a specific prediction market by condition ID.

​
Bridge

Requires readonly API key.
Get a cross-chain bridge quote.
​
fromChainId
number
default:42161
Source chain ID.
​
toChainId
number
required
Destination chain ID.
​
fromToken
string
required
Source token address.
​
toToken
string
required
Destination token address.
​
amount
string
required
Amount in smallest unit.
​
userAddress
string
required
User’s wallet address.
Returns list of supported bridge chains.

​
Automations

Requires readwrite API key.
List all automations for a wallet.
​
wallet
string
required
Wallet address to filter by.
​
walletAddress
string
required
Wallet address.
​
type
string
required
Automation type.
​
name
string
required
Display name.
​
config
object
required
Automation configuration.
Response 201: Returns the created automation.
Pause or resume an automation.
​
status
string
New status: active, paused, completed, or failed.
Remove an automation. Returns 404 if not found.

​
Admin

Requires admin API key.
Total revenue from x402 payments including unique payers and recent transactions.
Daily revenue breakdown.
​
days
number
default:30
Number of days to return (max 90).
​
tier
string
required
Key tier: readonly, readwrite, or admin.
​
label
string
required
Descriptive label (max 64 characters).
Response 201: Returns the key entry with the raw API key (shown once).
Returns all API keys (hashed, not raw values).
Permanently revoke an API key.