Quick Start

This guide walks you through cloning the repository, configuring credentials, starting the API server, and submitting your first agent prompt.

Prerequisites

Before you begin, make sure you have:

Bun v1.0+ — install from bun.sh if needed
Arbitrum RPC URL — a standard JSON-RPC endpoint from Alchemy, Infura, or any Arbitrum One provider
Anthropic API key — required for the Claude-backed agent runner
Funded wallet — an Arbitrum One wallet with ETH for gas and USDC for x402 payments

You can use Arbitrum Sepolia for testing. Replace the RPC URL and contract addresses accordingly.

Setup

Clone and install

Clone the monorepo and install all workspace dependencies with Bun.

git clone https://github.com/ouroborai-labs/agent.git
cd agent
bun install

This installs dependencies for all packages (sdk, adapters, timeboost, smart-account) and apps (api, web, telegram, mcp-server).

Configure environment variables

Create an .env file inside apps/api/:

cp apps/api/.env.example apps/api/.env

Open apps/api/.env and fill in the required values:

# Wallet private key (for smart account signer)
PRIVATE_KEY=0xYOUR_PRIVATE_KEY

# Anthropic API key (powers the agent runner)
ANTHROPIC_API_KEY=sk-ant-...

# Arbitrum One RPC
ARB_RPC_URL=https://arb-mainnet.g.alchemy.com/v2/YOUR_KEY

# Redis URL -- enables persistent job queue, thread store, and nonce tracking
# Falls back to in-memory stores when omitted
REDIS_URL=redis://localhost:6379

# Port for the Hono API server (default: 3000)
PORT=3000

Never commit your .env file. It contains your private key and API credentials. The repository .gitignore already excludes it.

Start the API server

Launch the development server:

bun run dev

You should see output indicating the Hono server is listening:

ouroborai API listening on http://localhost:3000

Verify the server is running

In a new terminal, hit the health endpoint:

curl http://localhost:3000/health

Expected response:

{ "status": "ok" }

Submit your first prompt

Send a natural language prompt to the agent:

curl -X POST http://localhost:3000/agent/prompt \
  -H "Content-Type: application/json" \
  -d '{"prompt": "What tokens can I trade on Uniswap?"}'

const response = await fetch("http://localhost:3000/agent/prompt", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    prompt: "What tokens can I trade on Uniswap?",
  }),
});

const data = await response.json();
console.log(data);

The response includes a jobId you can poll for the agent’s answer:

{ "jobId": "job_abc123", "threadId": "thread_xyz789" }

Check the result:

curl http://localhost:3000/agent/job/job_abc123

Continue the conversation

Pass the threadId from the previous response to maintain context across turns:

curl -X POST http://localhost:3000/agent/prompt \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Swap 50 USDC for ARB",
    "threadId": "thread_xyz789"
  }'

The agent remembers the prior conversation and executes against the same session state.

Optional: Start the Web Terminal

The web UI provides a chat-based terminal interface with session management, activity feeds, and position tracking.

cd apps/web
bun run dev

Open http://localhost:3001 in your browser.

Optional: Start the Telegram Bot

cd apps/telegram
TELEGRAM_BOT_TOKEN=your_bot_token bun run dev

Send /trade 50 USDC for ARB to your bot to test.

What’s Next

Architecture

Understand how requests flow from prompt to on-chain execution.

x402 Payments

Learn how the micropayment protocol works for production use.

Trading

Explore spot trading capabilities on Uniswap V3.

Add a Skill

Extend the agent with your own protocol integration.

Getting Started

Agent API

Features

Contracts

Bots

Guides

Prerequisites

Setup

Optional: Start the Web Terminal

Optional: Start the Telegram Bot

What’s Next

Architecture

x402 Payments

Trading

Add a Skill

​Prerequisites

​Setup

​Optional: Start the Web Terminal

​Optional: Start the Telegram Bot

​What’s Next

Architecture

x402 Payments

Trading

Add a Skill

Prerequisites

Setup

Optional: Start the Web Terminal

Optional: Start the Telegram Bot

What’s Next