API Endpoints

Overview

The ouroborai API is a Hono-based REST server running on Arbitrum One. Routes are organized into groups with different authentication requirements:

Root — public, no authentication
Agent — protected by x402 micropayments
Swap, Automations, Launchpad, v1 Chat — require a readwrite API key
Portfolio, Market, NFTs, Predictions, Bridge — require a readonly API key
Admin — require an admin API key

All API key-protected routes also enforce rate limiting.

Authentication

x402 Payment

Agent routes use the X-PAYMENT header with a signed USDC micropayment. See the x402 payments guide for details.

API Key

Other routes use the Authorization: Bearer <api-key> header. Keys are tiered: readonly, readwrite, and admin. Higher tiers can access lower-tier routes.

Root

Public endpoints for health checks and server metadata.

GET /health

Returns server health status.Authentication: NoneResponse:

{ "ok": true, "ts": 1709312400000 }

GET /

Returns server metadata and version information.Authentication: NoneResponse:

{
  "name": "arbitrum-agent",
  "version": "0.1.0",
  "chain": "arbitrum-one",
  "chainId": 42161,
  "docs": "https://github.com/ouroborai-labs/arbitrum-agent"
}

Agent routes

All agent routes are protected by x402 micropayments ($0.01 USDC per request). The payer address is used as the owner ID for job and thread isolation.

POST /agent/prompt

Submit a natural-language prompt to the AI agent. Returns a job ID for async polling and a thread ID for conversation continuity.Authentication: x402 paymentRequest body:

{
  "prompt": "Swap 100 USDC for ETH on Uniswap",
  "threadId": "thread_abc123",
  "context": {}
}

Field	Type	Required	Description
`prompt`	string	Yes	Natural-language instruction (max 4000 chars)
`threadId`	string	No	Existing thread ID for multi-turn conversation
`context`	object	No	Additional context passed to the agent runner

Response (202 Accepted):

{
  "jobId": "job_a1b2c3",
  "threadId": "thread_abc123",
  "status": "pending"
}

If no threadId is provided, a new thread is created automatically.

GET /agent/job/:id

Poll for the status and result of an agent job.Authentication: x402 paymentResponse (running):

{
  "id": "job_a1b2c3",
  "status": "running",
  "createdAt": 1709312400000
}

Response (complete):

{
  "id": "job_a1b2c3",
  "status": "complete",
  "result": {
    "text": "I swapped 100 USDC for 0.0312 ETH on Uniswap V3.",
    "steps": 2,
    "toolCalls": ["arb_quote", "arb_trade"]
  },
  "createdAt": 1709312400000
}

Status values: pending, running, complete, failed, cancelled

DELETE /agent/job/:id

Cancel a running agent job. Only jobs in pending or running state can be cancelled.Authentication: x402 paymentResponse:

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

GET /agent/thread/:id

Retrieve the full conversation history for a thread.Authentication: x402 paymentResponse:

{
  "id": "thread_abc123",
  "messages": [
    {
      "role": "user",
      "content": "Swap 100 USDC for ETH",
      "timestamp": 1709312400000
    },
    {
      "role": "assistant",
      "content": "I swapped 100 USDC for 0.0312 ETH on Uniswap V3.",
      "timestamp": 1709312401500,
      "toolCalls": ["arb_quote", "arb_trade"],
      "metadata": { "jobId": "job_a1b2c3" }
    }
  ],
  "createdAt": 1709312400000
}

GET /agent/skills

List all available skills the agent can use.Authentication: x402 paymentResponse:

{
  "skills": [
    { "name": "arb-trade", "url": "https://...", "external": false },
    { "name": "gmx", "url": "https://...", "external": false },
    { "name": "aave", "url": "https://...", "external": false },
    { "name": "evm-l2s", "url": "https://...", "external": true }
  ]
}

Swap routes

Swap routes provide direct access to DEX operations without going through the AI agent.

GET /swap/quote

Get a swap quote from Uniswap V3 or Camelot.Authentication: readwrite API keyQuery parameters:

Param	Type	Required	Description
`tokenIn`	string	Yes	Input token symbol (e.g., `ETH`, `USDC`, `ARB`)
`tokenOut`	string	Yes	Output token symbol
`amountIn`	string	Yes	Amount in raw units (wei for ETH, base units for tokens)
`dex`	string	No	`uniswap` (default) or `camelot`

Response:

{
  "dex": "uniswap",
  "tokenIn": "USDC",
  "tokenOut": "WETH",
  "amountIn": "100000000",
  "amountOut": "31200000000000000",
  "priceImpactBps": 5,
  "route": ["USDC", "WETH"]
}

POST /swap/execute

Execute a token swap on Arbitrum.Authentication: readwrite API keyRequest body:

{
  "tokenIn": "USDC",
  "tokenOut": "WETH",
  "amountIn": "100000000",
  "dex": "uniswap",
  "slippageBps": 50
}

Field	Type	Required	Description
`tokenIn`	string	Yes	Input token symbol or address
`tokenOut`	string	Yes	Output token symbol or address
`amountIn`	string	Yes	Amount in raw units
`dex`	string	No	`uniswap` (default) or `camelot`
`slippageBps`	number	No	Slippage tolerance in basis points (default: 50 = 0.5%)

Response:

{
  "hash": "0xabc...",
  "success": true
}

Portfolio routes

Read-only access to job history and aggregated DeFi positions.

GET /portfolio/jobs

List recent agent jobs. Results are scoped to the caller’s API key.Authentication: readonly API keyQuery parameters:

Param	Type	Default	Description
`limit`	number	50	Max results to return (capped at 100)

Response:

{
  "jobs": [
    {
      "id": "job_a1b2c3",
      "status": "complete",
      "createdAt": 1709312400000
    }
  ]
}

GET /portfolio/positions

Aggregated DeFi positions from Aave V3 and GMX V2.Authentication: readonly API keyResponse:

{
  "aave": {
    "totalCollateralBase": "5000000000",
    "totalDebtBase": "1000000000",
    "availableBorrowsBase": "2500000000",
    "healthFactor": "2500000000000000000",
    "ltv": "5000"
  },
  "gmx": [
    {
      "market": "ETH/USDC",
      "side": "long",
      "size": "10000000000",
      "collateral": "500000000",
      "entryPrice": "3200000000",
      "pnl": "150000000"
    }
  ]
}

Market routes

Real-time market data from external price feeds.

GET /market/prices

Token prices from CoinGecko for core Arbitrum assets (ETH, USDC, ARB, WBTC, PENDLE, GRAIL, LINK). Results are cached for 30 seconds.Authentication: readonly API keyResponse:

{
  "prices": {
    "ETH": { "price": 3245.67, "change24h": 2.34 },
    "ARB": { "price": 1.82, "change24h": -1.05 },
    "WBTC": { "price": 62150.00, "change24h": 0.89 }
  },
  "cached": false
}

GET /market/trending

Trending pools on Arbitrum from GeckoTerminal. Returns the top 10 pools by activity. Results are cached for 30 seconds.Authentication: readonly API keyResponse:

{
  "trending": [
    {
      "name": "WETH / USDC",
      "basePrice": "3245.67",
      "volume24h": "12500000",
      "change24h": "2.34"
    }
  ],
  "cached": false
}

Automations routes

Create and manage automated DeFi strategies.

GET /automations

List automations for a wallet.Authentication: readwrite API keyQuery parameters:

Param	Type	Required	Description
`wallet`	string	Yes	Wallet address to filter by

Response:

{
  "automations": [
    {
      "id": "auto_xyz",
      "name": "DCA ETH Weekly",
      "type": "dca",
      "status": "active",
      "walletAddress": "0x...",
      "config": { ... }
    }
  ]
}

POST /automations

Create a new automation.Authentication: readwrite API keyRequest body:

{
  "walletAddress": "0x...",
  "type": "dca",
  "name": "DCA ETH Weekly",
  "config": {
    "tokenIn": "USDC",
    "tokenOut": "WETH",
    "amount": "100",
    "interval": "weekly"
  }
}

Response (201 Created):

{
  "automation": {
    "id": "auto_xyz",
    "name": "DCA ETH Weekly",
    "type": "dca",
    "status": "active",
    "walletAddress": "0x...",
    "config": { ... },
    "createdAt": 1709312400000
  }
}

PATCH /automations/:id

Update an automation’s status (pause, resume, etc.).Authentication: readwrite API keyRequest body:

{ "status": "paused" }

Valid status values: active, paused, completed, failed

DELETE /automations/:id

Delete an automation.Authentication: readwrite API keyResponse:

{ "ok": true }

Admin routes

Operational endpoints for server administrators.

GET /admin/revenue

Revenue summary across all x402 payments.Authentication: admin API keyResponse:

{
  "totalUsdc": "150000",
  "totalUsd": "$0.15",
  "uniquePayers": 3,
  "pricePerRequest": "$0.01",
  "requestCount": 15,
  "recentPayments": [ ... ],
  "storage": "redis"
}

GET /admin/revenue/history

Daily revenue breakdown.Authentication: admin API keyQuery parameters:

Param	Type	Default	Description
`days`	number	30	Number of days to include (max 90)

Response:

{
  "days": 30,
  "history": [
    {
      "date": "2026-03-01",
      "count": 8,
      "totalUsdc": "80000",
      "totalUsd": "$0.08"
    }
  ]
}

Error responses

All endpoints return errors in a consistent format:

{ "error": "Description of what went wrong" }

Common HTTP status codes:

Code	Meaning
`400`	Bad request — missing or invalid parameters
`401`	Unauthorized — missing or invalid API key
`402`	Payment required — x402 payment needed or invalid
`403`	Forbidden — API key tier insufficient for this route
`404`	Not found — resource does not exist or belongs to another owner
`500`	Internal server error
`503`	Service unavailable — server wallet not configured

Getting Started

Agent API

Features

Contracts

Bots

Guides

Overview

Authentication

x402 Payment

API Key

Root

Agent routes

Swap routes

Portfolio routes

Market routes

Automations routes

Admin routes

Error responses

Getting Started

Agent API

Features

Contracts

Bots

Guides

​Overview

​Authentication

x402 Payment

API Key

​Root

​Agent routes

​Swap routes

​Portfolio routes

​Market routes

​Automations routes

​Admin routes

​Error responses

Overview

Authentication

Root

Agent routes

Swap routes

Portfolio routes

Market routes

Automations routes

Admin routes

Error responses