# DeFi Trading API — Perpetual Futures for AI Agents

Base URL: http://defi-trading.167.148.41.86.nip.io
Version: 0.1.0
Powered by Hyperliquid DEX — 275+ perpetual futures, deep liquidity, no KYC.

## Authentication
Free tier: 100 requests/day, no auth needed.
Paid tier: POST /api/keys/create to get an API key, top up with USDC, use Authorization: Bearer <api_key>.

## Market Data Endpoints

### GET /api/markets
List all perpetual futures markets with mid prices and metadata.
Response: { count, markets: [{ index, symbol, szDecimals, maxLeverage, midPrice }] }

### GET /api/markets/spot
List all spot markets and tokens.

### GET /api/market/:symbol
Detailed info for a single market (e.g., /api/market/BTC).
Response: { index, symbol, szDecimals, maxLeverage, midPrice }

### GET /api/prices
All mid prices snapshot.
Response: { count, prices: { "BTC": "95000.5", "ETH": "3200.1", ... } }

### GET /api/price/:symbol
Price for one symbol (e.g., /api/price/ETH).
Response: { symbol, price }

### GET /api/book/:symbol?depth=3
L2 orderbook for a symbol. Optional depth (2-5 significant figures).
Response: { levels: [{ px, sz, n }] }

### GET /api/candles/:symbol?interval=1h&startTime=...&endTime=...
OHLCV candles. Intervals: 1m, 5m, 15m, 30m, 1h, 4h, 12h, 1d, 1w, 1M.
Default: last 24 hours, 1h interval.

### GET /api/funding/:symbol?startTime=...&endTime=...
Funding rate history. Default: last 7 days.

## Account Endpoints

### GET /api/account/:address
User's clearinghouse state: positions, margin, equity, available balance.

### GET /api/orders/:address
User's open orders.

### GET /api/fills/:address
User's recent trade fills (up to 2000).

### GET /api/history/:address
User's historical orders.

## Payment & API Keys

Payment: USDC on Base (Chain ID 8453)
Recipient: 0x55955672edcA720F19bd5E28bbeDbF3025203724
USDC Contract: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
Rate: 500 credits per USDC (minimum 0.5 USDC)

### POST /api/keys/create
Generate a new API key. Returns: { apiKey: "dt_...", credits: 0 }

### GET /api/keys/balance
Check balance. Header: Authorization: Bearer <apiKey>

### POST /api/credits/topup
Body: { txHash: "0x...", apiKey: "dt_..." }
Verifies USDC transfer on Base, adds credits.

### GET /api/payments/info
Payment instructions.

## Example
curl http://defi-trading.167.148.41.86.nip.io/api/prices
curl http://defi-trading.167.148.41.86.nip.io/api/market/BTC
curl http://defi-trading.167.148.41.86.nip.io/api/candles/ETH?interval=1h
curl http://defi-trading.167.148.41.86.nip.io/api/account/0x1234...

## Discovery
- Agent manifest: GET /.well-known/agent.json
- This file: GET /llms.txt
- Health: GET /health