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

# API Endpoints

> REST API routes for the ouroborai agent

## 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](/docs/agent-api/x402-payments)
* **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

<CardGroup cols={2}>
  <Card title="x402 Payment" icon="coins">
    Agent routes use the `X-PAYMENT` header with a signed USDC micropayment. See the [x402 payments guide](/docs/agent-api/x402-payments) for details.
  </Card>

  <Card title="API Key" icon="key">
    Other routes use the `Authorization: Bearer <api-key>` header. Keys are tiered: `readonly`, `readwrite`, and `admin`. Higher tiers can access lower-tier routes.
  </Card>
</CardGroup>

## Root

Public endpoints for health checks and server metadata.

<AccordionGroup>
  <Accordion title="GET /health">
    Returns server health status.

    **Authentication:** None

    **Response:**

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

  <Accordion title="GET /">
    Returns server metadata and version information.

    **Authentication:** None

    **Response:**

    ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
    {
      "name": "arbitrum-agent",
      "version": "0.1.0",
      "chain": "arbitrum-one",
      "chainId": 42161,
      "docs": "https://github.com/ouroborai-labs/arbitrum-agent"
    }
    ```
  </Accordion>
</AccordionGroup>

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

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

    **Request body:**

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

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

    If no `threadId` is provided, a new thread is created automatically.
  </Accordion>

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

    **Authentication:** x402 payment

    **Response (running):**

    ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
    {
      "id": "job_a1b2c3",
      "status": "running",
      "createdAt": 1709312400000
    }
    ```

    **Response (complete):**

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

  <Accordion title="DELETE /agent/job/:id">
    Cancel a running agent job. Only jobs in `pending` or `running` state can be cancelled.

    **Authentication:** x402 payment

    **Response:**

    ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
    { "success": true, "jobId": "job_a1b2c3" }
    ```
  </Accordion>

  <Accordion title="GET /agent/thread/:id">
    Retrieve the full conversation history for a thread.

    **Authentication:** x402 payment

    **Response:**

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

  <Accordion title="GET /agent/skills">
    List all available skills the agent can use.

    **Authentication:** x402 payment

    **Response:**

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

## Swap routes

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

<AccordionGroup>
  <Accordion title="GET /swap/quote">
    Get a swap quote from Uniswap V3 or Camelot.

    **Authentication:** `readwrite` API key

    **Query 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:**

    ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
    {
      "dex": "uniswap",
      "tokenIn": "USDC",
      "tokenOut": "WETH",
      "amountIn": "100000000",
      "amountOut": "31200000000000000",
      "priceImpactBps": 5,
      "route": ["USDC", "WETH"]
    }
    ```
  </Accordion>

  <Accordion title="POST /swap/execute">
    Execute a token swap on Arbitrum.

    **Authentication:** `readwrite` API key

    **Request body:**

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

    ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
    {
      "hash": "0xabc...",
      "success": true
    }
    ```
  </Accordion>
</AccordionGroup>

## Portfolio routes

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

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

    **Authentication:** `readonly` API key

    **Query parameters:**

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

    **Response:**

    ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
    {
      "jobs": [
        {
          "id": "job_a1b2c3",
          "status": "complete",
          "createdAt": 1709312400000
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="GET /portfolio/positions">
    Aggregated DeFi positions from Aave V3 and GMX V2.

    **Authentication:** `readonly` API key

    **Response:**

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

## Market routes

Real-time market data from external price feeds.

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

    **Response:**

    ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
    {
      "prices": {
        "ETH": { "price": 3245.67, "change24h": 2.34 },
        "ARB": { "price": 1.82, "change24h": -1.05 },
        "WBTC": { "price": 62150.00, "change24h": 0.89 }
      },
      "cached": false
    }
    ```
  </Accordion>

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

    **Response:**

    ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
    {
      "trending": [
        {
          "name": "WETH / USDC",
          "basePrice": "3245.67",
          "volume24h": "12500000",
          "change24h": "2.34"
        }
      ],
      "cached": false
    }
    ```
  </Accordion>
</AccordionGroup>

## Automations routes

Create and manage automated DeFi strategies.

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

    **Authentication:** `readwrite` API key

    **Query parameters:**

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

    **Response:**

    ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
    {
      "automations": [
        {
          "id": "auto_xyz",
          "name": "DCA ETH Weekly",
          "type": "dca",
          "status": "active",
          "walletAddress": "0x...",
          "config": { ... }
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="POST /automations">
    Create a new automation.

    **Authentication:** `readwrite` API key

    **Request body:**

    ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
    {
      "walletAddress": "0x...",
      "type": "dca",
      "name": "DCA ETH Weekly",
      "config": {
        "tokenIn": "USDC",
        "tokenOut": "WETH",
        "amount": "100",
        "interval": "weekly"
      }
    }
    ```

    **Response (201 Created):**

    ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
    {
      "automation": {
        "id": "auto_xyz",
        "name": "DCA ETH Weekly",
        "type": "dca",
        "status": "active",
        "walletAddress": "0x...",
        "config": { ... },
        "createdAt": 1709312400000
      }
    }
    ```
  </Accordion>

  <Accordion title="PATCH /automations/:id">
    Update an automation's status (pause, resume, etc.).

    **Authentication:** `readwrite` API key

    **Request body:**

    ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
    { "status": "paused" }
    ```

    Valid status values: `active`, `paused`, `completed`, `failed`
  </Accordion>

  <Accordion title="DELETE /automations/:id">
    Delete an automation.

    **Authentication:** `readwrite` API key

    **Response:**

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

## Admin routes

Operational endpoints for server administrators.

<AccordionGroup>
  <Accordion title="GET /admin/revenue">
    Revenue summary across all x402 payments.

    **Authentication:** `admin` API key

    **Response:**

    ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
    {
      "totalUsdc": "150000",
      "totalUsd": "$0.15",
      "uniquePayers": 3,
      "pricePerRequest": "$0.01",
      "requestCount": 15,
      "recentPayments": [ ... ],
      "storage": "redis"
    }
    ```
  </Accordion>

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

    **Authentication:** `admin` API key

    **Query parameters:**

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

    **Response:**

    ```json theme={"theme":{"light":"dracula","dark":"dracula"}}
    {
      "days": 30,
      "history": [
        {
          "date": "2026-03-01",
          "count": 8,
          "totalUsdc": "80000",
          "totalUsd": "$0.08"
        }
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

## Error responses

All endpoints return errors in a consistent format:

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