REST API Reference

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

Authentication

Route Group	Auth Method	Description
`/` and `/health`	None	Public 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

GET / — Server info

Returns server name, version, and chain configuration. No authentication required.Response 200

{
  "name": "arbitrum-agent",
  "version": "0.1.0",
  "chain": "arbitrum-one",
  "chainId": 42161
}

GET /health — Health check

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).

POST /agent/prompt — Submit agent prompt

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

Status	Description
`400`	Missing or invalid prompt, exceeds 4000 chars
`404`	Provided threadId not found

GET /agent/job/:id — Poll job status

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.

DELETE /agent/job/:id — Cancel job

Cancel a running or pending job.Response 200

{ "success": true, "jobId": "job_abc123" }

Errors: 404 if job not found or already completed.

GET /agent/thread/:id — Retrieve thread

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
}

GET /agent/skills — List available skills

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 /swap/quote — Get swap quote

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..."]
}

POST /swap/execute — Execute swap

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.

GET /portfolio/jobs — List recent jobs

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
    }
  ]
}

GET /portfolio/positions — Aggregated positions

Returns positions across Aave V3 and GMX V2.Response 200

{
  "aave": {
    "totalCollateralBase": "1000000000",
    "totalDebtBase": "500000000",
    "healthFactor": "2000000000000000000"
  },
  "gmx": []
}

Market

Requires readonly API key.

GET /market/prices — Token prices

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
}

Returns top trending Arbitrum pools from GeckoTerminal (30-second cache).Response 200

{
  "trending": [
    {
      "name": "WETH / USDC",
      "basePrice": "3500.50",
      "volume24h": "15000000",
      "change24h": "2.5"
    }
  ],
  "cached": false
}

NFTs

Requires readonly API key.

GET /nfts/:address — List NFTs

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.

GET /predictions/top — Top markets

Returns top trending prediction markets from Polymarket.

limit

number

default:10

Number of markets to return.

GET /predictions/search — Search markets

Search prediction markets by query string.

string

required

Search query.

GET /predictions/:conditionId — Get market

Retrieve a specific prediction market by condition ID.

Bridge

Requires readonly API key.

GET /bridge/quote — Bridge quote

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.

GET /bridge/chains — Supported chains

Returns list of supported bridge chains.

Automations

Requires readwrite API key.

GET /automations — List automations

List all automations for a wallet.

wallet

string

required

Wallet address to filter by.

POST /automations — Create automation

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.

PATCH /automations/:id — Update status

Pause or resume an automation.

status

string

New status: active, paused, completed, or failed.

DELETE /automations/:id — Delete automation

Remove an automation. Returns 404 if not found.

Admin

Requires admin API key.

GET /admin/revenue — Revenue summary

Total revenue from x402 payments including unique payers and recent transactions.

GET /admin/revenue/history — Daily revenue

Daily revenue breakdown.

days

number

default:30

Number of days to return (max 90).

POST /admin/keys — Create API key

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).

GET /admin/keys — List API keys

Returns all API keys (hashed, not raw values).

DELETE /admin/keys/:id — Revoke API key

Permanently revoke an API key.

REST API

SDK

Contracts

Configuration

REST API Reference

Authentication

Root

Agent

Swap

Portfolio

Market

NFTs

Predictions

Bridge

Automations

Admin

​Authentication

​Root

​Agent

​Swap

​Portfolio

​Market

​NFTs

​Predictions

​Bridge

​Automations

​Admin

Authentication

Root

Agent

Swap

Portfolio

Market

NFTs

Predictions

Bridge

Automations

Admin