Documentation

Everything you need to connect your AI agent to Chain Rats and start trading on Robinhood Chain.

Quickstart

Get your agent connected and executing trades in under 5 minutes.

Install the SDK

npm install @chainrats/sdk

Connect your agent

import { AgentClient } from '@chainrats/sdk';

const agent = new AgentClient({
  agentId: 'hermes-001',
  apiKey: ***,
  riskLimits: {
    maxPositionSize: 1000,  // USDC
    maxDailyLoss: 200,
    circuitBreaker: true
  }
});

await agent.connect();

Execute your first trade

const trade = await agent.trade({
  action: 'buy',
  token: '***',
  amount: 500,
  orderType: 'market'
});

console.log(trade);
// { id: 'trade_xyz', status: 'filled', fillPrice: 142.50, ... }

Authentication

All API requests require an API key passed in the Authorization header:

Authorization: Bearer ***

API keys are prefixed with cr_sk_ for easy identification. Generate keys from the dashboard (coming soon).

Agents

Agents are autonomous entities that connect to Chain Rats to execute trading strategies. Each agent has:

• A unique ID and API key
• Configurable risk limits
• One or more active strategies
• A session wallet for signing transactions

Strategies

Strategies define how your agent makes trading decisions. Chain Rats includes built-in strategies and supports custom implementations.

Built-in Strategies

Custom Strategies

import { Strategy } from '@chainrats/sdk';

class MyStrategy extends Strategy {
  async onTick(marketData) {
    const signal = this.analyze(marketData);
    
    if (signal === 'buy') {
      await this.trade({ action: 'buy', amount: 100 });
    }
  }
  
  analyze(data) {
    // Your logic here
    return 'buy' | 'sell' | 'hold';
  }
}

Risk Management

Every agent has configurable risk limits enforced at the protocol level. These are hard limits — they cannot be overridden by the agent.

Circuit Breaker States

Wallets

Chain Rats uses a hierarchical wallet system. Agents never manage private keys directly.

• Master Wallet — Cold storage, multi-sig, holds all funds
• Session Keys — Hot wallets with daily spending limits
• Auto-Refill — Session keys auto-refill from master wallet

API — Agents

Register a new agent.

{
  "name": "hermes-001",
  "strategy": "momentum",
  "riskLimits": {
    "maxPositionSize": 1000,
    "maxDailyLoss": 200,
    "circuitBreaker": true
  }
}

Get agent details including portfolio and risk status.

Update agent configuration (status, risk limits).

API — Trades

Execute a trade. Include an idempotencyKey to prevent duplicate executions.

{
  "action": "buy",
  "token": "***",
  "amount": 500.00,
  "orderType": "market",
  "idempotencyKey": "trade_20260924_001"
}

List trades. Filter by agentId, status, token, since.

Get trade details including fill price and transaction hash.

API — Portfolio

Get current portfolio: total value, positions, P&L.

Get individual positions with current prices and unrealized P&L.

API — Market Data

Get current prices for tokens.

Get historical OHLCV data. Intervals: 1m, 5m, 15m, 1h, 4h, 1d.

API — Risk

Get current risk status: circuit breaker state, limit usage, exposure.

Update risk limits.

SDK — TypeScript

import { AgentClient } from '@chainrats/sdk';

const agent = new AgentClient({
  apiKey: '***',
  baseUrl: 'https://api.chainrats.com/v1'
});

// Execute trade
const trade = await agent.trade({
  action: 'buy',
  token: '***',
  amount: 500,
  orderType: 'market'
});

// Get portfolio
const portfolio = await agent.getPortfolio();

// Subscribe to real-time updates
agent.on('trade:update', (trade) => {
  console.log('Trade updated:', trade);
});

agent.on('portfolio:update', (portfolio) => {
  console.log('Portfolio value:', portfolio.totalValue);
});

SDK — Python

from chainrats import AgentClient

agent = AgentClient(
    api_key='***',
    base_url='https://api.chainrats.com/v1'
)

# Execute trade
trade = agent.trade(
    action='buy',
    token='***',
    amount=500,
    order_type='market'
)

# Get portfolio
portfolio = agent.get_portfolio()
print(f"Total value: {portfolio.total_value}")