> ## Documentation Index
> Fetch the complete documentation index at: https://ouroborai.xyz/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API Reference

> Complete API endpoint 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

<Accordion title="GET / — Server info">
  Returns server name, version, and chain configuration. No authentication
  required.

  **Response `200`**

  ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
  {
    "name": "arbitrum-agent",
    "version": "0.1.0",
    "chain": "arbitrum-one",
    "chainId": 42161
  }
  ```
</Accordion>

<Accordion title="GET /health — Health check">
  Returns server health status with a timestamp. No authentication required.

  **Response `200`**

  ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
  { "ok": true, "ts": 1709337600000 }
  ```
</Accordion>

***

## Agent

All `/agent/*` routes require x402 payment (or `SKIP_PAYMENT=true` in dev).

<Accordion title="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.

  <ParamField body="prompt" type="string" required>
    Natural language instruction (max 4000 characters).
  </ParamField>

  <ParamField body="threadId" type="string">
    Existing thread ID for multi-turn conversations. Omit to create a new thread.
  </ParamField>

  <ParamField body="context" type="object">
    Additional context object passed to the agent runner.
  </ParamField>

  **Response `202`**

  ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
  {
    "jobId": "job_abc123",
    "threadId": "thread_xyz789",
    "status": "pending"
  }
  ```

  **Errors**

  | Status | Description                                   |
  | ------ | --------------------------------------------- |
  | `400`  | Missing or invalid prompt, exceeds 4000 chars |
  | `404`  | Provided threadId not found                   |
</Accordion>

<Accordion title="GET /agent/job/:id — Poll job status">
  Retrieve the current status and result of an agent job.

  **Response `200`**

  ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
  {
    "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.
</Accordion>

<Accordion title="DELETE /agent/job/:id — Cancel job">
  Cancel a running or pending job.

  **Response `200`**

  ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
  { "success": true, "jobId": "job_abc123" }
  ```

  **Errors**: `404` if job not found or already completed.
</Accordion>

<Accordion title="GET /agent/thread/:id — Retrieve thread">
  Retrieve a conversation thread with all messages.

  **Response `200`**

  ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
  {
    "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
  }
  ```
</Accordion>

<Accordion title="GET /agent/skills — List available skills">
  Returns all registered built-in and external skills.

  **Response `200`**

  ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
  {
    "skills": [
      { "name": "arb-trade", "url": "https://...", "external": false },
      { "name": "evm-l2s", "url": "https://ethskills.com/...", "external": true }
    ]
  }
  ```
</Accordion>

***

## Swap

Requires `readwrite` API key.

<Accordion title="GET /swap/quote — Get swap quote">
  Get a price quote without executing the trade.

  <ParamField query="tokenIn" type="string" required>
    Input token symbol (ETH, USDC, ARB, WBTC) or address.
  </ParamField>

  <ParamField query="tokenOut" type="string" required>
    Output token symbol or address.
  </ParamField>

  <ParamField query="amountIn" type="string" required>
    Amount in smallest unit (wei for ETH, 6 decimals for USDC).
  </ParamField>

  <ParamField query="dex" type="string" default="uniswap">
    DEX to quote from: `uniswap` or `camelot`.
  </ParamField>

  **Response `200`**

  ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
  {
    "dex": "uniswap",
    "tokenIn": "USDC",
    "tokenOut": "ETH",
    "amountIn": "100000000",
    "amountOut": "50000000000000000",
    "priceImpactBps": 5,
    "route": ["0xaf88...", "0x82aF..."]
  }
  ```
</Accordion>

<Accordion title="POST /swap/execute — Execute swap">
  Execute a token swap on-chain.

  <ParamField body="tokenIn" type="string" required>
    Input token symbol or address.
  </ParamField>

  <ParamField body="tokenOut" type="string" required>
    Output token symbol or address.
  </ParamField>

  <ParamField body="amountIn" type="string" required>
    Amount in smallest unit.
  </ParamField>

  <ParamField body="dex" type="string" default="uniswap">
    DEX: `uniswap` or `camelot`.
  </ParamField>

  <ParamField body="slippageBps" type="number" default={50}>
    Maximum slippage in basis points (50 = 0.5%).
  </ParamField>

  **Response `200`**: Returns transaction result with hash and amounts.

  **Errors**: `400` for missing fields, `503` if server wallet not configured.
</Accordion>

***

## Portfolio

Requires `readonly` API key.

<Accordion title="GET /portfolio/jobs — List recent jobs">
  Returns recent agent jobs scoped to the caller's API key.

  <ParamField query="limit" type="number" default={50}>
    Maximum results (max 100).
  </ParamField>

  **Response `200`**

  ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
  {
    "jobs": [
      {
        "id": "job_abc123",
        "status": "complete",
        "prompt": "...",
        "createdAt": 1709337600000,
        "updatedAt": 1709337601000
      }
    ]
  }
  ```
</Accordion>

<Accordion title="GET /portfolio/positions — Aggregated positions">
  Returns positions across Aave V3 and GMX V2.

  **Response `200`**

  ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
  {
    "aave": {
      "totalCollateralBase": "1000000000",
      "totalDebtBase": "500000000",
      "healthFactor": "2000000000000000000"
    },
    "gmx": []
  }
  ```
</Accordion>

***

## Market

Requires `readonly` API key.

<Accordion title="GET /market/prices — Token prices">
  Returns current prices for supported tokens (30-second cache). Data sourced
  from CoinGecko.

  **Response `200`**

  ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
  {
    "prices": {
      "ETH": { "price": 3500.50, "change24h": 2.5 },
      "USDC": { "price": 1.0, "change24h": 0.01 },
      "ARB": { "price": 1.85, "change24h": -1.2 }
    },
    "cached": false
  }
  ```
</Accordion>

<Accordion title="GET /market/trending — Trending pools">
  Returns top trending Arbitrum pools from GeckoTerminal (30-second cache).

  **Response `200`**

  ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
  {
    "trending": [
      {
        "name": "WETH / USDC",
        "basePrice": "3500.50",
        "volume24h": "15000000",
        "change24h": "2.5"
      }
    ],
    "cached": false
  }
  ```
</Accordion>

***

## NFTs

Requires `readonly` API key.

<Accordion title="GET /nfts/:address — List NFTs">
  Returns NFTs owned by an address on Arbitrum (via Alchemy).

  <ParamField query="includeHidden" type="boolean" default="false">
    Include spam/hidden NFTs.
  </ParamField>

  **Response `200`**

  ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
  {
    "nfts": [
      {
        "contractAddress": "0x...",
        "tokenId": "42",
        "name": "My NFT #42",
        "collection": "Collection Name",
        "imageUrl": "https://...",
        "isSpam": false
      }
    ]
  }
  ```
</Accordion>

***

## Predictions

Requires `readonly` API key.

<Accordion title="GET /predictions/top — Top markets">
  Returns top trending prediction markets from Polymarket.

  <ParamField query="limit" type="number" default={10}>
    Number of markets to return.
  </ParamField>
</Accordion>

<Accordion title="GET /predictions/search — Search markets">
  Search prediction markets by query string.

  <ParamField query="q" type="string" required>
    Search query.
  </ParamField>
</Accordion>

<Accordion title="GET /predictions/:conditionId — Get market">
  Retrieve a specific prediction market by condition ID.
</Accordion>

***

## Bridge

Requires `readonly` API key.

<Accordion title="GET /bridge/quote — Bridge quote">
  Get a cross-chain bridge quote.

  <ParamField query="fromChainId" type="number" default={42161}>
    Source chain ID.
  </ParamField>

  <ParamField query="toChainId" type="number" required>
    Destination chain ID.
  </ParamField>

  <ParamField query="fromToken" type="string" required>
    Source token address.
  </ParamField>

  <ParamField query="toToken" type="string" required>
    Destination token address.
  </ParamField>

  <ParamField query="amount" type="string" required>
    Amount in smallest unit.
  </ParamField>

  <ParamField query="userAddress" type="string" required>
    User's wallet address.
  </ParamField>
</Accordion>

<Accordion title="GET /bridge/chains — Supported chains">
  Returns list of supported bridge chains.
</Accordion>

***

## Automations

Requires `readwrite` API key.

<Accordion title="GET /automations — List automations">
  List all automations for a wallet.

  <ParamField query="wallet" type="string" required>
    Wallet address to filter by.
  </ParamField>
</Accordion>

<Accordion title="POST /automations — Create automation">
  <ParamField body="walletAddress" type="string" required>
    Wallet address.
  </ParamField>

  <ParamField body="type" type="string" required>
    Automation type.
  </ParamField>

  <ParamField body="name" type="string" required>
    Display name.
  </ParamField>

  <ParamField body="config" type="object" required>
    Automation configuration.
  </ParamField>

  **Response `201`**: Returns the created automation.
</Accordion>

<Accordion title="PATCH /automations/:id — Update status">
  Pause or resume an automation.

  <ParamField body="status" type="string">
    New status: `active`, `paused`, `completed`, or `failed`.
  </ParamField>
</Accordion>

<Accordion title="DELETE /automations/:id — Delete automation">
  Remove an automation. Returns `404` if not found.
</Accordion>

***

## Admin

Requires `admin` API key.

<Accordion title="GET /admin/revenue — Revenue summary">
  Total revenue from x402 payments including unique payers and recent
  transactions.
</Accordion>

<Accordion title="GET /admin/revenue/history — Daily revenue">
  Daily revenue breakdown.

  <ParamField query="days" type="number" default={30}>
    Number of days to return (max 90).
  </ParamField>
</Accordion>

<Accordion title="POST /admin/keys — Create API key">
  <ParamField body="tier" type="string" required>
    Key tier: `readonly`, `readwrite`, or `admin`.
  </ParamField>

  <ParamField body="label" type="string" required>
    Descriptive label (max 64 characters).
  </ParamField>

  **Response `201`**: Returns the key entry with the raw API key (shown once).
</Accordion>

<Accordion title="GET /admin/keys — List API keys">
  Returns all API keys (hashed, not raw values).
</Accordion>

<Accordion title="DELETE /admin/keys/:id — Revoke API key">
  Permanently revoke an API key.
</Accordion>