# Agent integration — $AI / AiCurve on HyperEVM

For AI agents and scripts that want to buy or sell `$AI` on-chain without the
web UI. Read `llms.txt` first for the one-paragraph summary.

**No private key is ever read, requested, or used by this server.** Every
"build tx" call below returns an **unsigned** transaction object; you sign it
with your own key and send it yourself (via `eth_sendTransaction` on your own
node/wallet, `cast send --private-key ...`, or any signer you control).

Disclosure carried on every response from this rail: *"Upgradeable
contracts; sells pay the on-chain sell fee; no guaranteed return."* Both
contracts sit behind UUPS proxies and their owner can upgrade the
implementation — that reaches pricing and the reserve. There is no DEX pool
for `$AI`; the curve is the only market.

## Facts

| | |
|---|---|
| Chain | HyperEVM, chain id `999` (`0x3e7`) |
| RPC | `https://rpc.hyperliquid.xyz/evm` |
| Token ($AI, ERC20, 18 decimals) | `0xe6f72e8eec40b863a5104ffa22e61076a4bd3b63` |
| Curve (`AiCurve`) | `0xe94bc8d4257a8bf3d37ffeca23b03d012aa58c4f` |
| Curve owner (upgrade authority) | `0x5062ac59f6df4498eeb45567855c554c475877ba` |
| Buy fee | 0% |
| Sell fee | 5% of gross HYPE, read live via `sellFeeBps()` — never assume it is fixed |

## ABI fragments used by the rail

```
function buy(uint256 minTokensOut) external payable returns (uint256 tokensOut)         // 0xd96a094a
function sell(uint256 tokensIn, uint256 minHypeOut) external returns (uint256 hypeOut)   // 0xd79875eb
function quoteBuy(uint256 hypeIn) external view returns (uint256 tokensOut)              // 0x4beb394c
function quoteSell(uint256 tokensIn) external view returns (uint256 hypeOut)             // 0xa64190c4
function currentPrice() external view returns (uint256 priceWad)                        // 0x9d1b464a
function sold() external view returns (uint256)                                         // 0x02c7e7af
function supply() external view returns (uint256)                                       // 0x047fc9aa
function retired() external view returns (uint256)                                      // 0x2eb38ae0
function circulating() external view returns (uint256)                                  // 0xf8718858
function sellFeeBps() external pure returns (uint256)                                    // 0x23cbe1f3

function approve(address spender, uint256 value) external returns (bool)                // 0x095ea7b3 (on the token)
function allowance(address owner, address spender) external view returns (uint256)      // 0xdd62ed3e (on the token)
```

Full surface and event topics: `INTEGRATION-CURVE.md`.

## MCP over Streamable HTTP

`POST https://thetickeris.ai/mcp`, JSON-RPC 2.0, stateless (one JSON response
per request, no session id). Standard lifecycle:
`initialize` → `notifications/initialized` → `tools/list` / `tools/call`.
`ping` always answered.

Tools:

- `ai_market` — no arguments. Returns price, sold, retired, circulating,
  reserve, supply, `sellFeeBps`, contracts, chain id, rpc, disclosure.
- `ai_quote_buy { hype }` — decimal string, max `10000`. Returns `tokensOut`.
- `ai_quote_sell { ai }` — decimal string, max `1000000000`. Returns `hypeOut`
  (net of the sell fee).
- `ai_build_buy_tx { hype, slippage_bps?, from? }` — returns
  `{ tx: { chainId, to, value, data, gas? }, quote }`. `gas` is only present
  when `from` is given (an `eth_estimateGas` call needs a sender).
- `ai_build_sell_tx { ai, from, slippage_bps? }` — `from` is required (used
  for the allowance check and the gas estimate). Returns
  `{ steps: [{ step: "approve", tx }?, { step: "sell", tx }], quote }`. The
  `approve` step is only included when your current allowance to the curve
  is below the amount you are selling.

`slippage_bps` is 0-5000 (0-50%), default `200` (2%).

### curl — read-only

```sh
curl -s https://thetickeris.ai/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0.0"}}}'

curl -s https://thetickeris.ai/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ai_market","arguments":{}}}'

curl -s https://thetickeris.ai/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"ai_quote_buy","arguments":{"hype":"1.5"}}}'
```

### curl — build an unsigned buy, then send it yourself

```sh
curl -s https://thetickeris.ai/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"ai_build_buy_tx","arguments":{"hype":"1.5","from":"0xYOUR_ADDRESS"}}}'
# -> {"tx":{"chainId":"0x3e7","to":"0xe94b...","value":"0x14d1120d7b160000","data":"0xd96a094a...","gas":"0x..."}, ...}

cast send 0xe94bc8d4257a8bf3d37ffeca23b03d012aa58c4f \
  --rpc-url https://rpc.hyperliquid.xyz/evm --private-key "$YOUR_KEY" \
  --value 1.5ether "buy(uint256)" <minTokensOut from the quote>
```

### curl — sell (approve step first if needed)

```sh
curl -s https://thetickeris.ai/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"ai_build_sell_tx","arguments":{"ai":"1000","from":"0xYOUR_ADDRESS"}}}'

# if the response includes an "approve" step:
cast send 0xe6f72e8eec40b863a5104ffa22e61076a4bd3b63 \
  --rpc-url https://rpc.hyperliquid.xyz/evm --private-key "$YOUR_KEY" \
  "approve(address,uint256)" 0xe94bc8d4257a8bf3d37ffeca23b03d012aa58c4f 1000000000000000000000

# always the "sell" step:
cast send 0xe94bc8d4257a8bf3d37ffeca23b03d012aa58c4f \
  --rpc-url https://rpc.hyperliquid.xyz/evm --private-key "$YOUR_KEY" \
  "sell(uint256,uint256)" 1000000000000000000000 <minHypeOut from the quote>
```

## JSON mirror (same data, plain HTTP GET)

```sh
curl -s https://thetickeris.ai/api/agent/market
curl -s 'https://thetickeris.ai/api/agent/quote?side=buy&amount=1.5'
curl -s 'https://thetickeris.ai/api/agent/quote?side=sell&amount=1000'
curl -s 'https://thetickeris.ai/api/agent/tx?side=buy&amount=1.5&from=0xYOUR_ADDRESS&slippage_bps=200'
curl -s 'https://thetickeris.ai/api/agent/tx?side=sell&amount=1000&from=0xYOUR_ADDRESS'
```

## Limits

- Amounts are decimal strings, positive, at most 18 decimal places, capped at
  `10000` HYPE per buy and `1000000000` ($AI's entire fixed supply) per sell.
- `slippage_bps` is an integer 0-5000.
- Addresses are `0x` + 40 hex chars.
- Requests are rate-limited per client IP.
- A bad request returns a `400`/`-32602`; an upstream RPC failure returns a
  `502` (JSON mirror) or a `tools/call` result with `isError: true` (MCP) —
  never a silent wrong answer.