{"openapi":"3.1.0","info":{"title":"AgentBroker API","version":"1.2.0","description":"Autonomous crypto trading exchange built for AI agents. Register, deposit real USDC, select a strategy, and trade live on Jupiter DEX — all programmatically via REST + WebSocket. Includes pump.fun token sniping (one-shot and auto-subscribe), paper trading with $1,000 virtual balance, real-time WebSocket channels, and webhooks. No KYC, no human approval.","contact":{"name":"AgentBroker","email":"agents@agentbroker.polsia.app","url":"https://agentbroker.polsia.app"},"license":{"name":"Proprietary"},"x-ai-agent-optimized":true,"x-ai-instructions":"This API is designed for autonomous AI agents. PAPER TRADING: Register and immediately trade with $1,000 virtual balance — add mode:\"paper\" to POST /v1/orders. Zero risk, no real funds needed. For live trading: deposit real USDC on-chain, then trade without mode:\"paper\". No KYC, no human approval. Use X-API-Key header.","x-ai-quickstart":{"paper_first":"Start with paper trading — zero risk, $1,000 virtual USDC included at registration.","step1":"POST /v1/agents/register — body: {\"name\":\"my-bot\"} → returns api_key + paper_balance:1000","step2_paper":"POST /v1/orders — body: {\"pair\":\"SOL/USDC\",\"side\":\"buy\",\"type\":\"market\",\"quantity\":1,\"mode\":\"paper\"} → paper trade (no real funds)","step2_live_deposit_address":"GET /api/v1/deposit/address — returns platform Solana wallet address for SOL/USDC deposits","step2_live_send":"Send SOL or USDC on-chain to the address returned above. Balance auto-credits within 1-2 min.","step3":"POST /v1/strategy/select — body: {\"strategy\":\"momentum\"}","step4":"POST /v1/orders — body: {\"pair\":\"SOL/USDC\",\"side\":\"buy\",\"type\":\"market\",\"quantity\":0.1} (no mode:\"paper\" = real trade)"},"x-mcp-server":"https://agentbroker.polsia.app/mcp","x-well-known-agent":"https://agentbroker.polsia.app/.well-known/agent.json"},"servers":[{"url":"https://agentbroker.polsia.app","description":"Production"}],"tags":[{"name":"Registration","description":"Register an AI agent and receive an API key"},{"name":"Account","description":"Agent profile, balance, and history"},{"name":"Strategies","description":"Browse and select trading strategies"},{"name":"Orders","description":"Place, list, and cancel limit/market orders"},{"name":"Trades","description":"Executed trade history"},{"name":"Funding","description":"Deposits and withdrawals"},{"name":"Market Data","description":"Live prices, order book, candles, and stats (no auth required)"},{"name":"Portfolio","description":"Portfolio value, holdings, P&L, and position tracking"},{"name":"Positions","description":"Active open positions with unrealized P&L"},{"name":"Wallets","description":"Multi-chain deposit wallet addresses"},{"name":"Keys","description":"API key management — create, list, revoke standalone keys"},{"name":"Tokens","description":"New token discovery, pump.fun launches, and token sniping (one-shot + auto-subscribe)"},{"name":"System","description":"Health, status, fee schedule, and webhook management"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Agent API key returned at registration. Format: ab_sk_..."}},"schemas":{"Agent":{"type":"object","properties":{"agent_id":{"type":"integer","example":42},"name":{"type":"string","example":"my-trading-bot"},"owner_email":{"type":["string","null"],"format":"email"},"callback_url":{"type":["string","null"],"format":"uri"},"preferred_pairs":{"type":"array","items":{"type":"string"},"example":["BTC/USDC"]},"balance_usdc":{"type":"string","example":"1000.000000"},"strategy":{"oneOf":[{"type":"null"},{"type":"object","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"description":{"type":"string"},"selected_at":{"type":"string","format":"date-time"}}}]},"trade_count":{"type":"integer","example":0},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Order":{"type":"object","properties":{"order_id":{"type":"integer"},"agent_id":{"type":"integer"},"pair":{"type":"string","example":"BTC/USDC"},"side":{"type":"string","enum":["buy","sell"]},"type":{"type":"string","enum":["limit","market"]},"quantity":{"type":"string","example":"0.10000000"},"price":{"type":["string","null"],"example":"42000.000000"},"filled_quantity":{"type":"string","example":"0.10000000"},"status":{"type":"string","enum":["open","partially_filled","filled","cancelled"]},"fee_tier":{"type":"string","enum":["base","high_volume"]},"fee_rate_pct":{"type":"string","example":"0.40%"},"balance_usdc":{"type":"string","example":"995.800000"},"fills":{"type":"array","items":{"type":"object","properties":{"fill_price":{"type":"string"},"fill_quantity":{"type":"string"},"fill_value_usdc":{"type":"string"},"fee_usdc":{"type":"string"},"fee_tier":{"type":"string"},"fee_rate_pct":{"type":"string"},"trade_id":{"type":"integer"}}}},"created_at":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"error":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string"}}}}},"paths":{"/v1/agents/register":{"post":{"operationId":"registerAgent","tags":["Registration"],"summary":"Register a new AI agent","description":"Creates a new live agent account and returns a one-time API key. Deposit real funds to start trading. Also available at /api/v1/agents/register.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100,"example":"alpha-bot-v2"},"owner_email":{"type":"string","format":"email","example":"you@example.com"},"callback_url":{"type":"string","format":"uri","example":"https://yourbot.example.com/webhook"},"preferred_pairs":{"type":"array","items":{"type":"string","enum":["BTC/USDC","ETH/USDC","SOL/USDC","AVAX/USDC","LINK/USDC","DOGE/USDC","ARB/USDC","MATIC/USDC"]},"example":["BTC/USDC"]}}},"examples":{"live":{"summary":"Register live agent","value":{"name":"my-trading-bot"}}}}}},"responses":{"201":{"description":"Agent registered — save api_key immediately, cannot be retrieved again.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Agent"},{"type":"object","required":["api_key"],"properties":{"api_key":{"type":"string","example":"ab_sk_9f3k..."},"_note":{"type":"string"}}}]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agents/register":{"post":{"operationId":"registerAgentCanonical","tags":["Registration"],"summary":"Register a new AI agent (canonical versioned path)","description":"Identical to POST /v1/agents/register.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"my-bot"},"owner_email":{"type":"string","format":"email"},"callback_url":{"type":"string","format":"uri"},"preferred_pairs":{"type":"array","items":{"type":"string","enum":["BTC/USDC","ETH/USDC","SOL/USDC","AVAX/USDC","LINK/USDC","DOGE/USDC","ARB/USDC","MATIC/USDC"]}}}}}}},"responses":{"201":{"description":"Agent registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"400":{"description":"Validation error"}}}},"/api/v1/agents/me":{"get":{"operationId":"getAgentProfile","tags":["Account"],"summary":"Get agent profile","description":"Returns current agent profile: balance, active strategy, trade count.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Agent profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Agent not found"}}},"put":{"operationId":"updateAgentProfile","tags":["Account"],"summary":"Update agent profile","description":"Update callback_url and/or preferred_pairs. At least one field required.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"callback_url":{"type":["string","null"],"format":"uri","description":"Set null to clear"},"preferred_pairs":{"type":"array","items":{"type":"string","enum":["BTC/USDC","ETH/USDC","SOL/USDC","AVAX/USDC","LINK/USDC","DOGE/USDC","ARB/USDC","MATIC/USDC"]}}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"}}}},"/v1/account":{"get":{"operationId":"getAccount","tags":["Account"],"summary":"Get account summary","description":"Returns balance, active strategy, total deposited, and total trade count.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Account summary","content":{"application/json":{"schema":{"type":"object","properties":{"agent_id":{"type":"integer"},"name":{"type":"string"},"balance_usdc":{"type":"string","example":"9842.500000"},"strategy":{"type":["object","null"]},"total_deposited":{"type":"string"},"total_trades":{"type":"integer"}}}}}},"401":{"description":"Unauthorized"}}}},"/v1/strategies":{"get":{"operationId":"listStrategies","tags":["Strategies"],"summary":"List available trading strategies","responses":{"200":{"description":"Strategy list","content":{"application/json":{"schema":{"type":"object","properties":{"strategies":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["momentum","grid","mean_reversion"]},"display_name":{"type":"string"},"description":{"type":"string"},"parameters":{"type":"object"}}}}}}}}}}}},"/v1/strategy/select":{"post":{"operationId":"selectStrategy","tags":["Strategies"],"summary":"Select a trading strategy","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["strategy"],"properties":{"strategy":{"type":"string","enum":["momentum","grid","mean_reversion"],"example":"momentum"}}}}}},"responses":{"200":{"description":"Strategy selected","content":{"application/json":{"schema":{"type":"object","properties":{"agent_id":{"type":"integer"},"strategy":{"type":"string"},"display_name":{"type":"string"},"description":{"type":"string"},"selected_at":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Invalid strategy"},"401":{"description":"Unauthorized"}}}},"/v1/orders":{"post":{"operationId":"placeOrder","tags":["Orders"],"summary":"Place a limit or market order","description":"Places an order against the live order book. Market orders fill immediately; limit orders rest until matched. Returns fills and updated balance.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["pair","side","type","quantity"],"properties":{"pair":{"type":"string","enum":["BTC/USDC","ETH/USDC","SOL/USDC","AVAX/USDC","LINK/USDC","DOGE/USDC","ARB/USDC","MATIC/USDC"],"example":"SOL/USDC"},"side":{"type":"string","enum":["buy","sell"],"example":"buy"},"type":{"type":"string","enum":["limit","market","stop_loss","stop_limit","trailing_stop","oco"],"example":"market"},"quantity":{"type":"number","exclusiveMinimum":0,"example":1},"price":{"type":"number","exclusiveMinimum":0,"example":150,"description":"Required for limit/stop_limit orders"},"mode":{"type":"string","enum":["paper"],"description":"Set to \"paper\" for risk-free paper trading with virtual $1,000 balance. Omit for live trading."}}},"examples":{"market_buy":{"summary":"Market buy 1 SOL (live)","value":{"pair":"SOL/USDC","side":"buy","type":"market","quantity":1}},"paper_trade":{"summary":"Paper trade (no real funds)","value":{"pair":"SOL/USDC","side":"buy","type":"market","quantity":1,"mode":"paper"}},"limit_sell":{"summary":"Limit sell 0.5 ETH at $3500","value":{"pair":"ETH/USDC","side":"sell","type":"limit","quantity":0.5,"price":3500}}}}}},"responses":{"201":{"description":"Order placed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"400":{"description":"Validation error or insufficient balance"},"401":{"description":"Unauthorized"}}},"get":{"operationId":"listOrders","tags":["Orders"],"summary":"List orders","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["open","partially_filled","filled","cancelled","all"],"default":"open"},"description":"open returns open+partially_filled. all returns everything."}],"responses":{"200":{"description":"Order list","content":{"application/json":{"schema":{"type":"object","properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"count":{"type":"integer"}}}}}},"401":{"description":"Unauthorized"}}}},"/v1/orders/{id}":{"delete":{"operationId":"cancelOrder","tags":["Orders"],"summary":"Cancel an open order","description":"Cancels open or partially-filled order. Refunds reserved USDC proportional to unfilled quantity.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","example":7}}],"responses":{"200":{"description":"Order cancelled","content":{"application/json":{"schema":{"type":"object","properties":{"order_id":{"type":"integer"},"status":{"type":"string","example":"cancelled"},"filled_quantity":{"type":"string"},"refunded_usdc":{"type":"string"},"balance_usdc":{"type":"string"}}}}}},"400":{"description":"Cannot cancel"},"401":{"description":"Unauthorized"},"404":{"description":"Not found"}}}},"/v1/orderbook/{pair}":{"get":{"operationId":"getOrderBook","tags":["Market Data"],"summary":"Get order book for a pair","description":"Top 10 bids and asks plus market price and spread. Requires API key.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"pair","in":"path","required":true,"schema":{"type":"string","enum":["BTC/USDC","ETH/USDC","SOL/USDC","AVAX/USDC","LINK/USDC","DOGE/USDC","ARB/USDC","MATIC/USDC"],"example":"BTC/USDC"}}],"responses":{"200":{"description":"Order book","content":{"application/json":{"schema":{"type":"object","properties":{"pair":{"type":"string"},"market_price":{"type":"string"},"spread":{"type":["string","null"]},"bids":{"type":"array","items":{"type":"object","properties":{"price":{"type":"string"},"quantity":{"type":"string"},"orders":{"type":"integer"}}}},"asks":{"type":"array","items":{"type":"object","properties":{"price":{"type":"string"},"quantity":{"type":"string"},"orders":{"type":"integer"}}}},"timestamp":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Unsupported pair"},"401":{"description":"Unauthorized"}}}},"/v1/trades":{"get":{"operationId":"listTrades","tags":["Trades"],"summary":"List trade history","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Trade list","content":{"application/json":{"schema":{"type":"object","properties":{"trades":{"type":"array","items":{"type":"object","properties":{"trade_id":{"type":"integer"},"pair":{"type":"string"},"side":{"type":"string","enum":["buy","sell"]},"quantity":{"type":"string"},"market_price":{"type":"string"},"fill_price":{"type":"string"},"fee_usdc":{"type":"string"},"total_usdc":{"type":"string"},"status":{"type":"string"},"strategy":{"type":["string","null"]},"executed_at":{"type":"string","format":"date-time"}}}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}},"401":{"description":"Unauthorized"}}}},"/v1/deposit/address":{"get":{"operationId":"getDepositAddress","tags":["Funding"],"summary":"Get platform deposit wallet address","description":"Returns the Solana wallet address where agents should send SOL or USDC to fund their account. Always call this endpoint to get the current address — do not hardcode it.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Deposit address","content":{"application/json":{"schema":{"type":"object","properties":{"solana":{"type":"object","properties":{"address":{"type":"string","example":"AbcDef123..."},"supported_tokens":{"type":"array","items":{"type":"string"},"example":["SOL","USDC"]},"min_deposit":{"type":"string","example":"0.01"},"note":{"type":"string"},"explorer":{"type":"string"}}},"instructions":{"type":"array","items":{"type":"string"}}}}}}},"401":{"description":"Unauthorized"},"503":{"description":"Wallet not configured"}}}},"/api/v1/deposit/address":{"get":{"operationId":"getDepositAddressCanonical","tags":["Funding"],"summary":"Get platform deposit wallet address (canonical)","description":"Canonical alias for GET /v1/deposit/address. Returns the Solana wallet address for on-chain SOL/USDC deposits.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Deposit address","content":{"application/json":{"schema":{"type":"object","properties":{"solana":{"type":"object","properties":{"address":{"type":"string"},"supported_tokens":{"type":"array","items":{"type":"string"}},"min_deposit":{"type":"string"},"note":{"type":"string"},"explorer":{"type":"string"}}},"instructions":{"type":"array","items":{"type":"string"}}}}}}},"401":{"description":"Unauthorized"},"503":{"description":"Wallet not configured"}}}},"/v1/deposit":{"post":{"operationId":"deposit","tags":["Funding"],"summary":"Deposit USDC","description":"Records a USDC deposit to agent balance. Provide the on-chain transaction hash after sending real funds to your deposit wallet address.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"number","exclusiveMinimum":0,"maximum":10000000,"example":1000},"tx_hash":{"type":"string","maxLength":100,"example":"0xabc123..."}}}}}},"responses":{"201":{"description":"Deposit recorded","content":{"application/json":{"schema":{"type":"object","properties":{"deposit_id":{"type":"integer"},"agent_id":{"type":"integer"},"amount_usdc":{"type":"string"},"tx_hash":{"type":["string","null"]},"status":{"type":"string","example":"confirmed"},"balance_usdc":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"}}}},"/v1/deposits":{"get":{"operationId":"listDeposits","tags":["Funding"],"summary":"List deposit history","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Deposit list","content":{"application/json":{"schema":{"type":"object","properties":{"deposits":{"type":"array","items":{"type":"object","properties":{"deposit_id":{"type":"integer"},"amount_usdc":{"type":"string"},"tx_hash":{"type":["string","null"]},"status":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}},"agent_id":{"type":"integer"}}}}}},"401":{"description":"Unauthorized"}}}},"/v1/withdraw":{"post":{"operationId":"withdraw","tags":["Funding"],"summary":"Request a withdrawal","description":"Queues a USDC withdrawal to an on-chain address. Minimum 1 USDC balance must remain after withdrawal.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","destination_address"],"properties":{"amount":{"type":"number","exclusiveMinimum":0,"example":500},"destination_address":{"type":"string","minLength":10,"example":"0x742d35Cc6634C0532925a3b844Bc454e4438f44e"}}}}}},"responses":{"200":{"description":"Withdrawal queued","content":{"application/json":{"schema":{"type":"object","properties":{"withdrawal_id":{"type":"integer"},"amount_usdc":{"type":"string"},"destination_address":{"type":"string"},"status":{"type":"string","example":"pending"},"balance_usdc":{"type":"number"},"message":{"type":"string"}}}}}},"400":{"description":"Insufficient balance or validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Unauthorized or insufficient balance"}}}},"/v1/withdrawals":{"get":{"operationId":"listWithdrawals","tags":["Funding"],"summary":"List withdrawal history","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","processing","completed","failed"]}}],"responses":{"200":{"description":"Withdrawal list","content":{"application/json":{"schema":{"type":"object","properties":{"withdrawals":{"type":"array","items":{"type":"object","properties":{"withdrawal_id":{"type":"integer"},"amount_usdc":{"type":"string"},"destination_address":{"type":"string"},"status":{"type":"string"},"tx_hash":{"type":["string","null"]},"note":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}},"401":{"description":"Unauthorized"}}}},"/v1/balance/history":{"get":{"operationId":"getBalanceHistory","tags":["Account"],"summary":"Get balance event history","description":"Unified timeline of deposits, trades, and withdrawals, newest first.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Balance history","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["deposit","trade","withdrawal"]},"reference_id":{"type":"integer"},"amount":{"type":"string"},"balance_delta":{"type":"string"},"pair":{"type":["string","null"]},"side":{"type":["string","null"]},"destination_address":{"type":["string","null"]},"status":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}},"total":{"type":"integer"},"current_balance_usdc":{"type":"number"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}},"401":{"description":"Unauthorized"}}}},"/v1/prices":{"get":{"operationId":"getAllPrices","tags":["Market Data"],"summary":"Get live prices for all pairs","description":"Real-time prices for all registered pairs (CoinGecko) plus any DexScreener-cached tokens. source field indicates data origin: \"coingecko\", \"dexscreener\", or \"fallback\".","responses":{"200":{"description":"All prices","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"prices":{"type":"array","items":{"type":"object","properties":{"pair":{"type":"string","example":"PEPE/USDC"},"name":{"type":"string"},"chain":{"type":"string"},"price_usdc":{"type":["number","null"]},"change_24h_pct":{"type":["number","null"]},"last_updated":{"type":["string","null"],"format":"date-time"},"source":{"type":"string","enum":["coingecko","dexscreener","fallback"]}}}},"count":{"type":"integer"}}}}}}}}},"/v1/prices/{pair}":{"get":{"operationId":"getPairPrice","tags":["Market Data"],"summary":"Get price for any token pair","description":"Live price for any pair — registered tokens use CoinGecko, unknown tokens are looked up via DexScreener in real-time. Accepts BTC-USDC, PEPE-USDC, BTC/USDC, or just BTC.","parameters":[{"name":"pair","in":"path","required":true,"schema":{"type":"string","example":"PEPE-USDC"},"description":"Symbol or pair. Use - or / as separator."}],"responses":{"200":{"description":"Token price","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"pair":{"type":"string"},"name":{"type":"string"},"chain":{"type":"string"},"price_usdc":{"type":["number","null"]},"change_24h_pct":{"type":["number","null"]},"liquidity_usd":{"type":["number","null"]},"volume_24h_usd":{"type":["number","null"]},"market_cap_usd":{"type":["number","null"]},"last_updated":{"type":["string","null"]},"source":{"type":"string","enum":["coingecko","dexscreener","fallback"]},"dex_url":{"type":["string","null"]}}}}}},"404":{"description":"Pair not found on DexScreener"},"502":{"description":"DexScreener lookup failed"}}}},"/v1/pairs/search":{"get":{"operationId":"searchPairs","tags":["Market Data"],"summary":"Search DexScreener for token pairs","description":"Search DexScreener for pairs matching a symbol, name, or contract address. Returns price, liquidity, volume, and chain info. Covers Solana (pump.fun, Raydium), Base, Ethereum, and all major chains.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","example":"PEPE"},"description":"Symbol, name, or contract address"},{"name":"chain","in":"query","required":false,"schema":{"type":"string","example":"solana"},"description":"Filter by chain (solana, ethereum, base, etc.)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"maximum":50},"description":"Max results"}],"responses":{"200":{"description":"Matching pairs","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"query":{"type":"string"},"count":{"type":"integer"},"pairs":{"type":"array","items":{"type":"object","properties":{"pair":{"type":"string","example":"PEPE/USDC"},"symbol":{"type":"string"},"name":{"type":"string"},"contract":{"type":"string"},"chain":{"type":"string"},"dex_id":{"type":"string"},"price_usdc":{"type":"number"},"change_24h_pct":{"type":"number"},"liquidity_usd":{"type":"number"},"volume_24h_usd":{"type":"number"},"market_cap_usd":{"type":"number"},"dex_url":{"type":"string"}}}}}}}}},"400":{"description":"Missing or invalid query"},"502":{"description":"DexScreener search failed"}}}},"/v1/pairs":{"get":{"operationId":"listPairs","tags":["Market Data"],"summary":"List all registered trading pairs with metadata","description":"All pairs in the CoinGecko registry. Use /v1/pairs/search?q= to discover any token pair.","responses":{"200":{"description":"Supported pairs","content":{"application/json":{"schema":{"type":"object","properties":{"pairs":{"type":"array","items":{"type":"object","properties":{"pair":{"type":"string","example":"BTC/USDC"},"price":{"type":"string"},"base_asset":{"type":"string"},"quote_asset":{"type":"string"},"chain":{"type":"string"},"logo_url":{"type":["string","null"]}}}}}}}}}}}},"/v1/fees":{"get":{"operationId":"getFees","tags":["System"],"summary":"Get fee schedule","description":"All fee tiers. Applied automatically by 30-day rolling volume — no enrollment needed.","responses":{"200":{"description":"Fee schedule","content":{"application/json":{"schema":{"type":"object","properties":{"fee_tiers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["base","high_volume"]},"fee_rate":{"type":"number","example":0.004},"fee_pct":{"type":"string","example":"0.40%"},"threshold_usdc_30d":{"type":["number","null"]},"description":{"type":"string"}}}},"notes":{"type":"array","items":{"type":"string"}},"example_order_fill":{"type":"object"}}}}}}}}},"/api/v1/status":{"get":{"operationId":"getStatus","tags":["System"],"summary":"Health and status check","description":"API version, uptime, database health, price feed status, and trading metrics.","responses":{"200":{"description":"System status","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["operational","partial","degraded"]},"version":{"type":"string","example":"1.1.0"},"uptime_seconds":{"type":"integer"},"timestamp":{"type":"string","format":"date-time"},"services":{"type":"object"},"metrics":{"type":"object","properties":{"total_agents":{"type":"integer"},"total_trades":{"type":"integer"},"supported_pairs":{"type":"integer"}}}}}}}}}}},"/v1/trade/execute":{"post":{"operationId":"executeTrade","tags":["Orders"],"summary":"DEPRECATED — Execute a market trade","description":"Deprecated. Use POST /v1/orders with type:market instead. Requires a strategy to be selected first.","deprecated":true,"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["pair","side","quantity"],"properties":{"pair":{"type":"string","enum":["BTC/USDC","ETH/USDC","SOL/USDC","AVAX/USDC","LINK/USDC","DOGE/USDC","ARB/USDC","MATIC/USDC"]},"side":{"type":"string","enum":["buy","sell"]},"quantity":{"type":"number","exclusiveMinimum":0}}}}}},"responses":{"201":{"description":"Trade executed"},"400":{"description":"Validation error, no strategy, or no liquidity"},"401":{"description":"Unauthorized"}}}},"/api/v1/wallets":{"get":{"operationId":"getWallets","tags":["Wallets"],"summary":"Get multi-chain deposit wallet addresses","description":"Returns unique on-chain deposit addresses for your agent (Ethereum, Solana, BNB Chain). Send real USDC to any address — balance updates within 1-2 minutes of on-chain confirmation.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Wallet addresses","content":{"application/json":{"schema":{"type":"object","properties":{"agent_id":{"type":"integer"},"wallets":{"type":"array","items":{"type":"object","properties":{"chain":{"type":"string","example":"ethereum"},"address":{"type":"string","example":"0x742d35Cc..."},"network":{"type":"string"},"coin":{"type":"string","example":"USDC"}}}},"note":{"type":"string"}}}}}},"401":{"description":"Unauthorized"},"503":{"description":"Wallet infrastructure not yet configured"}}}},"/api/v1/deposits":{"get":{"operationId":"listDepositsCanonical","tags":["Funding"],"summary":"List deposit history (canonical — includes on-chain data)","description":"Full deposit history with blockchain confirmation data, chain info, and confirmations count. Also available at /v1/deposits (legacy).","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["pending","confirming","confirmed"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Deposit list","content":{"application/json":{"schema":{"type":"object","properties":{"deposits":{"type":"array","items":{"type":"object","properties":{"deposit_id":{"type":"integer"},"amount_usdc":{"type":"string"},"tx_hash":{"type":["string","null"]},"chain":{"type":["string","null"]},"confirmations":{"type":["integer","null"]},"status":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}},"agent_id":{"type":"integer"}}}}}},"401":{"description":"Unauthorized"}}}},"/api/v1/portfolio":{"get":{"operationId":"getPortfolioCanonical","tags":["Portfolio"],"summary":"Get portfolio summary — total value, holdings, unrealized P&L","description":"Returns full portfolio: USDC balance, all crypto holdings with current prices, unrealized and realized P&L per asset, and total portfolio value. Also available at /v1/portfolio (legacy).","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Portfolio summary","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"portfolio":{"type":"object","properties":{"total_value_usdc":{"type":"number","example":10234.56},"usdc_balance":{"type":"number"},"holdings_value_usdc":{"type":"number"},"total_unrealized_pnl_usdc":{"type":"number"},"total_realized_pnl_net_usdc":{"type":"number"},"snapshot_at":{"type":"string","format":"date-time"},"holdings":{"type":"array","items":{"type":"object","properties":{"pair":{"type":"string","example":"BTC/USDC"},"quantity":{"type":"number"},"avg_entry_price":{"type":"number"},"current_price":{"type":"number"},"current_value_usdc":{"type":"number"},"unrealized_pnl_usdc":{"type":"number"},"unrealized_pnl_pct":{"type":"number"},"realized_pnl_net_usdc":{"type":"number"},"total_fees_usdc":{"type":"number"}}}}}}}}}}},"401":{"description":"Unauthorized"}}}},"/api/v1/portfolio/history":{"get":{"operationId":"getPortfolioHistoryCanonical","tags":["Portfolio"],"summary":"Get portfolio equity curve (time-series snapshots)","description":"Hourly portfolio snapshots for charting. Returns total_value_usdc, usdc_balance, and holdings_value over time. Also at /v1/portfolio/history.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"interval","in":"query","schema":{"type":"string","default":"1h","description":"Snapshot interval (informational)"}},{"name":"limit","in":"query","schema":{"type":"integer","default":168,"maximum":720,"description":"Number of snapshots to return (default 168 = 7 days of hourly)"}}],"responses":{"200":{"description":"Portfolio history","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"interval":{"type":"string"},"count":{"type":"integer"},"snapshots":{"type":"array","items":{"type":"object","properties":{"total_value_usdc":{"type":"number"},"usdc_balance":{"type":"number"},"holdings_value_usdc":{"type":"number"},"holdings":{"type":"array"},"recorded_at":{"type":"string","format":"date-time"}}}}}}}}},"401":{"description":"Unauthorized"}}}},"/api/v1/portfolio/pnl":{"get":{"operationId":"getPairPnlCanonical","tags":["Portfolio"],"summary":"Get P&L for a specific trading pair","description":"Detailed realized and unrealized P&L for one pair — avg entry price, quantity held, trade count, fee totals. Also at /v1/portfolio/pnl.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"pair","in":"query","required":true,"schema":{"type":"string","example":"SOL-USDC"},"description":"Pair to query (e.g. SOL-USDC or SOL/USDC)"}],"responses":{"200":{"description":"P&L data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"pair":{"type":"string"},"pnl":{"type":"object","properties":{"quantity_held":{"type":"number"},"avg_entry_price":{"type":["number","null"]},"current_price":{"type":"number"},"unrealized_pnl_usdc":{"type":"number"},"unrealized_pnl_pct":{"type":"number"},"realized_pnl_gross_usdc":{"type":"number"},"realized_pnl_net_usdc":{"type":"number"},"total_fees_usdc":{"type":"number"},"total_bought_qty":{"type":"number"},"total_sold_qty":{"type":"number"},"trade_count":{"type":"integer"}}}}}}}},"400":{"description":"pair param required"},"401":{"description":"Unauthorized"}}}},"/api/v1/positions":{"get":{"operationId":"getPositionsCanonical","tags":["Positions"],"summary":"Get all active open positions","description":"All currently held crypto positions with entry price, current price, unrealized P&L, and duration since entry. Also available at /v1/positions.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Open positions","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"count":{"type":"integer"},"positions":{"type":"array","items":{"type":"object","properties":{"pair":{"type":"string","example":"SOL/USDC"},"side":{"type":"string","example":"long"},"quantity":{"type":"number"},"avg_entry_price":{"type":"number"},"current_price":{"type":"number"},"current_value_usdc":{"type":"number"},"unrealized_pnl_usdc":{"type":"number"},"unrealized_pnl_pct":{"type":"number"},"total_fees_usdc":{"type":"number"},"entry_time":{"type":"string","format":"date-time"},"duration":{"type":"string","example":"14h"}}}}}}}}},"401":{"description":"Unauthorized"}}}},"/api/v1/candles":{"get":{"operationId":"getCandles","tags":["Market Data"],"security":[{"ApiKeyAuth":[]}],"summary":"Get OHLCV candle data for a pair","description":"Historical candlestick data (OHLCV) for charting. Data sourced from internal trade fills; falls back to CoinGecko for major pairs when local candles are unavailable. Returns oldest-first (standard for charting libs).","parameters":[{"name":"pair","in":"query","required":true,"schema":{"type":"string","example":"SOL-USDC"},"description":"Pair symbol, e.g. SOL-USDC or BTC/USDC"},{"name":"interval","in":"query","schema":{"type":"string","enum":["1m","5m","15m","1h","4h","1d"],"default":"1h"},"description":"Candle interval"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"default":500}}],"responses":{"200":{"description":"Candles","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"pair":{"type":"string"},"interval":{"type":"string"},"count":{"type":"integer"},"candles":{"type":"array","items":{"type":"object","properties":{"open_time":{"type":"string","format":"date-time"},"open":{"type":"number"},"high":{"type":"number"},"low":{"type":"number"},"close":{"type":"number"},"volume":{"type":"number"},"trade_count":{"type":"integer"},"source":{"type":"string","enum":["internal","coingecko"]}}}}}}}}},"400":{"description":"Missing or invalid pair/interval"},"401":{"description":"Unauthorized"}}}},"/api/v1/trades/history":{"get":{"operationId":"getPublicTradeHistory","tags":["Market Data"],"security":[{"ApiKeyAuth":[]}],"summary":"Trade history for a pair (requires API key)","description":"Recent anonymized fills across all agents for a given pair (or all pairs). Useful for understanding market activity. Requires API key.","parameters":[{"name":"pair","in":"query","schema":{"type":"string","example":"SOL-USDC"},"description":"Filter by pair (optional — omit for all pairs)"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}}],"responses":{"200":{"description":"Recent trades","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"pair":{"type":"string"},"count":{"type":"integer"},"trades":{"type":"array","items":{"type":"object","properties":{"pair":{"type":"string"},"side":{"type":"string","enum":["buy","sell"]},"price":{"type":"number"},"quantity":{"type":"number"},"timestamp":{"type":"string","format":"date-time"}}}}}}}}},"401":{"description":"Unauthorized"}}}},"/api/v1/pairs/{pair}/stats":{"get":{"operationId":"getPairStats","tags":["Market Data"],"security":[{"ApiKeyAuth":[]}],"summary":"Get 24h market stats for a trading pair","description":"24-hour market statistics: current price, open, high, low, volume, and price change %. Combines live price feed with internal trade aggregation.","parameters":[{"name":"pair","in":"path","required":true,"schema":{"type":"string","example":"BTC-USDC"},"description":"Pair, e.g. BTC-USDC or BTC/USDC"}],"responses":{"200":{"description":"24h stats","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"pair":{"type":"string"},"current_price":{"type":["number","null"]},"open_24h":{"type":["number","null"]},"high_24h":{"type":["number","null"]},"low_24h":{"type":["number","null"]},"close_24h":{"type":["number","null"]},"volume_24h_usdc":{"type":"number"},"change_24h_pct":{"type":["number","null"]},"trade_count_24h":{"type":"integer"},"data_sources":{"type":"object"},"generated_at":{"type":"string","format":"date-time"}}}}}},"401":{"description":"Unauthorized"}}}},"/api/v1/tokens/new":{"get":{"operationId":"getNewTokensCanonical","tags":["Tokens"],"security":[{"ApiKeyAuth":[]}],"summary":"Discover newly launched tokens (pump.fun / DexScreener)","description":"Real-time feed of new token launches from pump.fun and DexScreener. Filter by min liquidity, hours since launch, chain, and graduated status. Useful for token discovery and sniping strategies. Also at /v1/tokens/new.","parameters":[{"name":"hours","in":"query","schema":{"type":"integer","default":1,"maximum":168},"description":"Tokens launched within last N hours"},{"name":"min_liquidity","in":"query","schema":{"type":"number","default":0},"description":"Minimum liquidity in USD"},{"name":"chain","in":"query","schema":{"type":"string","example":"solana"},"description":"Filter by chain (solana, ethereum, base, etc.)"},{"name":"graduated","in":"query","schema":{"type":"boolean"},"description":"Filter pump.fun graduated tokens only"},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}}],"responses":{"200":{"description":"New tokens","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"count":{"type":"integer"},"tokens":{"type":"array","items":{"type":"object","properties":{"pair":{"type":"string"},"name":{"type":"string"},"symbol":{"type":"string"},"chain":{"type":"string"},"contract":{"type":"string"},"price_usdc":{"type":"number"},"liquidity_usd":{"type":"number"},"volume_24h_usd":{"type":"number"},"market_cap_usd":{"type":["number","null"]},"created_at":{"type":["string","null"],"format":"date-time"},"graduated":{"type":["boolean","null"]},"dex_url":{"type":"string"}}}},"filters":{"type":"object"},"generated_at":{"type":"string","format":"date-time"}}}}}},"401":{"description":"Unauthorized"}}}},"/v1/tokens/{mint}/analytics":{"get":{"operationId":"getTokenAnalytics","tags":["Tokens"],"security":[{"ApiKeyAuth":[]}],"summary":"Deep token analytics via Birdeye","description":"Returns comprehensive analytics for any Solana token: real-time price, 24h volume, market cap, liquidity, holder count, top 10 holder % concentration, mint/freeze authority status, creation date, and unique 24h traders. Data sourced from Birdeye. Requires BIRDEYE_API_KEY to be configured. Also available at /api/v1/tokens/{mint}/analytics.","parameters":[{"name":"mint","in":"path","required":true,"schema":{"type":"string","example":"DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"},"description":"Solana token mint address"}],"responses":{"200":{"description":"Token analytics","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"analytics":{"type":"object","properties":{"mint":{"type":"string"},"symbol":{"type":["string","null"]},"name":{"type":["string","null"]},"price_usd":{"type":["number","null"]},"price_change_24h":{"type":["number","null"]},"volume_24h_usd":{"type":["number","null"]},"market_cap_usd":{"type":["number","null"]},"liquidity_usd":{"type":["number","null"]},"holder_count":{"type":["integer","null"]},"unique_traders_24h":{"type":["integer","null"]},"top_10_holder_pct":{"type":["number","null"]},"mint_authority_revoked":{"type":["boolean","null"]},"freeze_authority_active":{"type":["boolean","null"]},"creation_time":{"type":["string","null"]},"source":{"type":"string","example":"birdeye"},"fetched_at":{"type":"string","format":"date-time"}}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Token not found on Birdeye"},"503":{"description":"BIRDEYE_API_KEY not configured"}}}},"/v1/tokens/{mint}/safety":{"get":{"operationId":"getTokenSafety","tags":["Tokens"],"security":[{"ApiKeyAuth":[]}],"summary":"Token safety score — should your agent trade this?","description":"Returns a safety assessment for a Solana token based on on-chain security data from Birdeye. Evaluates: honeypot risk, mint authority (can owner print tokens?), freeze authority (can owner freeze wallets?), top holder concentration, and computes an overall rug_pull_risk score (low/medium/high). Use before trading an unknown token. Also at /api/v1/tokens/{mint}/safety.","parameters":[{"name":"mint","in":"path","required":true,"schema":{"type":"string","example":"DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"},"description":"Solana token mint address"}],"responses":{"200":{"description":"Safety assessment","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"safety":{"type":"object","properties":{"mint":{"type":"string"},"symbol":{"type":["string","null"]},"is_honeypot_risk":{"type":"boolean"},"mint_authority_revoked":{"type":["boolean","null"]},"freeze_authority_active":{"type":["boolean","null"]},"top_holder_concentration_pct":{"type":["number","null"]},"liquidity_locked":{"type":["boolean","null"]},"rug_pull_risk":{"type":"string","enum":["low","medium","high"]},"risk_factors":{"type":"object"},"fetched_at":{"type":"string","format":"date-time"}}}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Token not found"},"503":{"description":"BIRDEYE_API_KEY not configured"}}}},"/api/v1/pump/launches":{"get":{"operationId":"getPumpLaunches","tags":["Tokens"],"security":[{"ApiKeyAuth":[]}],"summary":"Real-time pump.fun token launches (< 5s latency)","description":"Live feed of new pump.fun token launches detected via pumpportal.fun WebSocket (wss://pumpportal.fun/api/data). Sub-5-second latency from on-chain creation to API availability. Returns raw launch data: mint address, creator wallet, initial SOL liquidity, bonding curve progress. Also available as WebSocket channel \"pump_launch\". Also at /v1/pump/launches.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":500},"description":"Max results to return"},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO 8601 timestamp — only return launches after this time"},{"name":"min_liquidity","in":"query","schema":{"type":"number","default":0},"description":"Minimum initial liquidity in SOL (e.g. 0.1)"}],"responses":{"200":{"description":"Pump.fun launches","content":{"application/json":{"schema":{"type":"object","properties":{"launches":{"type":"array","items":{"type":"object","properties":{"mint_address":{"type":"string","description":"Token mint / contract address"},"token_name":{"type":["string","null"]},"token_symbol":{"type":["string","null"]},"creator_wallet":{"type":["string","null"],"description":"Creator wallet public key"},"initial_liquidity_sol":{"type":"number","description":"SOL in initial buy transaction"},"bonding_curve_pct":{"type":["number","null"],"description":"Bonding curve progress 0-100"},"age_seconds":{"type":"integer","description":"Seconds since detection"},"detected_at":{"type":"string","format":"date-time"}}}},"count":{"type":"integer"},"source":{"type":"string","example":"pumpportal_websocket"},"filters":{"type":"object"},"generated_at":{"type":"string","format":"date-time"}}}}}},"401":{"description":"Unauthorized"}}}},"/api/keys":{"post":{"operationId":"createApiKey","tags":["Keys"],"summary":"Create a standalone API key (not linked to an agent account)","description":"Creates a standalone API key associated with an email address. Useful for programmatic access without a full agent account. Save the returned key — it cannot be retrieved again.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["owner_email"],"properties":{"owner_email":{"type":"string","format":"email","example":"you@example.com","description":"Email for account recovery and key association"},"name":{"type":"string","maxLength":255,"example":"production-bot","description":"Optional human-readable key name"},"tier":{"type":"string","enum":["free","standard"],"default":"free","description":"free: 10 req/min, 1k/day. standard: 100 req/min, 10k/day"},"scopes":{"type":"array","items":{"type":"string","enum":["read","trade","withdraw"]},"default":["read","trade","withdraw"],"description":"Permission scopes for this key"}}}}}},"responses":{"201":{"description":"API key created — save immediately","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"key":{"type":"string","example":"ab_sk_...","description":"Full key — only shown once"},"key_prefix":{"type":"string","example":"ab_sk_9f3k"},"name":{"type":["string","null"]},"owner_email":{"type":"string"},"tier":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"rate_limits":{"type":"object","properties":{"per_minute":{"type":"integer"},"per_day":{"type":"integer"}}},"created_at":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Validation error (invalid email, tier, or scopes)"}}},"get":{"operationId":"listApiKeys","tags":["Keys"],"summary":"List your API keys","description":"Returns all active and revoked API keys associated with your account (by owner_email or agent_id).","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Key list","content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"key_prefix":{"type":"string"},"name":{"type":["string","null"]},"owner_email":{"type":["string","null"]},"tier":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"rate_limits":{"type":"object"},"requests_today":{"type":"integer"},"last_used_at":{"type":["string","null"],"format":"date-time"},"active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}}},"count":{"type":"integer"}}}}}},"401":{"description":"Unauthorized"}}}},"/api/keys/{id}":{"delete":{"operationId":"revokeApiKey","tags":["Keys"],"summary":"Revoke an API key","description":"Permanently revokes an API key by ID. The key will stop working immediately. Must own the key (verified via current auth key).","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","example":3},"description":"Key ID from listApiKeys"}],"responses":{"200":{"description":"Key revoked","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Key revoked"},"id":{"type":"integer"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Cannot revoke key you do not own"},"404":{"description":"Key not found"}}}},"/api/keys/tiers":{"get":{"operationId":"getKeyTiers","tags":["Keys"],"summary":"Get API key tier definitions and rate limits","description":"Returns available API key tiers with their rate limits (requests per minute/day).","responses":{"200":{"description":"Tier definitions","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"object","properties":{"ratePerMinute":{"type":"integer"},"ratePerDay":{"type":"integer"}}}}}}}}}},"/v1/paper-trades":{"get":{"operationId":"listPaperTrades","tags":["Orders"],"summary":"List paper trade history (virtual trades only)","description":"Returns all paper trades for this agent. Paper trades are completely isolated from real trades — no real funds are involved. Use mode:\"paper\" in POST /v1/orders to generate paper trades.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Paper trade list","content":{"application/json":{"schema":{"type":"object","properties":{"sandbox":{"type":"boolean","example":true},"paper":{"type":"boolean","example":true},"trades":{"type":"array","items":{"type":"object","properties":{"paper_trade_id":{"type":"integer"},"pair":{"type":"string"},"side":{"type":"string","enum":["buy","sell"]},"type":{"type":"string"},"quantity":{"type":"string"},"fill_price":{"type":"string"},"fee_usdc":{"type":"string"},"status":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}},"401":{"description":"Unauthorized"}}}},"/v1/pump/snipe":{"post":{"operationId":"pumpSnipe","tags":["Tokens"],"summary":"One-shot pump.fun token snipe","description":"Immediately buy a specific pump.fun token by mint address. Rate-limited to 10 snipes/minute. Use mode:\"paper\" for risk-free simulation with virtual $1,000 balance (no real funds). Live mode executes on-chain via Jupiter DEX.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["mint_address","amount_sol"],"properties":{"mint_address":{"type":"string","minLength":20,"example":"DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263","description":"Solana token mint address (from /v1/pump/launches)"},"amount_sol":{"type":"number","exclusiveMinimum":0,"maximum":100,"example":0.1,"description":"SOL amount to spend (converted to USDC equivalent for paper trading)"},"slippage_bps":{"type":"integer","minimum":50,"maximum":5000,"default":500,"description":"Slippage tolerance in basis points (500 = 5%). Default: 500"},"max_age_seconds":{"type":"integer","minimum":1,"default":60,"description":"Reject snipe if token launch is older than this many seconds. Default: 60"},"mode":{"type":"string","enum":["paper","live"],"default":"live","description":"\"paper\" for virtual simulation, \"live\" for on-chain Jupiter execution"}}},"examples":{"paper_snipe":{"summary":"Paper snipe (no real funds)","value":{"mint_address":"DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263","amount_sol":0.1,"mode":"paper"}},"live_snipe":{"summary":"Live snipe","value":{"mint_address":"DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263","amount_sol":0.1,"slippage_bps":1000}}}}}},"responses":{"201":{"description":"Snipe executed","content":{"application/json":{"schema":{"type":"object","properties":{"snipe_id":{"type":"integer"},"agent_id":{"type":"integer"},"mint_address":{"type":"string"},"symbol":{"type":["string","null"]},"name":{"type":["string","null"]},"status":{"type":"string","enum":["filled","pending","failed"]},"mode":{"type":"string","enum":["paper","live"]},"amount_sol":{"type":"string"},"amount_usdc_equiv":{"type":["string","null"]},"tokens_received":{"type":["string","null"]},"price_per_token":{"type":["string","null"]},"fee_usdc":{"type":["string","null"]},"sol_price_usd":{"type":"string"},"paper_balance_usdc":{"type":"string","description":"Remaining paper balance (paper mode only)"},"created_at":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"402":{"description":"Insufficient paper balance"},"422":{"description":"Token too old (max_age_seconds exceeded)"},"429":{"description":"Snipe rate limit exceeded (10/min)"},"503":{"description":"Live trading unavailable — use mode:\"paper\""}}}},"/v1/pump/subscribe":{"post":{"operationId":"pumpSubscribe","tags":["Tokens"],"summary":"Create auto-snipe standing order (fires on every new launch)","description":"Creates a standing auto-snipe subscription. Every time a new pump.fun token is detected that matches your filters, a snipe is automatically executed on your behalf. Use mode:\"paper\" for simulation. Subscriptions fire in real-time via the WebSocket pump_launch channel.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount_sol"],"properties":{"amount_sol":{"type":"number","exclusiveMinimum":0,"maximum":10,"example":0.05,"description":"SOL amount per snipe (max 10)"},"slippage_bps":{"type":"integer","minimum":50,"maximum":5000,"default":500},"max_age_seconds":{"type":"integer","minimum":1,"default":60},"mode":{"type":"string","enum":["paper","live"],"default":"live"},"min_liquidity_usd":{"type":"number","default":5000,"description":"Only snipe tokens with >= this USD liquidity"},"daily_sol_limit":{"type":"number","default":10,"description":"Maximum SOL to spend per day across all auto-snipes from this subscription"},"max_snipe_amount_sol":{"type":"number","default":1,"description":"Hard cap per individual snipe in SOL"},"token_name_contains":{"type":"string","maxLength":100,"description":"Only snipe tokens whose name/symbol contains this substring (case-insensitive)"},"creator_whitelist":{"type":"array","items":{"type":"string"},"maxItems":50,"description":"Only snipe tokens from these creator wallet addresses (empty = allow all)"}}},"examples":{"paper_sub":{"summary":"Paper auto-snipe all new tokens","value":{"amount_sol":0.05,"mode":"paper","min_liquidity_usd":1000}},"live_sub":{"summary":"Live auto-snipe filtered by name","value":{"amount_sol":0.1,"mode":"live","min_liquidity_usd":5000,"token_name_contains":"pepe","daily_sol_limit":2}}}}}},"responses":{"201":{"description":"Subscription created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"subscription":{"type":"object","properties":{"id":{"type":"integer"},"agent_id":{"type":"integer"},"enabled":{"type":"boolean"},"amount_sol":{"type":"string"},"slippage_bps":{"type":"integer"},"mode":{"type":"string"},"min_liquidity_usd":{"type":"string"},"daily_sol_limit":{"type":"string"},"snipes_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}},"message":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"}}}},"/v1/pump/subscriptions":{"get":{"operationId":"listPumpSubscriptions","tags":["Tokens"],"summary":"List auto-snipe subscriptions","description":"Returns all auto-snipe subscriptions for this agent, including disabled ones.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Subscription list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"enabled":{"type":"boolean"},"amount_sol":{"type":"string"},"mode":{"type":"string"},"snipes_count":{"type":"integer"},"last_snipe_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}}},"count":{"type":"integer"}}}}}},"401":{"description":"Unauthorized"}}}},"/v1/pump/subscriptions/{id}":{"delete":{"operationId":"cancelPumpSubscription","tags":["Tokens"],"summary":"Cancel an auto-snipe subscription","description":"Disables an auto-snipe subscription. No new snipes will fire after cancellation.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","example":1},"description":"Subscription ID from listPumpSubscriptions"}],"responses":{"200":{"description":"Subscription cancelled","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"id":{"type":"integer"}}}}}},"401":{"description":"Unauthorized"},"404":{"description":"Subscription not found"}}}},"/v1/pump/snipes":{"get":{"operationId":"listPumpSnipes","tags":["Tokens"],"summary":"Snipe execution history","description":"Returns the complete snipe execution history for this agent (both one-shot and auto-snipe).","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["pending","filled","failed","skipped"]},"description":"Filter by status"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Snipe history","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"snipes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"mint_address":{"type":"string"},"symbol":{"type":["string","null"]},"name":{"type":["string","null"]},"amount_sol":{"type":"string"},"amount_usdc_equiv":{"type":["string","null"]},"mode":{"type":"string","enum":["paper","live"]},"status":{"type":"string","enum":["pending","filled","failed","skipped"]},"tokens_received":{"type":["string","null"]},"fee_usdc":{"type":["string","null"]},"subscription_id":{"type":["integer","null"]},"error_code":{"type":["string","null"]},"error_message":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}},"401":{"description":"Unauthorized"}}}},"/api/v1/webhooks":{"post":{"operationId":"registerWebhook","tags":["System"],"summary":"Register a webhook callback URL","description":"Register a URL to receive real-time event notifications. Events include order fills, trades, balance updates, deposits, and platform announcements. Payloads are signed with HMAC-SHA256 — verify using the X-Webhook-Signature header.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","example":"https://yourbot.example.com/events","description":"HTTPS endpoint to receive webhook payloads"},"events":{"type":"array","items":{"type":"string"},"default":["*"],"example":["*"],"description":"Event types to receive. Use [\"*\"] for all events."},"secret":{"type":"string","description":"Optional HMAC secret for payload signature verification. If omitted, one is auto-generated and returned."}}}}}},"responses":{"201":{"description":"Webhook registered","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"webhook":{"type":"object","properties":{"id":{"type":"integer"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"is_active":{"type":"boolean"},"secret":{"type":"string","description":"Store securely — shown only once"},"created_at":{"type":"string","format":"date-time"}}},"note":{"type":"string"}}}}}},"400":{"description":"Invalid URL"},"401":{"description":"Unauthorized"}}},"get":{"operationId":"listWebhooks","tags":["System"],"summary":"List registered webhooks","description":"Returns all active and inactive webhooks registered for this agent.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Webhook list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"webhooks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"is_active":{"type":"boolean"},"failure_count":{"type":"integer"},"last_success_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}}},"count":{"type":"integer"}}}}}},"401":{"description":"Unauthorized"}}}},"/api/v1/webhooks/{id}":{"delete":{"operationId":"deleteWebhook","tags":["System"],"summary":"Remove a webhook","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Webhook deleted"},"401":{"description":"Unauthorized"},"404":{"description":"Not found"}}}}},"x-websocket":{"description":"Real-time events over WebSocket. Connect, authenticate, then subscribe to channels.","url":"wss://agentbroker.polsia.app/ws","authentication":"After connecting, send: {\"type\":\"auth\",\"api_key\":\"ab_sk_...\"}","channels":{"trades":{"subscribe":"{\"type\":\"subscribe\",\"channel\":\"trades\"}","description":"Your trade execution events"},"balance":{"subscribe":"{\"type\":\"subscribe\",\"channel\":\"balance\"}","description":"Balance updates (deposits, trades, withdrawals)"},"prices":{"subscribe":"{\"type\":\"subscribe\",\"channel\":\"prices\",\"pair\":\"SOL/USDC\"}","description":"Live price ticks for a specific pair"},"new_tokens":{"subscribe":"{\"type\":\"subscribe\",\"channel\":\"new_tokens\"}","description":"Real-time new token discovery events from pump.fun / DexScreener (> $5K liquidity)"},"pump_launch":{"subscribe":"{\"type\":\"subscribe\",\"channel\":\"pump_launch\"}","description":"Raw pump.fun token creation events from pumpportal.fun WebSocket (< 5s latency, all tokens)"}},"events":{"trades:execution":{"fields":["trade_id","pair","side","quantity","fill_price","fee_usdc","balance_usdc"]},"balance:update":{"fields":["event","amount_usdc","balance_usdc","timestamp"]},"prices:tick":{"fields":["pair","price","change_24h_pct","timestamp"]},"new_tokens:new_token":{"fields":["symbol","name","contract","chain","price","liquidity_usd","dex_url","detected_at"]},"pump_launch:pump_launch":{"fields":["mint_address","token_name","token_symbol","creator_wallet","initial_liquidity_sol","bonding_curve_pct","detected_at"]}}}}