# MCP Hub API
Source: https://docs.aiusd.ai/api

Direct API access for custom agents

## What is MCP Hub

HTTP server implementing Model Context Protocol (MCP) that provides AI agents with access to trading services through standardized tool calls.

**Protocol:** JSON-RPC 2.0 over HTTP

**Endpoints:**

* Production: `https://mcp.alpha.dev/api/mcp-hub/mcp`
* Development: `https://dev.alpha.dev/api/mcp-hub/mcp`

<Note>
  Authentication required. Contact support for API access.
</Note>

## Quick Start

### List Available Tools

```bash theme={null}
curl -X POST https://mcp.alpha.dev/api/mcp-hub/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'
```

### Call a Tool

```bash theme={null}
curl -X POST https://mcp.alpha.dev/api/mcp-hub/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "genalpha_solchef_get_tokens_market_cap",
      "arguments": {
        "limit": 10
      }
    }
  }'
```

## Tool Naming Convention

All tools follow the pattern: `genalpha_{service}_{action}`

**Examples:**

* `genalpha_tim_execute_intent` - Execute trading intent
* `genalpha_aiusd_get_portfolio` - Get portfolio balance
* `genalpha_solchef_get_tokens_market_cap` - Get token market caps

## Available Services

<CardGroup>
  <Card title="TIM" icon="bolt">
    Trading Intent Model

    Prefix: `genalpha_tim_*`
  </Card>

  <Card title="AIUSD" icon="coins">
    Trading & Portfolio

    Prefix: `genalpha_aiusd_*`
  </Card>

  <Card title="Solchef" icon="chart-line">
    Market Data

    Prefix: `genalpha_solchef_*`
  </Card>
</CardGroup>

## Integration Examples

### With Claude Desktop

Add to `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "aiusd": {
      "url": "https://mcp.alpha.dev/api/mcp-hub/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}
```

### With Anthropic SDK

```typescript theme={null}
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const response = await client.messages.create({
  model: "claude-3-5-sonnet-20241022",
  max_tokens: 4096,
  tools: [{
    type: "custom",
    name: "mcp",
    mcp_server: {
      url: "https://mcp.alpha.dev/api/mcp-hub/mcp",
      transport: "http",
      headers: {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }],
  messages: [{
    role: "user",
    content: "What are the top 10 tokens by market cap?"
  }]
});
```

### With MCP Inspector

Test your integration interactively:

```bash theme={null}
npm install -g @modelcontextprotocol/inspector
npx @modelcontextprotocol/inspector
```

**Configuration:**

* Transport: HTTP
* URL: `https://mcp.alpha.dev/api/mcp-hub/mcp`
* Auth: Bearer token required

## Response Format

All tool calls return JSON-RPC 2.0 responses:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{...tool response data...}"
      }
    ],
    "isError": false
  }
}
```

## Error Handling

Errors follow JSON-RPC 2.0 error format:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32600,
    "message": "Invalid request",
    "data": {
      "details": "Missing required parameter"
    }
  }
}
```

## Authentication

MCP Hub supports Bearer token authentication:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://mcp.alpha.dev/api/mcp-hub/mcp
```

Contact support for API access credentials.

## Running Locally

For local development and testing:

### Prerequisites

* Rust toolchain
* `just` command runner (optional)

### Start the Server

```bash theme={null}
git clone https://github.com/galpha-ai/mcp-hub
cd mcp-hub

# Run with local config
just run-local

# Or with cargo
cargo run -- --config config/mcp-hub.local.yaml
```

Local server runs on `http://127.0.0.1:3000/mcp`

<Note>
  Local development uses passthrough authentication. Production requires valid Bearer tokens.
</Note>

## Tool Reference

### TIM Tools

**genalpha\_tim\_execute\_intent** - Execute trading intent

Supports:

* Immediate swaps
* Prediction markets (Polymarket)
* Perpetual futures (HyperLiquid)
* Spot orders (HyperLiquid)
* Conditional orders

### AIUSD Tools

**genalpha\_aiusd\_get\_portfolio** - Get account balance

**genalpha\_aiusd\_get\_transactions** - Get transaction history

### Solchef Tools

**genalpha\_solchef\_get\_tokens\_market\_cap** - Get top tokens by market cap

Parameters:

* `limit` (number): Number of tokens to return

<Card title="Full API Reference" icon="book" href="/api">
  Complete tool catalog with parameters
</Card>

## Best Practices

<AccordionGroup>
  <Accordion title="Use Structured Logging">
    Enable debug logging to see tool calls:

    ```bash theme={null}
    RUST_LOG=debug cargo run
    ```
  </Accordion>

  <Accordion title="Handle Errors Gracefully">
    Always check `isError` field in responses and handle error cases.
  </Accordion>

  <Accordion title="Test with Inspector">
    Use MCP Inspector to test tool calls before integrating into your application.
  </Accordion>

  <Accordion title="Secure Your Tokens">
    Never commit Bearer tokens to version control. Use environment variables.
  </Accordion>
</AccordionGroup>


# Architecture
Source: https://docs.aiusd.ai/architecture

How AIUSD works across human interfaces, AI agents, custody, and trading execution.

## Overview

AIUSD is a trading platform built for both human users and AI agents. Humans can use AIUSD through first-party interfaces and chat-based experiences. AI agents can use [AIUSD Skills](/skills) (either the direct MCP-based skill or the natural language skill) or connect directly through the [MCP Hub API](/api). All paths converge on the same execution platform.

At a high level, the platform combines four layers:

* User and agent interfaces
* A shared orchestration layer for intent handling
* Core services for balances, custody, and trading
* On-chain execution and institutional custody

<Note>
  This page explains the platform at a high level. It intentionally omits sensitive implementation details such as key derivation formulas, signing paths, wallet inventories, and internal operational thresholds.
</Note>

## Shared platform for humans and AI agents

```mermaid theme={null}
flowchart LR
    H[Human users] --> UI[AIUSD interfaces]
    A[AI agents] --> SK[AIUSD Skill / NL Skill]
    A --> MCP[MCP Hub API]
    UI --> ORCH[Shared platform]
    SK --> ORCH
    MCP --> ORCH
    ORCH --> L[Ledger and custody services]
    ORCH --> T[TIM trading execution]
    T --> C[Supported chains and venues]
```

The key design choice is that human users and AI agents do not use separate trading systems. They use different entry points, but they rely on the same account model, custody controls, and execution infrastructure.

## Core components

| Component                  | Role                                                                                                                  |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| User interfaces            | Serve human users through web and chat-style experiences                                                              |
| `AIUSD Skills`             | Let external AI agents access the platform through packaged integrations (direct MCP skill or natural language skill) |
| `MCP Hub`                  | Exposes a tool surface for balances, funding, and trading                                                             |
| Ledger                     | Tracks AIUSD balances, staking balances, and movement between reserve and trading contexts                            |
| TIM                        | Interprets trading intent and routes execution to the right chain and venue                                           |
| Relayer and chain adapters | Handle chain-specific transaction execution                                                                           |
| Indexers and monitoring    | Detect deposits, observe on-chain state, and support operational controls                                             |
| `CEFFU`                    | Holds reserve assets in institutional custody                                                                         |

## Account model

The platform separates identity, reserve custody, and trading execution.

| Account type            | Purpose                                                            |
| ----------------------- | ------------------------------------------------------------------ |
| Login wallet            | Proves user identity during authentication                         |
| Deposit address         | Receives supported stablecoin deposits into the AIUSD system       |
| Trading account         | Holds tradable on-chain assets and executes user-authorized trades |
| Hot wallet              | Supports operational transfers and fulfillment                     |
| `CEFFU` custody account | Holds reserve assets backing liquid AIUSD                          |
| `CEFFU` staking account | Holds reserve assets backing staked AIUSD                          |

Two boundaries matter:

* `AIUSD ledger balances` are ledger liabilities inside the reserve model
* `On-chain trading balances` are execution balances outside the AIUSD reserve model until they are converted back through ledger operations

This separation lets the platform support natural-language trading without confusing reserve assets with active trading positions.

## Custody and reserve management

Reserve assets are managed in `CEFFU` custody. Liquid reserves and staked reserves are separated at the custody layer.

```mermaid theme={null}
flowchart LR
    D[User stablecoin deposits] --> DA[Deposit addresses]
    DA --> CW[CEFFU custody]
    CW --> HW[Hot wallets]
    CW --> SW[CEFFU staking]
    CW --> TA[Per-user trading accounts]
    SW --> Y[Yield strategy layer]
    TA --> EX[On-chain trading execution]
```

The custody model is designed around clear fund boundaries:

* Liquid AIUSD reserves are held in `CEFFU` custody
* Staked reserves are isolated in `CEFFU` staking
* Hot wallets support operational movement and fulfillment
* Trading accounts are used for execution, not for reserve backing

We run continuous reconciliation and operational monitoring across custody balances, ledger state, and execution flows. This architecture doc does not expose internal reconciliation procedures.

## How intent becomes execution

The same execution model supports a human asking for a trade and an AI agent fulfilling that trade on the user’s behalf.

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant U as Human or AI agent
    participant E as UI, Skills, or MCP client
    participant M as MCP Hub / orchestration
    participant L as Ledger
    participant T as TIM
    participant X as Chains and venues

    U->>E: Express trading intent
    E->>M: Submit authenticated request
    M->>L: Read balances and account state
    alt Funding or gas is needed
        M->>L: Move funds or ensure gas
    end
    M->>T: Submit trading intent
    T->>X: Execute on the target chain or venue
    X-->>T: Return transaction result
    T-->>M: Return execution status
    M-->>E: Return result and updated state
```

In practice, the flow is:

1. The user authenticates with a wallet-based identity flow.
2. The platform reads the user’s ledger balances and trading-account balances.
3. If needed, the platform moves value into the correct execution context.
4. `TIM` executes the trading intent on the destination chain or venue.
5. The platform returns execution status and updated balances.

This model is especially important for AI agents. Agents can use `AIUSD Skills` or the `MCP Hub API` directly to fulfill user trading intents without bypassing the platform’s custody and balance controls.

## Security model

The platform uses a wallet-based identity model and a separate trading-account control model.

* A user’s login wallet proves identity
* Per-user trading accounts are deterministically mapped from authenticated user identity inside a secure key-management boundary
* The application does not store those signing keys as plaintext in the application database
* Signing and execution occur through controlled service boundaries

This approach lets the platform give users persistent trading accounts while avoiding a simple “private key in database” design.

## Design principles

* One platform for both human users and AI agents
* Clear separation between reserve custody and trading execution
* Natural-language intent as the user-facing interaction model
* Shared backend controls for funding, gas, execution, and monitoring
* High-level transparency without exposing sensitive implementation details


# Strategies
Source: https://docs.aiusd.ai/examples

Ready-to-deploy trading strategies for AI agents.

## DCA Bot

Dollar-cost averaging strategy for long-term accumulation.

### Strategy

```
Every Monday at 10am:
- Buy $100 of BTC
- Buy $100 of ETH
- Stake any idle AIUSD
```

### Implementation

Tell your bot:

```
Set up weekly DCA:
- Every Monday at 10am
- Buy $100 BTC
- Buy $100 ETH
- Stake remaining AIUSD
```

### Expected Results

* Smooth out price volatility
* Build position over time
* Earn yield on idle capital

***

## Portfolio Rebalancer

Maintain target allocation automatically.

### Strategy

```
Every day at 9am:
- Check portfolio allocation
- If BTC > 60%: sell 10%
- If ETH < 30%: buy $500
- If SOL < 10%: buy $200
- Stake idle AIUSD
```

### Implementation

```
Set up daily rebalancing:
- Target: 50% BTC, 30% ETH, 20% SOL
- Check every day at 9am
- Rebalance if drift > 5%
- Stake idle funds
```

### Expected Results

* Maintain risk profile
* Auto take profits from winners
* Auto buy dips in losers

***

## Social Trading Bot

Copy trades from Twitter influencers.

### Strategy

```
Monitor @trader_alpha on Twitter
When they mention a token:
- Check if tradeable on Solana
- Buy $50 worth
- Set 10% stop loss
- Take profit at 20% gain
```

### Implementation

```
Monitor @trader_alpha with $500 budget:
- Buy $50 per signal
- Stop loss: -10%
- Take profit: +20%
- Max 10 concurrent positions
```

### Expected Results

* Capture alpha from experienced traders
* Automated execution (no manual work)
* Risk-managed with stop losses

***

## Arbitrage Bot

Exploit price differences across chains.

### Strategy

```
Monitor SOL price on:
- Solana DEXs (Jupiter)
- Base DEXs (Uniswap)

If price difference > 2%:
- Buy on cheaper chain
- Sell on expensive chain
- Account for gas fees
```

### Implementation

```
Set up arbitrage bot:
- Monitor SOL on Solana and Base
- Threshold: 2% price difference
- Trade size: $1000
- Account for gas and slippage
```

### Expected Results

* Capture arbitrage opportunities
* Low-risk profit
* Requires fast execution

***

## Yield Optimizer

Maximize staking returns automatically.

### Strategy

```
Every week:
- Check AIUSD staking APY
- Compare with other protocols
- If better yield available: migrate
- Compound rewards
```

### Implementation

```
Set up yield optimization:
- Check APY every week
- If AIUSD APY > 15%: stake all
- If AIUSD APY < 10%: look for alternatives
- Auto-compound rewards
```

### Expected Results

* Maximize passive income
* Auto-compound for growth
* Adapt to changing rates

***

## Momentum Trading Bot

Trade based on price momentum.

### Strategy

```
Monitor top 20 tokens by market cap
If token gains > 10% in 1 hour:
- Buy $100 worth
- Set stop loss at entry price
- Take profit at +15%
```

### Implementation

```
Set up momentum bot:
- Watch top 20 tokens
- Trigger: +10% in 1 hour
- Position size: $100
- Stop loss: 0%
- Take profit: +15%
```

### Expected Results

* Capture momentum moves
* Protected downside with stop loss
* Quick profits on volatile moves

***

## Mean Reversion Bot

Buy dips, sell rallies.

### Strategy

```
Monitor BTC and ETH prices
If BTC drops > 5% in 24h:
- Buy $500 worth
- Take profit at +5%

If BTC rallies > 5% in 24h:
- Sell 50% of position
```

### Implementation

```
Set up mean reversion:
- Watch BTC and ETH
- Buy trigger: -5% in 24h
- Sell trigger: +5% in 24h
- Position size: $500
```

### Expected Results

* Profit from volatility
* Buy low, sell high
* Works in ranging markets

***

## Grid Trading Bot

Profit from price oscillation.

### Strategy

```
Set up grid for ETH:
- Price range: $2500 - $3500
- Grid levels: 10
- Buy at each level going down
- Sell at each level going up
```

### Implementation

```
Set up grid trading:
- Asset: ETH
- Range: $2500 - $3500
- Levels: 10
- Capital: $5000
```

### Expected Results

* Profit from sideways movement
* No need to predict direction
* Works in ranging markets

***

## Risk Management Bot

Protect your portfolio automatically.

### Strategy

```
Monitor all open positions
If any position loses > 10%:
- Close position immediately
- Send alert

If total portfolio loses > 20%:
- Close all positions
- Move to stablecoins
```

### Implementation

```
Set up risk management:
- Per-position stop loss: -10%
- Portfolio stop loss: -20%
- Auto-close on trigger
- Send alerts
```

### Expected Results

* Limit downside risk
* Preserve capital
* Sleep better at night

***

## Tips for Bot Success

<AccordionGroup>
  <Accordion title="Start Small">
    Test strategies with small amounts first. Scale up after proving profitability.
  </Accordion>

  <Accordion title="Monitor Daily">
    Check bot performance daily. Adjust parameters based on market conditions.
  </Accordion>

  <Accordion title="Set Limits">
    Always set:

    * Maximum position size
    * Daily trade limit
    * Total portfolio exposure
  </Accordion>

  <Accordion title="Backtest First">
    Simulate strategy on historical data before going live.
  </Accordion>

  <Accordion title="Have Emergency Stop">
    Always have a way to stop your bot immediately:

    ```
    Stop all bots
    Close all positions
    ```
  </Accordion>
</AccordionGroup>

<Card title="Trading Guide" icon="chart-line" href="/trading">
  Learn all trading commands
</Card>


# Overview
Source: https://docs.aiusd.ai/index

Trading infrastructure for AI agents. Unified venues, unified capital, programmable execution.

## Introduction

AIUSD is trading infrastructure purpose-built for AI agents. It unifies fragmented venues, abstracts away capital complexity, and gives agents a programmable execution layer — so they can trade across DEXs, CEXs, perpetual markets, prediction markets, and more — through a single interface.

<Frame>
  <img alt="AIUSD Platform" />
</Frame>

***

## Core Concepts

<CardGroup>
  <Card title="Unified Venues" icon="layer-group">
    One interface to spot, perpetuals, prediction markets, and more. No venue-specific adapters.
  </Card>

  <Card title="Unified Capital Layer" icon="coins">
    Deposit once, trade anywhere. Gas, bridging, and stablecoin conversion handled automatically.
  </Card>

  <Card title="Conditional Execution" icon="code-branch">
    Program trades against price, time, portfolio, or signal conditions. The platform executes autonomously.
  </Card>
</CardGroup>

***

## Unified Venues

AI agents shouldn't need to integrate with each trading venue independently. AIUSD normalizes access across venue types so a single tool call can route to the right market.

| Venue Type             | Platforms                                                            | What agents can do                                                                                                    |
| ---------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **DEX (Spot)**         | Jupiter, 1inch across Solana, Ethereum, BSC, Base, Arbitrum, Polygon | Buy, sell, swap any token                                                                                             |
| **Perpetuals**         | HyperLiquid                                                          | Long, short, close with up to 50x leverage                                                                            |
| **Prediction Markets** | Polymarket                                                           | Trade on event outcomes                                                                                               |
| **Yield**              | sAIUSD staking                                                       | Earn yield via funding rate arbitrage strategy (10–20% APY, Sharpe 22, delta neutral, 7-day withdrawal after unstake) |

The agent expresses intent ("buy NVDAx", "long BTC 10x"). The platform selects the optimal venue and routing path, handles cross-chain bridging, and manages gas — the agent never touches any of it.

***

## Unified Capital Layer

Today, different assets live on different platforms — TRUMP trades on Solana, UNI on Ethereum, ASTER on BSC, perpetuals on HyperLiquid, event markets on Polymarket. Each requires its own stablecoin, gas token, and wallet setup. AIUSD eliminates this entirely.

<Steps>
  <Step title="Deposit once">
    Send USDC or USDT on any supported chain (Solana, Ethereum, Base, BSC, and more). Your balance is credited as AIUSD.
  </Step>

  <Step title="Trade anywhere">
    Use AIUSD to trade on any venue. The platform handles conversion to the right stablecoin, gas funding, and chain routing automatically.
  </Step>

  <Step title="Settle transparently">
    AIUSD is backed 1:1 by USDT and USDC held in CEFFU institutional custody. It is not a token — there is no contract address. It is a ledger balance representing your claim on underlying reserves.
  </Step>
</Steps>

<Note>
  AIUSD is **not** a stablecoin. It is a capital abstraction layer. Underlying reserves are held in institutional-grade custody (CEFFU) and are fully backed by USDT/USDC.
</Note>

***

## Conditional Execution

Agents can define rules that execute trades when future conditions are met — without staying online or polling.

### Price Triggers

```text theme={null}
If BTC drops below $60k, sell all my BTC
If ETH goes above $3k, buy $500 of ETH
When SOL hits $50, close my SOL position
```

### Time-Based

```text theme={null}
Every Monday at 10am, buy $100 of BTC
Every day at 9am, check my portfolio and rebalance
```

### Portfolio-Based

```text theme={null}
If BTC > 60% of portfolio, sell 10%
If ETH < 30% of portfolio, buy $500
Every Sunday at midnight, rebalance to 50% BTC / 30% ETH / 20% SOL
```

### Event-Driven

React to real-world events in real time — social signals, on-chain activity, exchange announcements.

#### Social Signal Trading

```text theme={null}
Monitor @trader_alpha on Twitter
When they mention a token, buy $50 worth
Set 10% stop loss on each position

If @realDonaldTrump posts anything negative about tariffs, close all positions immediately

If @CoinbaseAssets posts a new token listing, buy that token on DEX for 2% of my cash,
with 50% take profit and 20% stop loss
```

#### On-Chain Copy Trading

```text theme={null}
If this smart address I'm tracking on Polymarket trades a political contract,
buy the same contract position for $1,000
```

These conditions are stored and evaluated server-side. The agent doesn't need to maintain state or run continuously.

***

## Integration

Three ways to connect your agent to AIUSD:

<CardGroup>
  <Card icon="bolt" href="/skills#aiusd-core" title="AIUSD Core">
    **Structured CLI tools**

    Client-side LLM handles reasoning. No platform inference cost.
  </Card>

  <Card icon="comments" href="/skills#aiusd-pro" title="AIUSD Pro">
    **Managed AI agent**

    Backend handles reasoning, tool selection, and multi-step execution.
  </Card>

  <Card icon="code" href="/api" title="MCP Hub API">
    **Direct API**

    JSON-RPC 2.0 via Model Context Protocol for custom integrations.
  </Card>
</CardGroup>

```bash theme={null}
# Install AIUSD Core
npx skills add galpha-ai/aiusd-core -y -g

# Install AIUSD Pro
npx skills add galpha-ai/aiusd-pro -y -g
```

<Card icon="rocket" href="/quickstart" title="Get Started">
  Start trading in under 5 minutes
</Card>


# Quick Start
Source: https://docs.aiusd.ai/quickstart

Get your agent trading in under 5 minutes.

<CardGroup>
  <Card title="Web App" icon="globe" href="#web-app">
    Trade directly at aiusd.ai. No setup required.
  </Card>

  <Card title="Telegram Bot" icon="paper-plane" href="#telegram-bot">
    Trade from Telegram. Message @aiusd\_ai\_bot to start.
  </Card>

  <Card title="AIUSD Core" icon="bolt" href="#aiusd-core">
    Structured CLI tools for AI agents. No platform inference cost.
  </Card>

  <Card title="AIUSD Pro" icon="comments" href="#aiusd-pro">
    AI agent skill with built-in reasoning. Best for OpenClaw, Claude Code, Codex, and Cursor.
  </Card>

  <Card title="MCP Hub API" icon="code" href="#mcp-hub-api">
    Direct JSON-RPC 2.0 for custom agent builds.
  </Card>
</CardGroup>

***

## Web App

The fastest way to start. No installation, no CLI — just open [aiusd.ai](https://aiusd.ai) and trade.

<Steps>
  <Step title="Open aiusd.ai">
    Go to [aiusd.ai](https://aiusd.ai) and connect your wallet or create a new account.
  </Step>

  <Step title="Deposit">
    Send USDC or USDT on any supported chain. Your balance is credited as AIUSD instantly.
  </Step>

  <Step title="Trade">
    Type what you want to do in natural language — the built-in AI agent handles the rest.
  </Step>
</Steps>

***

## Telegram Bot

Trade from any Telegram conversation. No app to install, no wallet extension needed.

<Steps>
  <Step title="Open the bot">
    Message [@aiusd\_ai\_bot](https://t.me/aiusd_ai_bot) on Telegram.
  </Step>

  <Step title="Create account or sign in">
    The bot walks you through authentication — create a new wallet or link an existing one.
  </Step>

  <Step title="Trade">
    Send messages like "Buy \$100 of SOL", "Long ETH 10x", or "What's my balance?" — the bot executes directly.
  </Step>
</Steps>

***

## AIUSD Core

For agents that handle their own reasoning. Install the skill, authenticate, and start calling structured commands.

<Steps>
  <Step title="Install">
    <Tabs>
      <Tab title="Claude Code / Codex / Cursor">
        ```bash theme={null}
        npx skills add galpha-ai/aiusd-core -y -g
        ```
      </Tab>

      <Tab title="npm">
        ```bash theme={null}
        npm install -g aiusd-core
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Authenticate">
    ```bash theme={null}
    aiusd login --browser
    ```

    A browser window opens. Sign in or create a new account — the CLI picks up the session automatically.
  </Step>

  <Step title="Trade">
    ```bash theme={null}
    aiusd balances                                      # Check account
    aiusd guide spot                                    # Get command reference
    aiusd spot buy -b SOL -a 100                        # Buy $100 of SOL
    aiusd perp long --asset ETH --size 0.1 --leverage 10  # Long ETH 10x
    ```
  </Step>
</Steps>

<Card title="Full Core Reference" icon="book" href="/skills#aiusd-core">
  All commands, domains, and configuration
</Card>

***

## AIUSD Pro

For agents that want a turnkey experience. Send natural language — the backend handles reasoning, tool selection, and execution.

<Steps>
  <Step title="Install">
    <Tabs>
      <Tab title="Claude Code / Codex / Cursor">
        ```bash theme={null}
        npx skills add galpha-ai/aiusd-pro -y -g
        ```
      </Tab>

      <Tab title="npm">
        ```bash theme={null}
        npm install -g aiusd-pro
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Authenticate">
    ```bash theme={null}
    aiusd-pro login --browser
    ```
  </Step>

  <Step title="Trade">
    ```bash theme={null}
    aiusd-pro send "What's my balance?"
    aiusd-pro send "Buy $100 of SOL"
    aiusd-pro send "Long ETH 10x"
    aiusd-pro send "If BTC drops below $60k, sell everything"
    ```

    The backend agent processes your intent, executes the trade, confirms the transaction, and streams the result back.
  </Step>
</Steps>

<Card title="Full Pro Reference" icon="book" href="/skills#aiusd-pro">
  How it works, session management, and capabilities
</Card>

***

## MCP Hub API

For developers building custom agents. Connect directly to the AIUSD execution layer via Model Context Protocol.

<Steps>
  <Step title="Get API access">
    | Environment | Endpoint                                |
    | ----------- | --------------------------------------- |
    | Production  | `https://mcp.alpha.dev/api/mcp-hub/mcp` |
    | Development | `https://dev.alpha.dev/api/mcp-hub/mcp` |

    <Note>
      Authentication required. Contact support for API access.
    </Note>
  </Step>

  <Step title="Connect your agent">
    <Tabs>
      <Tab title="Claude Desktop">
        Add to `claude_desktop_config.json`:

        ```json theme={null}
        {
          "mcpServers": {
            "aiusd": {
              "url": "https://mcp.alpha.dev/api/mcp-hub/mcp",
              "transport": "http",
              "headers": {
                "Authorization": "Bearer YOUR_TOKEN"
              }
            }
          }
        }
        ```
      </Tab>

      <Tab title="Anthropic SDK">
        ```typescript theme={null}
        import Anthropic from "@anthropic-ai/sdk";

        const client = new Anthropic();

        const response = await client.messages.create({
          model: "claude-sonnet-4-6-20250514",
          max_tokens: 1024,
          tools: [{
            type: "custom",
            name: "mcp",
            mcp_server: {
              url: "https://mcp.alpha.dev/api/mcp-hub/mcp",
              transport: "http",
              headers: {
                "Authorization": "Bearer YOUR_TOKEN"
              }
            }
          }],
          messages: [{
            role: "user",
            content: "Buy $100 of SOL"
          }]
        });
        ```
      </Tab>

      <Tab title="cURL">
        ```bash theme={null}
        curl -X POST https://mcp.alpha.dev/api/mcp-hub/mcp \
          -H "Content-Type: application/json" \
          -H "Authorization: Bearer YOUR_TOKEN" \
          -d '{
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/list"
          }'
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

<Card title="API Reference" icon="terminal" href="/api">
  Full tool reference and response formats
</Card>

***

## Next Steps

<CardGroup>
  <Card title="Trading Guide" icon="chart-line" href="/trading">
    All supported trading operations
  </Card>

  <Card title="Example Strategies" icon="lightbulb" href="/examples">
    Ready-to-deploy bot strategies
  </Card>

  <Card title="Architecture" icon="building" href="/architecture">
    How the platform works
  </Card>
</CardGroup>


# Core & Pro
Source: https://docs.aiusd.ai/skills

Two integration paths for AI agents — choose the level of control you need.

## Overview

AIUSD provides two official skills for integrating trading capabilities into AI agents:

<CardGroup>
  <Card title="AIUSD Core" icon="bolt">
    **Structured CLI tools**

    Your agent's LLM calls trading commands directly via MCP. You control the reasoning and orchestration.

    No platform inference cost.
  </Card>

  <Card title="AIUSD Pro" icon="comments">
    **Managed AI agent**

    Delegates to a backend agent that handles reasoning, tool selection, and multi-step execution.

    Natural language in, results out.
  </Card>
</CardGroup>

## Which Should I Use?

|                      | Core                                      | Pro                                    |
| -------------------- | ----------------------------------------- | -------------------------------------- |
| **How it works**     | Agent calls CLI/MCP tools directly        | Messages sent to managed backend agent |
| **Reasoning**        | Client-side (your agent's LLM)            | Server-side (AIUSD backend)            |
| **Interface**        | Structured commands                       | Natural language                       |
| **Multi-step flows** | Agent manages state                       | Backend maintains session context      |
| **Inference cost**   | None — bring your own LLM                 | Included                               |
| **Best for**         | Developers building custom agents         | End users and turnkey integrations     |
| **Trade-off**        | More control, requires capable host agent | Easier setup, less granular control    |

<Tip>
  **Not sure?** Start with **AIUSD Pro** for the fastest setup. Switch to **AIUSD Core** when you need granular control over execution logic.
</Tip>

***

## AIUSD Core

Structured CLI tools and MCP integration. Your agent invokes trading commands and handles orchestration.

### Installation

<Tabs>
  <Tab title="Claude Code / Codex / Cursor">
    ```bash theme={null}
    npx skills add galpha-ai/aiusd-core -y -g
    ```
  </Tab>

  <Tab title="OpenClaw">
    Drag & drop the [.skill file](https://github.com/galpha-ai/aiusd-core/releases/latest/download/aiusd-core.skill) into your OpenClaw chat, or:

    ```bash theme={null}
    openclaw skill install aiusd-core.skill
    ```
  </Tab>

  <Tab title="npm">
    ```bash theme={null}
    npm install -g aiusd-core
    ```

    This registers `aiusd-core` globally so you can use `aiusd-core <command>` directly.
  </Tab>

  <Tab title="Manual">
    ```bash theme={null}
    git clone https://github.com/galpha-ai/aiusd-core.git
    cd aiusd-core && npm install && npm run build
    ```
  </Tab>
</Tabs>

### Authentication

```bash theme={null}
# Browser login (recommended)
aiusd-core login --browser

# Create new account
aiusd-core login --new-wallet

# Switch accounts
aiusd-core logout
aiusd-core login --browser
```

### CLI Usage

```bash theme={null}
# Check balances
aiusd-core balances

# Get command reference for a domain
aiusd-core guide spot

# Execute trades
aiusd-core spot buy -b SOL -a 100
aiusd-core perp long --asset ETH --size 0.1 --leverage 10
```

### Command Reference

| Domain                 | Commands                                                                                                                                                                                                                     |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Account**            | `aiusd-core balances`, `aiusd-core accounts`, `aiusd-core transactions`, `aiusd-core get-deposit-address`                                                                                                                    |
| **Spot**               | `aiusd-core spot buy -b SOL -a 100`, `aiusd-core spot sell -b ETH -a all`                                                                                                                                                    |
| **Perpetuals**         | `aiusd-core perp long --asset ETH --size 0.1 --leverage 10`, `aiusd-core perp close --asset ETH`, `aiusd-core perp deposit --amount 100`, `aiusd-core perp withdraw --amount 50`                                             |
| **HyperLiquid Spot**   | `aiusd-core hl-spot buy --coin HYPE --amount 100`, `aiusd-core hl-spot sell --coin PURR --amount 50`                                                                                                                         |
| **Prediction Markets** | `aiusd-core pm buy --market "bitcoin-100k" --outcome Yes --amount 10`, `aiusd-core pm sell`, `aiusd-core pm positions`, `aiusd-core pm orders`, `aiusd-core pm search -q "election"`, `aiusd-core pm cancel --order-id <id>` |
| **Monitoring**         | `aiusd-core monitor add --handle @elonmusk --budget 100`, `aiusd-core monitor list`, `aiusd-core monitor cancel --order-id <id>`                                                                                             |
| **Market Data**        | `aiusd-core market hot-tokens`                                                                                                                                                                                               |
| **Staking**            | `aiusd-core call genalpha_stake_aiusd -p '{"amount":"100"}'`, `aiusd-core call genalpha_unstake_aiusd -p '{"amount":"50"}'`                                                                                                  |

Run `aiusd-core guide <domain>` before executing commands to get the latest parameter reference.

**Source:** [github.com/galpha-ai/aiusd-core](https://github.com/galpha-ai/aiusd-core)

***

## AIUSD Pro

Natural language interface to a managed backend agent. Send messages in plain language — the agent handles reasoning, execution, and transaction confirmation.

### Installation

<Tabs>
  <Tab title="Claude Code / Codex / Cursor">
    ```bash theme={null}
    npx skills add galpha-ai/aiusd-pro -y -g
    ```
  </Tab>

  <Tab title="OpenClaw">
    Drag & drop the [.skill file](https://github.com/galpha-ai/aiusd-pro/releases/latest/download/aiusd-pro.skill) into your OpenClaw chat, or:

    ```bash theme={null}
    openclaw skill install aiusd-pro.skill
    ```
  </Tab>

  <Tab title="npm">
    ```bash theme={null}
    npm install -g aiusd-pro
    ```

    This registers `aiusd-pro` globally.
  </Tab>

  <Tab title="Manual">
    ```bash theme={null}
    git clone https://github.com/galpha-ai/aiusd-pro.git
    cd aiusd-pro && npm install && npm run build
    ```
  </Tab>
</Tabs>

### Authentication

```bash theme={null}
# Browser login (recommended)
aiusd-pro login --browser

# Create new account
aiusd-pro login --new-wallet

# Switch accounts
aiusd-pro logout
aiusd-pro login --browser
```

### Usage

```bash theme={null}
aiusd-pro send "What are my balances?"
aiusd-pro send "Buy $100 of SOL"
aiusd-pro send "Long ETH 10x with $500"
```

### How It Works

```
You send a message
       ↓
Backend agent processes intent
       ↓
Agent streams response via WebSocket
       ↓
CLI auto-polls transaction status
       ↓
Session maintained for follow-ups
```

1. **Send** — your message is posted to the AIUSD backend agent
2. **Reason** — the agent selects tools, plans execution, and handles multi-step logic
3. **Execute** — trades are placed and transactions confirmed automatically
4. **Respond** — results stream back in natural language

### What You Can Ask

| Domain           | Examples                                                     |
| ---------------- | ------------------------------------------------------------ |
| **Spot Trading** | "Buy \$100 of SOL", "Sell all my ETH", "Swap TRUMP for USDC" |
| **Perpetuals**   | "Long ETH 10x", "Short BTC at \$70k", "Close my position"    |
| **Account**      | "What's my balance?", "Show my deposit addresses"            |
| **Staking**      | "Stake 500 AIUSD", "Unstake my AIUSD"                        |
| **Market Data**  | "What's trending?", "Show xStock prices"                     |

### Session Management

```bash theme={null}
aiusd-pro session new      # Start a new conversation
aiusd-pro session list     # List sessions
aiusd-pro session reset    # Reset current session
aiusd-pro cancel           # Cancel active operation
```

**Source:** [github.com/galpha-ai/aiusd-pro](https://github.com/galpha-ai/aiusd-pro)

***

## Supported Platforms

Both skills support the same platforms:

| Platform           | Install                                            |
| ------------------ | -------------------------------------------------- |
| **Claude Code**    | `npx skills add` or symlink to `~/.claude/skills/` |
| **Codex**          | `npx skills add` or symlink to `~/.codex/skills/`  |
| **Cursor**         | `npx skills add` or symlink to `.cursor/skills/`   |
| **OpenClaw**       | `.skill` file or symlink to `~/.openclaw/skills/`  |
| **GitHub Copilot** | Symlink to `.github/skills/`                       |

Both skills require **Node.js >= 18.0.0**.

## Security

<AccordionGroup>
  <Accordion title="Local-First Authentication">
    Authentication tokens stored locally on your device in `~/.aiusd/`. No credentials sent to third parties.
  </Accordion>

  <Accordion title="Secure Storage">
    Token files written with restrictive permissions (0600). Wallet mnemonic stored separately.
  </Accordion>

  <Accordion title="Open Source">
    All skill code is transparent and auditable on GitHub.
  </Accordion>
</AccordionGroup>

## Troubleshooting

### Authentication Issues

```bash theme={null}
# Logout and re-login
aiusd-core logout              # or aiusd-pro logout
aiusd-core login --browser     # or aiusd-pro login --browser
```

If browser login fails, try creating a new account with `--new-wallet`.

### Skill Not Loading

```bash theme={null}
# Check installation
ls ~/.claude/skills/aiusd-core
ls ~/.claude/skills/aiusd-pro

# Reinstall
npx skills add galpha-ai/aiusd-core -y -g
npx skills add galpha-ai/aiusd-pro -y -g
```


# Trading
Source: https://docs.aiusd.ai/trading

Complete guide to all supported trading operations.

## Spot Trading

Trade tokens across multiple chains with natural language.

### Basic Commands

```
Buy $100 of SOL
Sell all my ETH
Swap TRUMP for USDC
```

### Supported Chains

| Chain    | Tokens            | DEXs               |
| -------- | ----------------- | ------------------ |
| Solana   | All SPL tokens    | Jupiter, Raydium   |
| Base     | All ERC-20 tokens | Uniswap, Aerodrome |
| Ethereum | All ERC-20 tokens | Uniswap, Sushiswap |

### Specify Chain

```
Buy ETH on Base
Buy SOL on Solana
```

If chain not specified, AIUSD auto-selects based on liquidity and fees.

### Advanced

```
Buy $500 of ETH with 1% slippage
Sell 10 SOL at market price
Swap all my USDC for BTC
```

***

## Perpetual Futures

Trade with leverage on HyperLiquid.

### Open Position

```
Long ETH 10x
Short BTC 5x with $1000
Long SOL 20x at $45
```

**Leverage:** Up to 50x

### Close Position

```
Close my ETH position
Close all positions
Take profit on BTC position
```

### Check Positions

```
Show my open positions
What's my PnL on ETH?
```

***

## Prediction Markets

Bet on real-world outcomes via Polymarket.

### Place Bet

```
Bet $10 on Yes for Bitcoin 100k
Bet $50 on No for Trump wins 2024
```

### Search Markets

```
Search election markets
Find Bitcoin price markets
Show trending prediction markets
```

### Check Positions

```
Show my prediction positions
What's my PnL on predictions?
```

***

## Staking & Yield

Earn yield on idle AIUSD.

### Stake

```
Stake 500 AIUSD
Stake all my AIUSD
```

**Returns:** \~20% APY on sAIUSD

### Unstake

```
Unstake my AIUSD
Unstake 100 AIUSD
```

### Check Yield

```
How much am I earning?
Show my staking balance
```

***

## Conditional Execution

Set up automated trades based on conditions.

### Price Triggers

```
If BTC drops below $60k, sell all my BTC
If ETH goes above $3k, buy $500 of ETH
When SOL hits $50, close my SOL position
```

### Time-Based

```
Every Monday at 10am, buy $100 of BTC
Every day at 9am, check my portfolio
```

### Portfolio-Based

```
If BTC > 60% of portfolio, sell 10%
If ETH < 30% of portfolio, buy $500
```

***

## Social Trading

Auto-execute trades based on Twitter signals.

### Monitor Influencer

```
Monitor @elonmusk with $100 budget
Monitor @trader_alpha with $500 budget
```

### Check Monitors

```
List my active monitors
Stop monitoring @elonmusk
```

### How It Works

1. Bot monitors Twitter account
2. When they mention a token
3. Bot checks if tradeable
4. Auto-executes trade with your budget

***

## Portfolio Management

### Check Balance

```
What's my balance?
Show my portfolio
How much AIUSD do I have?
```

### View Positions

```
Show my open positions
What tokens do I own?
Show my trading history
```

### Addresses

```
Show my trading addresses
What's my Solana address?
What's my Base address?
```

### Transactions

```
Show my recent transactions
Show my last 10 trades
```

***

## Market Data

### Trending Tokens

```
What tokens are trending?
Show top gainers today
```

### Prices

```
What's the price of SOL?
Show xStock prices
```

### Market Cap

```
Show top 10 tokens by market cap
```

***

## Deposits & Withdrawals

### Deposit

```
How do I deposit?
What are my deposit addresses?
Show deposit instructions
```

**Supported:**

* USDC (Solana, Base, Ethereum)
* USDT (Solana, Base, Ethereum)
* Native tokens (SOL, ETH)

### Withdraw

```
Withdraw 100 AIUSD to my wallet
Send 50 USDC to [address]
```

***

## Tips & Best Practices

<AccordionGroup>
  <Accordion title="Start Small">
    Test with small amounts first. Gradually increase position sizes as you get comfortable.
  </Accordion>

  <Accordion title="Use Stop Losses">
    Always set stop losses for leveraged positions:

    ```
    Long ETH 10x with stop loss at $2500
    ```
  </Accordion>

  <Accordion title="Monitor Conditions">
    Check your conditional orders regularly:

    ```
    List my active monitors
    Show my pending orders
    ```
  </Accordion>

  <Accordion title="Diversify">
    Don't put all capital in one position. Spread across multiple assets and strategies.
  </Accordion>

  <Accordion title="Check Fees">
    Different chains have different fees. Solana is typically cheapest for small trades.
  </Accordion>
</AccordionGroup>

<Card title="Examples" icon="lightbulb" href="/examples">
  See real bot strategies
</Card>


# HTTP API reference
Source: https://docs.aiusd.ai/trading-api/api

TIM HTTP API endpoints, authentication, and request/response schemas.

## Base URL

| Environment | URL                            |
| ----------- | ------------------------------ |
| Production  | `https://api.alpha.dev/api/v1` |
| Development | `https://dev.alpha.dev/api/v1` |

## Authentication

All endpoints except health check and internal cluster endpoints require a JWT Bearer token:

```
Authorization: Bearer <jwt_token>
```

<Note>
  Contact support for API access credentials.
</Note>

## Endpoints

| Method | Path                       | Description                          | Auth |
| ------ | -------------------------- | ------------------------------------ | ---- |
| POST   | `/api/v1/execute-intent`   | Execute or register a trading intent | Yes  |
| POST   | `/api/v1/normalize-intent` | Normalize intent for auto-approval   | Yes  |
| POST   | `/api/v1/trades/simulate`  | Simulate a trade without execution   | No   |
| GET    | `/api/v1/tokens/resolve`   | Resolve token symbols to addresses   | No   |
| GET    | `/api/v1/transactions`     | Transaction history                  | Yes  |

***

## POST `/api/v1/execute-intent`

Execute an on-chain swap, register a conditional rule, or close a position.

### Request

```json theme={null}
{
  "intent": "<intent><type>IMMEDIATE</type><chain_id>solana:mainnet-beta</chain_id>...</intent>"
}
```

| Field    | Type   | Required | Description                                                                |
| -------- | ------ | -------- | -------------------------------------------------------------------------- |
| `intent` | string | Yes      | TIM intent as XML string. See [intent format](/trading-api/intent-format). |

### Response

```json theme={null}
{
  "intent_id": "550e8400-e29b-41d4-a716-446655440000",
  "transaction_hash": "5UfD...",
  "status": "EXECUTION_STATUS_CONFIRMED",
  "details": "Swap executed successfully",
  "system_message": "...",
  "position_id": "pos_abc123",
  "exit_orders": {
    "take_profit_order_id": "ord_tp_1",
    "stop_loss_order_id": "ord_sl_1"
  },
  "rule_id": null,
  "wait_hint": {
    "type": "transaction",
    "tx_hash": "5UfD...",
    "chain_id": "solana:mainnet-beta",
    "commitment": "finalized",
    "poll_interval_ms": 2000,
    "timeout_ms": 60000,
    "system_message": "..."
  }
}
```

| Field              | Type           | Description                                                                   |
| ------------------ | -------------- | ----------------------------------------------------------------------------- |
| `intent_id`        | string         | Unique identifier for this intent                                             |
| `transaction_hash` | string or null | Blockchain transaction hash. Present for `IMMEDIATE` swaps, absent for rules. |
| `status`           | string         | Execution status (see below)                                                  |
| `details`          | string         | Human-readable status message                                                 |
| `system_message`   | string         | Message with balance verification and block explorer link                     |
| `position_id`      | string or null | Position ID if exit strategy was configured or for `CLOSE_POSITION`           |
| `exit_orders`      | object or null | Take-profit and stop-loss order IDs                                           |
| `rule_id`          | string or null | Rule ID for `CONDITIONAL_ENTRY` intents                                       |
| `cancelled_orders` | array or null  | Cancelled order IDs (for `CLOSE_POSITION`)                                    |
| `realized_pnl`     | object or null | Realized PnL with `pnl_percent` and `pnl_usd` (for `CLOSE_POSITION`)          |
| `prerequisite`     | object or null | Prerequisite action required before execution (e.g., funding)                 |
| `continuation`     | object or null | Follow-up intent to execute after prerequisite completes                      |
| `wait_hint`        | object or null | Polling hint for transaction confirmation                                     |

### Execution status values

| Status                       | Meaning                                         |
| ---------------------------- | ----------------------------------------------- |
| `EXECUTION_STATUS_PENDING`   | Transaction submitted, awaiting confirmation    |
| `EXECUTION_STATUS_CONFIRMED` | Transaction confirmed on-chain                  |
| `EXECUTION_STATUS_FAILED`    | Execution failed                                |
| `EXECUTION_STATUS_CANCELLED` | Intent was cancelled                            |
| `FUNDING_REQUIRED`           | Insufficient funds — check `prerequisite` field |

***

## POST `/api/v1/normalize-intent`

Parse and enrich an intent XML with resolved token addresses and USD values. Use this to preview what TIM will execute before submitting.

### Request

```json theme={null}
{
  "intent": "<intent>...</intent>"
}
```

### Response

```json theme={null}
{
  "intent": "{\"type\":\"IMMEDIATE\",\"chain_id\":\"solana:mainnet-beta\",...}"
}
```

The response `intent` field contains the normalized intent as a JSON string with resolved addresses and computed values.

***

## POST `/api/v1/trades/simulate`

Simulate a trade to check token liquidity and price impact without executing.

### Request

```json theme={null}
{
  "chain_id": "eip155:1",
  "token_address": "0x6982508145454Ce325dDbE47a25d4ec3d2311933",
  "amount_usd": 1000
}
```

| Field           | Type   | Required | Description                     |
| --------------- | ------ | -------- | ------------------------------- |
| `chain_id`      | string | Yes      | CAIP-2 chain identifier         |
| `token_address` | string | Yes      | Token contract/mint address     |
| `amount_usd`    | number | Yes      | Trade size in USD (must be > 0) |

### Response (success)

```json theme={null}
{
  "success": true,
  "chain_id": "eip155:1",
  "token_address": "0x6982508145454Ce325dDbE47a25d4ec3d2311933",
  "quote_token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "amount_usd": 1000.0,
  "expected_output": "15131564379480771843325952",
  "price_impact_bps": 0,
  "simulated_at": "2026-01-07T20:14:54.715394844+00:00"
}
```

### Response (failure)

```json theme={null}
{
  "success": false,
  "chain_id": "eip155:1",
  "token_address": "0x...",
  "quote_token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "amount_usd": 1000.0,
  "error_code": "insufficient_liquidity",
  "error_message": "Token has insufficient liquidity for requested amount",
  "simulated_at": "2026-01-07T20:14:54.715394844+00:00"
}
```

| Field              | Type           | Description                                   |
| ------------------ | -------------- | --------------------------------------------- |
| `success`          | boolean        | Whether the simulation succeeded              |
| `quote_token`      | string         | Quote token used (chain's default stablecoin) |
| `expected_output`  | string or null | Expected token output in smallest units       |
| `price_impact_bps` | number or null | Price impact in basis points (50 = 0.5%)      |
| `error_code`       | string or null | Error code if simulation failed               |
| `error_message`    | string or null | Error description if simulation failed        |
| `simulated_at`     | string         | ISO 8601 timestamp                            |

### Simulation error codes

| Code                     | Description                    | Retryable |
| ------------------------ | ------------------------------ | --------- |
| `insufficient_liquidity` | Liquidity below threshold      | Yes       |
| `token_not_found`        | Token not found on chain       | No        |
| `no_route_found`         | No swap route available        | Yes       |
| `high_price_impact`      | Price impact exceeds threshold | Yes       |
| `simulation_failed`      | RPC or aggregator error        | Yes       |

***

## GET `/api/v1/tokens/resolve`

Resolve a token symbol to contract addresses across chains.

### Query parameters

| Parameter   | Required | Description                                                          |
| ----------- | -------- | -------------------------------------------------------------------- |
| `query`     | Yes      | Token symbol to resolve (e.g., `USDC`, `SOL`)                        |
| `chain_ids` | No       | Comma-separated CAIP-2 chain IDs. Defaults to all configured chains. |

### Response

```json theme={null}
{
  "query": "USDC",
  "results": [
    {
      "chain_id": "solana:mainnet-beta",
      "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "symbol": "USDC",
      "name": "USD Coin",
      "decimals": 6
    }
  ],
  "errors": [
    {
      "chain_id": "eip155:56",
      "code": "TOKEN_NOT_FOUND",
      "message": "Token not found on chain"
    }
  ]
}
```

| Field                | Type   | Description                                 |
| -------------------- | ------ | ------------------------------------------- |
| `results[].chain_id` | string | CAIP-2 chain identifier                     |
| `results[].address`  | string | Token contract address                      |
| `results[].symbol`   | string | Token symbol                                |
| `results[].name`     | string | Token display name                          |
| `results[].decimals` | number | Token decimal places                        |
| `errors[].chain_id`  | string | Chain where resolution failed               |
| `errors[].code`      | string | Error code (`TOKEN_NOT_FOUND`, `API_ERROR`) |
| `errors[].message`   | string | Error description                           |

***

## GET `/api/v1/transactions`

List transaction history for the authenticated user.

### Query parameters

| Parameter        | Required | Default               | Description                              |
| ---------------- | -------- | --------------------- | ---------------------------------------- |
| `chain_id`       | No       | `solana:mainnet-beta` | Chain to query                           |
| `correlation_id` | No       | —                     | Filter by correlation ID                 |
| `context_query`  | No       | —                     | Filter by context label                  |
| `result_code`    | No       | —                     | Filter by result codes (comma-separated) |
| `page`           | No       | `0`                   | Page number (0-indexed)                  |
| `limit`          | No       | `20`                  | Items per page (max 100)                 |

***

## Error format

All errors follow this structure:

```json theme={null}
{
  "error": {
    "code": "INVALID_INTENT",
    "message": "Failed to parse intent XML",
    "details": { ... }
  }
}
```

### Common error codes

| Code                            | Description                        |
| ------------------------------- | ---------------------------------- |
| `INVALID_INTENT`                | Malformed or invalid intent XML    |
| `TOKEN_NOT_FOUND`               | Token symbol could not be resolved |
| `TXN_FAILED`                    | Transaction execution failed       |
| `TRANSACTION_SIGNING_FAILED`    | Signing operation failed           |
| `TRANSACTION_SUBMISSION_FAILED` | Blockchain submission failed       |
| `INVALID_CHAIN_ID`              | Chain ID not configured            |
| `INVALID_AMOUNT`                | Amount must be a positive number   |

## MCP Hub alternative

`MCP Hub` wraps TIM with the same capabilities via MCP tool calling. If you are building an AI agent that supports MCP, you can use `genalpha_tim_execute_intent` through the [MCP Hub API](/api) instead of calling the HTTP API directly. Both accept the same intent format and return equivalent responses.


# Intent format
Source: https://docs.aiusd.ai/trading-api/intent-format

XML schema reference for TIM trading intents.

## Intent structure

TIM intents are expressed in XML. Every intent has a `<type>`, a `<chain_id>`, and type-specific fields.

```xml theme={null}
<intent>
  <type>IMMEDIATE | CONDITIONAL_ENTRY | CLOSE_POSITION</type>
  <chain_id>solana:mainnet-beta</chain_id>
  <entry>
    <condition>...</condition>
    <action>...</action>
  </entry>
  <exit>...</exit>
</intent>
```

The `<entry>` block defines what triggers the trade and what action to take. The `<exit>` block is optional and defines take-profit/stop-loss conditions.

## Buy semantics

A `<buy>` action spends quote tokens to acquire base tokens.

* `<amount>` is the number of **quote** tokens to spend
* `<quote>` is the token you are spending (address or `AIUSD`)
* `<base>` is the token you are buying (address or symbol)

```xml theme={null}
<action>
  <buy>
    <amount>1</amount>
    <quote>EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v</quote>
    <base>trump</base>
  </buy>
</action>
```

This spends 1 USDC to buy TRUMP on Solana.

<Note>
  `<buy>` does **not** support `<relative>` or percentage amounts. To buy with your full balance, query your portfolio first and use the absolute amount.
</Note>

## Sell semantics

A `<sell>` action sells base tokens to receive quote tokens.

* `<amount>` is the number of **base** tokens to sell
* `<quote>` is the token you receive
* `<base>` is the token you are selling

```xml theme={null}
<action>
  <sell>
    <amount>1000.5</amount>
    <quote>So11111111111111111111111111111111111111112</quote>
    <base>EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v</base>
  </sell>
</action>
```

### Sell all

Use `<amount>all</amount>` to sell your entire balance:

```xml theme={null}
<action>
  <sell>
    <amount>all</amount>
    <quote>EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v</quote>
    <base>JUP</base>
  </sell>
</action>
```

### Sell percentage

Use `<relative>` to sell a percentage of your balance (sell only):

```xml theme={null}
<action>
  <sell>
    <relative><percentage>50.0</percentage></relative>
    <quote>So11111111111111111111111111111111111111112</quote>
    <base>EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v</base>
  </sell>
</action>
```

## Default quote token

When the user does not specify a quote token, default to USDC on the target chain. For example:

* "sell TRUMP" uses USDC as quote
* "sell TRUMP for AIUSD" uses AIUSD as quote
* "buy TRUMP with SOL" uses SOL as quote

## Exit strategies

Attach an `<exit>` block to set take-profit and stop-loss conditions:

```xml theme={null}
<exit>
  <conditions>
    <profit_percent>10</profit_percent>
    <loss_percent>5</loss_percent>
  </conditions>
  <logic>OR</logic>
</exit>
```

| Field            | Meaning                                                                 |
| ---------------- | ----------------------------------------------------------------------- |
| `profit_percent` | Sell when PnL reaches +X%                                               |
| `loss_percent`   | Sell when PnL reaches -X%                                               |
| `logic`          | `OR` (default — either condition triggers) or `AND` (both must be true) |

## Intent type examples

### IMMEDIATE — buy with USDC

```xml theme={null}
<intent>
  <type>IMMEDIATE</type>
  <chain_id>solana:mainnet-beta</chain_id>
  <entry>
    <condition><immediate>true</immediate></condition>
    <action>
      <buy>
        <amount>1</amount>
        <quote>EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v</quote>
        <base>trump</base>
      </buy>
    </action>
  </entry>
</intent>
```

### IMMEDIATE — buy with SOL

```xml theme={null}
<intent>
  <type>IMMEDIATE</type>
  <chain_id>solana:mainnet-beta</chain_id>
  <entry>
    <condition><immediate>true</immediate></condition>
    <action>
      <buy>
        <amount>0.001</amount>
        <quote>So11111111111111111111111111111111111111112</quote>
        <base>pump</base>
      </buy>
    </action>
  </entry>
</intent>
```

### IMMEDIATE — sell all

```xml theme={null}
<intent>
  <type>IMMEDIATE</type>
  <chain_id>solana:mainnet-beta</chain_id>
  <entry>
    <condition><immediate>true</immediate></condition>
    <action>
      <sell>
        <amount>all</amount>
        <quote>EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v</quote>
        <base>JUP</base>
      </sell>
    </action>
  </entry>
</intent>
```

### IMMEDIATE — sell percentage

```xml theme={null}
<intent>
  <type>IMMEDIATE</type>
  <chain_id>solana:mainnet-beta</chain_id>
  <entry>
    <condition><immediate>true</immediate></condition>
    <action>
      <sell>
        <relative><percentage>50.0</percentage></relative>
        <quote>So11111111111111111111111111111111111111112</quote>
        <base>EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v</base>
      </sell>
    </action>
  </entry>
</intent>
```

### IMMEDIATE — buy with exit strategy

```xml theme={null}
<intent>
  <type>IMMEDIATE</type>
  <chain_id>solana:mainnet-beta</chain_id>
  <entry>
    <condition><immediate>true</immediate></condition>
    <action>
      <buy>
        <amount>1</amount>
        <quote>EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v</quote>
        <base>trump</base>
      </buy>
    </action>
  </entry>
  <exit>
    <conditions>
      <profit_percent>10</profit_percent>
      <loss_percent>5</loss_percent>
    </conditions>
    <logic>OR</logic>
  </exit>
</intent>
```

### CONDITIONAL\_ENTRY — event-triggered buy

Register a rule that triggers when PumpFun posts a bullish signal:

```xml theme={null}
<intent>
  <type>CONDITIONAL_ENTRY</type>
  <chain_id>solana:mainnet-beta</chain_id>
  <entry>
    <condition>
      <event_trigger>
        <event_type>token_listing</event_type>
        <exchange>PUMPFUN</exchange>
        <sub_event_type>PUMPFUN_BULLISH</sub_event_type>
      </event_trigger>
    </condition>
    <action>
      <buy>
        <budget_aiusd>10</budget_aiusd>
        <base_from_event>contract_address</base_from_event>
      </buy>
    </action>
  </entry>
  <exit>
    <conditions>
      <profit_percent>50</profit_percent>
      <loss_percent>30</loss_percent>
    </conditions>
    <logic>OR</logic>
  </exit>
</intent>
```

For `CONDITIONAL_ENTRY`, the buy action uses:

* `<budget_aiusd>` — amount in AIUSD to spend per matching event
* `<base_from_event>` — must be `contract_address` (token resolved from the event)

The response includes a `rule_id`. The rule stays active and triggers on each matching event until cancelled.

### CLOSE\_POSITION — close by position ID

```xml theme={null}
<intent>
  <type>CLOSE_POSITION</type>
  <chain_id>solana:mainnet-beta</chain_id>
  <position_id>pos_abc123</position_id>
</intent>
```

The response includes `cancelled_orders` (any exit orders that were removed) and `realized_pnl`.

## Token addressing

Follow this priority order when specifying tokens:

1. **Contract address provided** — use it directly
2. **Common tokens** — use the known addresses from the table below
3. **Other tokens** — use the symbol (e.g., `trump`, `JUP`). TIM resolves it automatically.

### Common token addresses

| Chain    | Native                                        | USDC                                           | USDT                                           |
| -------- | --------------------------------------------- | ---------------------------------------------- | ---------------------------------------------- |
| Solana   | `So11111111111111111111111111111111111111112` | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | `Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB` |
| Ethereum | `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`  | `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`   | `0xdAC17F958D2ee523a2206206994597C13D831ec7`   |
| BSC      | `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`  | `0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d`   | `0x55d398326f99059fF775485246999027B3197955`   |
| Base     | `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`  | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`   | —                                              |
| Arbitrum | `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`  | `0xaf88d065e77c8cC2239327C5EDb3A432268e5831`   | `0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9`   |

Amounts are always in human-readable decimal format (e.g., `0.170324`), not raw smallest-unit integers.

## CAIP-2 chain IDs

| Chain    | ID                    |
| -------- | --------------------- |
| Solana   | `solana:mainnet-beta` |
| Ethereum | `eip155:1`            |
| BSC      | `eip155:56`           |
| Base     | `eip155:8453`         |
| Arbitrum | `eip155:42161`        |

## AIUSD trading rules

* **Buy AIUSD:** use a `<sell>` action with `<quote>AIUSD</quote>`. Any token can be sold for AIUSD.
* **Sell AIUSD:** use a `<buy>` action with `<quote>AIUSD</quote>`. The base token must be a stablecoin: USDC, USDT, or USD1.

To buy non-stablecoins with AIUSD, run two intents:

1. Convert AIUSD to USDC (`<buy>` with `<quote>AIUSD</quote>` and `<base>` = USDC address)
2. Swap USDC for the target token (`<buy>` with `<quote>` = USDC address)

### Buy AIUSD (sell a token to get AIUSD)

```xml theme={null}
<intent>
  <type>IMMEDIATE</type>
  <chain_id>solana:mainnet-beta</chain_id>
  <entry>
    <condition><immediate>true</immediate></condition>
    <action>
      <sell>
        <amount>100</amount>
        <quote>AIUSD</quote>
        <base>trump</base>
      </sell>
    </action>
  </entry>
</intent>
```

### Sell AIUSD for USDC

```xml theme={null}
<intent>
  <type>IMMEDIATE</type>
  <chain_id>solana:mainnet-beta</chain_id>
  <entry>
    <condition><immediate>true</immediate></condition>
    <action>
      <buy>
        <amount>100</amount>
        <quote>AIUSD</quote>
        <base>EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v</base>
      </buy>
    </action>
  </entry>
</intent>
```


# Trading API overview
Source: https://docs.aiusd.ai/trading-api/overview

How TIM (Trading Intent Model) powers trading execution across chains and venues.

## What is TIM

The Trading API is built on TIM (Trading Intent Model) — a protocol for expressing trading strategies as structured intents. You submit an intent, and TIM validates it, resolves tokens, and executes the trade on-chain.

A single tool call (`execute_intent`) covers all trading operations: immediate swaps, event-triggered rules, exit strategies, and position management.

## Intent types

TIM supports three intent types:

| Type                | Behavior                                                          |
| ------------------- | ----------------------------------------------------------------- |
| `IMMEDIATE`         | Execute an on-chain swap now                                      |
| `CONDITIONAL_ENTRY` | Register an event-triggered rule that fires when conditions match |
| `CLOSE_POSITION`    | Close an existing position by `position_id`                       |

`IMMEDIATE` intents execute and return a transaction hash. `CONDITIONAL_ENTRY` intents register a rule and return a `rule_id` — the rule stays active and triggers on each matching event until cancelled. `CLOSE_POSITION` cancels exit orders and returns realized PnL.

## Supported chains

TIM uses [CAIP-2](https://chainagnostic.org/CAIPs/caip-2) chain identifiers:

| Chain    | CAIP-2 ID             |
| -------- | --------------------- |
| Solana   | `solana:mainnet-beta` |
| Ethereum | `eip155:1`            |
| BSC      | `eip155:56`           |
| Base     | `eip155:8453`         |
| Arbitrum | `eip155:42161`        |

## Supported DEXes

**Solana:** Jupiter, Raydium, PumpFun, Orca, Meteora DLMM, Bonk Launchpad

**EVM (via RelayerRouter):** Uniswap, Aerodrome, Sushiswap

TIM selects the best route automatically based on liquidity and price impact.

## Exit strategies

You can attach take-profit and stop-loss conditions to any `IMMEDIATE` buy intent:

* `profit_percent` — sell when PnL reaches +X%
* `loss_percent` — sell when PnL reaches -X%
* Combine with `OR` logic (either condition triggers) or `AND` logic (both must be true)

When an exit strategy is configured, TIM creates a tracked position and monitors it until an exit condition fires or you close it manually.

## Token resolution

TIM has built-in symbol-to-address resolution. You do not need to look up contract addresses before submitting intents:

1. If you provide a contract address, TIM uses it directly
2. For common tokens (SOL, USDC, USDT, ETH, BNB), TIM uses known addresses
3. For other tokens, provide the symbol and TIM resolves it

You can also use the [`GET /api/v1/tokens/resolve`](/trading-api/api#get-apiv1tokensresolve) endpoint to resolve tokens explicitly.

## AIUSD integration

TIM connects to the AIUSD ledger for funding. When you trade using your AIUSD balance, the platform moves funds from the ledger into your trading account before execution. See the [architecture page](/architecture) for how this flow works.

<Note>
  AIUSD can only be converted to stablecoins (USDC, USDT, USD1). To buy non-stablecoins with AIUSD, first convert AIUSD to USDC, then swap USDC for the target token.
</Note>

## How it fits together

```mermaid theme={null}
flowchart LR
    U[User or AI agent] --> MCP[MCP Hub]
    U --> HTTP[HTTP API]
    MCP --> TIM[TIM]
    HTTP --> TIM
    TIM --> SOL[Solana DEXes]
    TIM --> EVM[EVM DEXes]
```

You can reach TIM through two paths:

* **MCP Hub** — call `genalpha_tim_execute_intent` via the [MCP Hub API](/api). Best for AI agents using MCP tool calling.
* **HTTP API** — call `POST /api/v1/execute-intent` directly. Best for custom integrations and programmatic access.

Both paths accept the same XML intent format and return the same response structure.

## Next steps

<CardGroup>
  <Card title="Intent format" icon="code" href="/trading-api/intent-format">
    XML schema, intent types, buy/sell semantics, and examples
  </Card>

  <Card title="HTTP API reference" icon="server" href="/trading-api/api">
    Endpoints, authentication, request/response schemas
  </Card>
</CardGroup>