{ "openapi": "3.1.0", "info": { "title": "Rigoblock", "x-logo": { "url": "https://trader.rigoblock.com/favicon.ico", "altText": "Rigoblock" }, "description": "AI-powered DeFi trading API for autonomous agents. Protected by the x402 v2 payment protocol — pay per request in USDC on Base mainnet, no API key required.\n\n## x402 v2 Payment Flow\n1. Make a request → server responds `402 Payment Required` and may include a `PAYMENT-REQUIRED` header describing accepted payment requirements\n2. Create the payment payload for USDC on Base (chain 8453), typically with `@x402/core`\n3. Retry with the `X-Payment` header → receive structured data; successful 2xx responses may include a `PAYMENT-RESPONSE` settlement receipt\n\n**Use the [@x402/core](https://www.npmjs.com/package/@x402/core) SDK** — it handles payment flow automatically.\n\n**Payment:** USDC on Base (eip155:8453) — CDP facilitator at api.cdp.coinbase.com\n\n**Integration guide & agent-to-agent architecture:** https://github.com/RigoBlock/agentic-operator/blob/main/AGENTS.md\n\n**Supported chains:** Ethereum (1), Base (8453), Arbitrum (42161), Optimism (10), Polygon (137), BNB (56), Unichain (130)", "version": "1.0.0", "contact": { "name": "Rigoblock", "url": "https://rigoblock.com", "email": "gab@rigoblock.com" }, "license": { "name": "Apache-2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0" } }, "servers": [ { "url": "https://trader.rigoblock.com", "description": "Production" } ], "paths": { "/api/quote": { "get": { "operationId": "getDexQuote", "summary": "Get DEX swap quote", "description": "Returns a swap quote sourced from Uniswap liquidity for a given token pair and amount on any of the 7 supported chains. No vault, wallet, or operator context required — any agent can call this endpoint with a $0.0020 USDC payment.\n\n**Price:** $0.0020 USDC per request (x402, eip155:8453)\n\n**Typical use:** Price discovery, trade sizing, yield comparison, arbitrage detection.\n\n**Example:** `GET /api/quote?sell=ETH&buy=USDC&amount=1&chain=base`", "tags": [ "Quotes" ], "parameters": [ { "name": "sell", "in": "query", "required": true, "description": "Token to sell — ticker symbol (e.g. `ETH`) or ERC-20 contract address.", "schema": { "type": "string", "example": "ETH" } }, { "name": "buy", "in": "query", "required": true, "description": "Token to buy — ticker symbol (e.g. `USDC`) or ERC-20 contract address.", "schema": { "type": "string", "example": "USDC" } }, { "name": "amount", "in": "query", "required": true, "description": "Human-readable amount of the sell token (e.g. `1` for 1 ETH).", "schema": { "type": "string", "example": "1" } }, { "name": "chain", "in": "query", "required": false, "description": "Target chain. Accepts chain name or chain ID.", "schema": { "type": "string", "default": "base", "enum": [ "base", "arbitrum", "ethereum", "optimism", "polygon", "bsc", "unichain" ], "example": "base" } } ], "responses": { "200": { "description": "Successful quote response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponse" } } } }, "400": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment required (x402). Pay in USDC on Base and retry with `X-Payment` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentRequired" } } } } }, "security": [ { "x402": [] } ] } }, "/api/quote/uniswap": { "post": { "operationId": "getUniswapQuote", "summary": "Uniswap Trading API quote with oracle enrichment", "description": "Proxies to the Uniswap Trading API `/quote` endpoint and enriches the response with on-chain BackgeoOracle spot-price metadata. Returns the upstream response verbatim plus `priceFeedExists`, `deltaBps`, and `oracleAmount`.\n\n**Price:** $0.0021 USDC per request (x402 exact scheme, eip155:8453)\n\n**Request body:** Identical to the Uniswap Trading API `/quote` endpoint. All request body fields are forwarded verbatim to Uniswap.", "tags": [ "Quotes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "amount", "tokenIn", "tokenOut", "tokenInChainId", "tokenOutChainId" ], "properties": { "type": { "type": "string", "description": "Quote type: EXACT_INPUT or EXACT_OUTPUT", "example": "EXACT_INPUT" }, "amount": { "type": "string", "description": "Amount in base units", "example": "1000000000000000000" }, "tokenIn": { "type": "string", "description": "Token to sell (address or symbol). Use 0x0000...0000 for native ETH.", "example": "ETH" }, "tokenOut": { "type": "string", "description": "Token to buy (address or symbol)", "example": "USDC" }, "tokenInChainId": { "type": "integer", "description": "Chain ID for input token", "example": 8453 }, "tokenOutChainId": { "type": "integer", "description": "Chain ID for output token", "example": 8453 }, "swapper": { "type": "string", "description": "Address of the swapper (vault address)", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }, "slippageTolerance": { "type": "number", "description": "Maximum slippage tolerance in percent", "example": 0.5 }, "routingPreference": { "type": "string", "description": "Routing preference: CLASSIC, BEST_PRICE, FASTEST, or BEST_PRICE_V2", "example": "CLASSIC" }, "protocols": { "type": "array", "items": { "type": "string" }, "description": "List of protocols to include (e.g. V2, V3)", "example": [ "V3" ] } } } } } }, "responses": { "200": { "description": "Successful quote with oracle enrichment", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "Uniswap Trading API quote response" }, { "$ref": "#/components/schemas/OracleEnrichment" } ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized — x402 payment or browser session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment required (x402)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentRequired" } } } } }, "security": [ { "x402": [] } ] } }, "/api/quote/0x": { "get": { "operationId": "get0xQuote", "summary": "0x API quote with oracle enrichment", "description": "Proxies to the 0x API v2 `/swap/allowance-holder/quote` endpoint and enriches the response with on-chain BackgeoOracle spot-price metadata. Returns the upstream response verbatim plus `priceFeedExists`, `deltaBps`, and `oracleAmount`.\n\n**Price:** $0.0022 USDC per request (x402 exact scheme, eip155:8453)\n\n**Query parameters:** Identical to the 0x API. All query parameters are forwarded verbatim to 0x.", "tags": [ "Quotes" ], "parameters": [ { "name": "chainId", "in": "query", "required": true, "description": "Chain ID", "schema": { "type": "integer", "example": 8453 } }, { "name": "sellToken", "in": "query", "required": true, "description": "Token to sell (address or symbol)", "schema": { "type": "string", "example": "ETH" } }, { "name": "buyToken", "in": "query", "required": true, "description": "Token to buy (address or symbol)", "schema": { "type": "string", "example": "USDC" } }, { "name": "sellAmount", "in": "query", "required": false, "description": "Amount to sell in base units (exact-input). Either sellAmount or buyAmount must be provided.", "schema": { "type": "string", "example": "1000000000000000000" } }, { "name": "buyAmount", "in": "query", "required": false, "description": "Amount to buy in base units (exact-output). Either sellAmount or buyAmount must be provided.", "schema": { "type": "string", "example": "2000000000" } }, { "name": "taker", "in": "query", "required": false, "description": "Address of the taker (vault address)", "schema": { "type": "string", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" } }, { "name": "slippageBps", "in": "query", "required": false, "description": "Maximum slippage tolerance in basis points (100 = 1%)", "schema": { "type": "integer", "example": 100 } } ], "responses": { "200": { "description": "Successful quote with oracle enrichment", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "0x API quote response" }, { "$ref": "#/components/schemas/OracleEnrichment" } ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized — x402 payment or browser session required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment required (x402)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentRequired" } } } } }, "security": [ { "x402": [] } ] } }, "/api/chat": { "post": { "operationId": "agentChat", "summary": "AI-powered DeFi agent chat", "description": "Natural language DeFi interface. Send a message describing a trading intent and receive unsigned swap calldata, position summaries, bridge transactions, or market analysis. The agent internally uses Kimi K2.7 Code for reasoning and tool calling.\n\n**Price:** up to $0.10 USDC per request (x402 `upto` scheme, eip155:8453) — billed by actual inference cost, typical $0.003–$0.015\n\n**Supported operations (one per request):**\n- Swap tokens via Uniswap v4 or 0x aggregator\n- Bridge tokens cross-chain via Across Protocol\n- Add/remove Uniswap v4 LP positions\n- Open/close GMX perpetual positions\n- Stake/unstake GRG governance tokens\n- Deploy and fund Rigoblock smart pool vaults\n- Query vault NAV, token balances, active positions\n- Create/manage automated trading strategies\n- Schedule TWAP orders (time-weighted average price execution)\n\n**Execution modes:**\n- manual (default): Returns unsigned calldata — operator signs and broadcasts\n- delegated: Agent wallet executes on-chain directly (requires operator auth + on-chain delegation)\n\n**Safety:** Every transaction passes NAV shield (≤10% loss), Swap Shield (oracle price check), 7-point execution validation, and on-chain selector whitelist.", "tags": [ "Agent" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRequest" }, "example": { "messages": [ { "role": "user", "content": "Swap 0.1 ETH for USDC on Base" } ], "vaultAddress": "0xYourVaultAddress" } } } }, "responses": { "200": { "description": "AI response with DeFi action or analysis", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment required (x402). Pay in USDC on Base and retry with `X-Payment` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentRequired" } } } } }, "security": [ { "x402": [] } ] } }, "/api/settings/slippage": { "post": { "operationId": "setSlippage", "summary": "Set default slippage tolerance", "description": "Operator-only endpoint to set the default slippage tolerance (0.1%–5%). Does not involve the chat LLM; the UI settings panel calls this directly.", "tags": ["Operator Settings"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorSettingsRequest" }, "example": { "vaultAddress": "0xYourVaultAddress", "chainId": 8453, "operatorAddress": "0xOperatorAddress", "authSignature": "0x...", "authTimestamp": 1741700000000, "slippage": "0.5%" } } } }, "responses": { "200": { "description": "Slippage updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" } } } }, "/api/settings/swap-shield": { "post": { "operationId": "setSwapShieldTolerance", "summary": "Set or reset Swap Shield tolerance", "description": "Operator-only endpoint to temporarily raise the Swap Shield tolerance (up to 50% for 10 minutes) or reset it to the default 5%. Does not involve the chat LLM.", "tags": ["Operator Settings"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorSettingsRequest" }, "example": { "vaultAddress": "0xYourVaultAddress", "chainId": 8453, "operatorAddress": "0xOperatorAddress", "authSignature": "0x...", "authTimestamp": 1741700000000, "tolerance": "30%" } } } }, "responses": { "200": { "description": "Swap Shield tolerance updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" } } } }, "/api/settings/nav-shield": { "post": { "operationId": "setNavShieldThreshold", "summary": "Set or reset NAV Shield threshold", "description": "Operator-only endpoint to set the NAV Shield maximum loss threshold (1%–100%) or reset it to the default 10%. Does not involve the chat LLM.", "tags": ["Operator Settings"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorSettingsRequest" }, "example": { "vaultAddress": "0xYourVaultAddress", "chainId": 8453, "operatorAddress": "0xOperatorAddress", "authSignature": "0x...", "authTimestamp": 1741700000000, "threshold": "15%" } } } }, "responses": { "200": { "description": "NAV Shield threshold updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" } } } }, "/api/settings/exec-mode": { "get": { "operationId": "getExecMode", "summary": "Get execution mode preference", "description": "Returns the operator's current auto-execute preference (autonomous or confirm). Shared between the web UI and Telegram.", "tags": ["Operator Settings"], "parameters": [ { "name": "vaultAddress", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "chainId", "in": "query", "required": true, "schema": { "type": "integer" } }, { "name": "operatorAddress", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "authSignature", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "authTimestamp", "in": "query", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Current execution mode preference", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecModeResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" } } }, "post": { "operationId": "setExecMode", "summary": "Set execution mode preference", "description": "Sets whether the operator's trades execute immediately (autonomous) or require confirmation (confirm). Shared between the web UI and Telegram.", "tags": ["Operator Settings"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecModeRequest" }, "example": { "vaultAddress": "0xYourVaultAddress", "chainId": 8453, "operatorAddress": "0xOperatorAddress", "authSignature": "0x...", "authTimestamp": 1741700000000, "mode": "autonomous" } } } }, "responses": { "200": { "description": "Execution mode preference updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecModeResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" } } } }, "/api/tools": { "get": { "operationId": "listTools", "summary": "List all available DeFi tools with schemas", "description": "Returns a machine-readable catalog of every direct-invocation tool: names, descriptions, parameter schemas, categories, and access requirements.\n\nAutonomous agents should call this endpoint first to discover what operations are available and what arguments each tool expects. The response includes full JSON-Schema parameter definitions compatible with OpenAI function calling.\n\n**Price:** $0.0024 USDC per request (x402, eip155:8453)", "tags": [ "Tools" ], "responses": { "200": { "description": "Tool catalog with full schemas", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCatalogResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "x402 payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentRequired" } } } } }, "security": [ { "x402": [] } ] }, "post": { "operationId": "invokeTool", "summary": "Invoke a DeFi tool directly", "description": "Direct tool invocation without LLM overhead. Useful when you know exactly which operation to perform and want structured input/output without natural language parsing. Each call is atomic.\n\n**Discover schemas first:** Call `GET /api/tools` to retrieve the full catalog with parameter schemas for every tool.\n\n**Price:** $0.0025 USDC per request (x402, eip155:8453)\n\n**Read-only tools:**\n`get_swap_quote`, `get_vault_info`, `get_token_balance`, `get_pool_info`, `get_lp_positions`, `gmx_get_positions`, `gmx_get_markets`, `check_delegation_status`, `get_crosschain_quote`, `get_aggregated_nav`, `get_rebalance_plan`, `verify_bridge_arrival`, `list_twap_orders`, `list_nav_syncs`, `list_strategies`, `switch_chain`\n\n**State-changing tools:**\n`build_vault_swap`, `add_liquidity`, `remove_liquidity`, `collect_lp_fees`, `burn_position`, `gmx_increase_position`, `gmx_decrease_position`, `gmx_cancel_order`, `gmx_update_order`, `gmx_claim_funding_fees`, `crosschain_transfer`, `crosschain_sync`, `grg_stake`, `grg_unstake`, `grg_undelegate_stake`, `grg_end_epoch`, `grg_claim_rewards`, `deploy_smart_pool`, `fund_pool`, `create_twap_order`, `cancel_twap_order`, `create_nav_sync`, `cancel_nav_sync`\n\n**Operator-scoped tools (require operatorVerified):**\n`setup_delegation`, `revoke_delegation`, `revoke_selectors`, `list_strategies`, `set_default_slippage`, `set_swap_shield_tolerance`, `enable_swap_shield`\n\n**Oracle tools:**\n`refresh_oracle_feed`\n\n**Orchestration pattern:** External agents compose atomic operations from this endpoint into multi-step strategies. Each call returns either a result (reads) or unsigned calldata (writes). The full safety stack (NAV shield, Swap Shield, slippage protection) applies to all write operations.", "tags": [ "Tools" ], "parameters": [ { "name": "toolName", "in": "query", "required": true, "description": "Tool name to invoke", "schema": { "type": "string", "example": "get_swap_quote", "enum": [ "get_swap_quote", "build_vault_swap", "get_vault_info", "get_token_balance", "switch_chain", "gmx_increase_position", "gmx_decrease_position", "gmx_get_positions", "gmx_cancel_order", "gmx_update_order", "gmx_claim_funding_fees", "gmx_get_markets", "setup_delegation", "revoke_delegation", "check_delegation_status", "deploy_smart_pool", "fund_pool", "crosschain_transfer", "crosschain_sync", "get_crosschain_quote", "get_aggregated_nav", "get_rebalance_plan", "list_strategies", "get_pool_info", "add_liquidity", "remove_liquidity", "get_lp_positions", "collect_lp_fees", "burn_position", "grg_stake", "grg_unstake", "grg_undelegate_stake", "grg_end_epoch", "grg_claim_rewards", "revoke_selectors", "verify_bridge_arrival", "set_default_slippage", "set_swap_shield_tolerance", "enable_swap_shield", "create_twap_order", "cancel_twap_order", "list_twap_orders", "create_nav_sync", "list_nav_syncs", "cancel_nav_sync", "refresh_oracle_feed" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "arguments" ], "properties": { "arguments": { "type": "object", "description": "Tool-specific arguments. For swap tools, provide `tokenIn`, `tokenOut`, and either `amountIn` or `amountOut`. Other tools use different argument shapes.", "additionalProperties": true, "example": { "tokenIn": "ETH", "tokenOut": "USDC", "amountIn": "1" } }, "chainId": { "type": "integer", "description": "EVM chain ID", "default": 8453, "enum": [ 1, 10, 56, 137, 130, 8453, 42161 ] }, "vaultAddress": { "type": "string", "description": "Rigoblock vault address (required for vault-specific tools)", "example": "0xYourVaultAddress" }, "operatorAddress": { "type": "string", "description": "Vault owner address (required for vault-action tools in delegated mode)", "example": "0xOperatorWallet" }, "authSignature": { "type": "string", "description": "EIP-191 signature by operatorAddress over the auth message (required for vault-action tools)", "example": "0x..." }, "authTimestamp": { "type": "integer", "description": "Unix timestamp (ms) when authSignature was created. Valid for 24 hours.", "example": 1741700000000 } } } } } }, "responses": { "200": { "description": "Tool result", "content": { "application/json": { "schema": { "type": "object", "properties": { "tool": { "type": "string", "description": "Canonical tool name that handled the request" }, "message": { "type": "string", "description": "Human-readable tool result" }, "transaction": { "type": "object", "description": "Unsigned transaction payload for state-changing tools" }, "chainSwitch": { "type": "integer", "description": "Suggested chain switch, when the tool resolved to a different chain" }, "suggestions": { "type": "array", "items": { "type": "string" } } } }, "example": { "tool": "get_swap_quote", "message": "1 ETH -> 2079.54 USDC on Base via 0x.", "suggestions": [ "Build the swap transaction", "Try the same quote on Arbitrum" ] } } } }, "400": { "description": "Bad request — missing or invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Operator authentication required for this tool", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "x402 payment required", "headers": { "PAYMENT-REQUIRED": { "description": "Base64-encoded payment requirements", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentRequired" } } } }, "404": { "description": "Unknown tool name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "x402": [] } ] } }, "/api/health": { "get": { "operationId": "healthCheck", "summary": "Health check", "description": "Returns service status, version, and feature flags.", "tags": [ "System" ], "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/chains": { "get": { "operationId": "listChains", "summary": "Supported chains", "description": "Returns the list of supported EVM chains.", "tags": [ "System" ], "parameters": [ { "name": "testnet", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "List of chains", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/session": { "get": { "operationId": "getSession", "summary": "Get session token", "description": "Issues an HMAC-signed session token for browser clients. Rate-limited per IP.", "tags": [ "Auth" ], "responses": { "200": { "description": "Session token", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Not from allowed origin" }, "429": { "description": "Rate limit exceeded" } } } }, "/api/vault": { "get": { "operationId": "getVaultInfo", "summary": "Vault info", "description": "Returns on-chain vault information. Tries the requested chain first, then all others.", "tags": [ "Vault" ], "parameters": [ { "name": "address", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "chain", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Vault info" }, "400": { "description": "Invalid address" }, "404": { "description": "Vault not found" } } } }, "/api/strategy-events": { "get": { "operationId": "getStrategyEvents", "summary": "Strategy events", "description": "Polling endpoint for web chat notifications (TWAP events).", "tags": [ "Strategies" ], "parameters": [ { "name": "vault", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Events list" }, "400": { "description": "Missing vault param" } } } }, "/api/oracle/refresh": { "post": { "operationId": "refreshOracle", "summary": "BackgeoOracle pool refresh", "description": "Builds an unsigned exact-input swap transaction that updates the on-chain BackgeoOracle price feed for a given ERC-20 token. The oracle pool always pairs the native token (ETH/POL/BNB) as currency0 with the specified ERC-20 as currency1. Supports EOA and vault paths.\n\n**Price:** $0.0023 USDC per request (x402 exact scheme, eip155:8453)", "tags": [ "Oracle" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token", "tokenIn", "tokenOut", "chainId" ], "properties": { "token": { "type": "string", "description": "ERC-20 token symbol or address whose oracle feed is stale (e.g. 'GRG', 'USDC'). The native token (ETH/POL/BNB) cannot be used here; it is always currency0 in the oracle pool." }, "tokenIn": { "type": "string", "description": "Token the trader pays. Must be the chain's native token (ETH/POL/BNB) or the ERC-20 'token'." }, "tokenOut": { "type": "string", "description": "Token the trader receives. Must be the chain's native token (ETH/POL/BNB) or the ERC-20 'token'." }, "amount": { "type": "string", "description": "Exact INPUT amount in tokenIn units. Defaults to '0.001'." }, "chainId": { "type": "integer", "description": "Chain ID" }, "vaultAddress": { "type": "string", "description": "Optional vault address for vault path" } } } } } }, "responses": { "200": { "description": "Unsigned transaction" }, "401": { "description": "Unauthorized" }, "402": { "description": "Payment required (x402)" } }, "security": [ { "x402": [] } ] } }, "/api/delegation/setup": { "post": { "operationId": "setupDelegation", "summary": "Prepare delegation transaction", "description": "Returns an unsigned transaction to delegate vault function selectors to the agent wallet. Requires operator signature.", "tags": [ "Delegation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Unsigned delegation transaction" }, "401": { "description": "Invalid operator signature" } } } }, "/api/delegation/confirm": { "post": { "operationId": "confirmDelegation", "summary": "Confirm delegation", "description": "Stores delegation config in KV after the on-chain transaction is confirmed.", "tags": [ "Delegation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Confirmation result" } } } }, "/api/delegation/revoke": { "post": { "operationId": "revokeDelegation", "summary": "Revoke delegation", "description": "Returns an unsigned transaction to revoke delegation. Clears KV config on success.", "tags": [ "Delegation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Unsigned revocation transaction" } } } }, "/api/delegation/status": { "get": { "operationId": "getDelegationStatus", "summary": "Delegation status", "description": "Returns delegation status from KV and on-chain verification.", "tags": [ "Delegation" ], "parameters": [ { "name": "vault", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "chainId", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Delegation status" } } } }, "/api/delegation/execute": { "post": { "operationId": "executeViaDelegation", "summary": "Execute transaction via delegation", "description": "Executes a transaction on the vault via the agent wallet's delegation. Requires operator auth.", "tags": [ "Delegation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Execution result" }, "401": { "description": "Unauthorized" } } } }, "/api/delegation/balance": { "get": { "operationId": "getAgentBalance", "summary": "Agent wallet balance", "description": "Returns the agent wallet's native token balance.", "tags": [ "Delegation" ], "parameters": [ { "name": "vault", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Balance info" } } } }, "/api/delegation/tx-status": { "get": { "operationId": "getTxStatus", "summary": "Transaction status", "description": "Returns the status of a pending transaction.", "tags": [ "Delegation" ], "parameters": [ { "name": "txHash", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction status" } } } }, "/api/delegation/settings": { "post": { "operationId": "updateDelegationSettings", "summary": "Update delegation settings", "description": "Updates delegation-specific settings (e.g. slippage, gas policy).", "tags": [ "Delegation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated settings" } } } }, "/api/delegation/telegram-reset": { "post": { "operationId": "resetTelegramPairing", "summary": "Reset Telegram pairing", "description": "Removes Telegram pairing for a vault.", "tags": [ "Delegation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Reset result" } } } }, "/api/gas-policy": { "get": { "operationId": "gasPolicyHealth", "summary": "Gas policy health check", "description": "Returns a simple health check for the gas policy webhook endpoint.", "tags": [ "System" ], "responses": { "200": { "description": "Gas policy endpoint is healthy" } } }, "post": { "operationId": "gasPolicyWebhook", "summary": "Alchemy Gas Manager webhook", "description": "Webhook called by Alchemy's Gas Manager to approve or reject gas sponsorship for a UserOperation.", "tags": [ "System" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Approval decision" } } } }, "/api/telegram/webhook": { "post": { "operationId": "telegramWebhook", "summary": "Telegram Bot webhook", "description": "Receives updates from the Telegram Bot API.", "tags": [ "Telegram" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OK" } } } }, "/api/telegram/unpair": { "post": { "operationId": "telegramUnpair", "summary": "Unpair Telegram", "description": "Removes a vault's Telegram pairing.", "tags": [ "Telegram" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Unpair result" } } } }, "/api/telegram/pair": { "post": { "operationId": "telegramPair", "summary": "Generate Telegram pairing code", "description": "Generates a pairing code to link a Telegram account to a vault.", "tags": [ "Telegram" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Pairing code" } } } }, "/api/telegram/setup": { "get": { "operationId": "getTelegramSetup", "summary": "Get Telegram webhook setup", "description": "Returns current webhook configuration.", "tags": [ "Telegram" ], "responses": { "200": { "description": "Webhook config" } } }, "post": { "operationId": "setupTelegramWebhook", "summary": "Setup Telegram webhook", "description": "Registers the webhook URL with Telegram.", "tags": [ "Telegram" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Setup result" } } } }, "/api/telegram/debug": { "get": { "operationId": "telegramDebug", "summary": "Telegram debug endpoint", "description": "Debug endpoint for Telegram integration diagnostics.", "tags": [ "Telegram" ], "responses": { "200": { "description": "Debug info" } } } } }, "components": { "securitySchemes": { "x402": { "type": "apiKey", "in": "header", "name": "X-Payment", "description": "x402 payment header. Flow:\n1. Make the request without this header → receive `402 Payment Required` and, for protected routes, a `PAYMENT-REQUIRED` header describing accepted payment requirements\n2. Create the x402 payment payload for USDC on Base (chain 8453), typically via `@x402/core` and the CDP facilitator at `api.cdp.coinbase.com`\n3. Retry the request with this header set to the encoded payment payload\n\nSuccessful 2xx responses may include a `PAYMENT-RESPONSE` settlement receipt. See https://github.com/rigoblock/agentic-operator/blob/main/AGENTS.md for full integration." } }, "schemas": { "QuoteResponse": { "type": "object", "description": "Best swap quote across 150+ liquidity sources (0x default) or Uniswap V2/V3/V4", "properties": { "sellToken": { "type": "string", "description": "Address of the token being sold", "example": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE" }, "buyToken": { "type": "string", "description": "Address of the token being bought", "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "sellAmount": { "type": "string", "description": "Sell amount in token base units (wei)", "example": "1000000000000000000" }, "buyAmount": { "type": "string", "description": "Buy amount in token base units", "example": "2485000000" }, "price": { "type": "string", "description": "Exchange rate (buy per sell)", "example": "2485.00" }, "source": { "type": "string", "description": "DEX source routing the quote", "example": "0x" }, "chain": { "type": "string", "description": "Chain the quote is valid on", "example": "base" }, "calldata": { "type": "string", "description": "Encoded calldata for on-chain execution" }, "to": { "type": "string", "description": "Contract address to send the swap transaction to" }, "value": { "type": "string", "description": "ETH value to attach (for native token swaps)", "example": "1000000000000000000" }, "gasEstimate": { "type": "string", "description": "Estimated gas units for the transaction", "example": "180000" } } }, "ChatRequest": { "type": "object", "required": [ "messages" ], "properties": { "messages": { "type": "array", "description": "Conversation history in OpenAI message format", "items": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "user", "assistant", "system" ] }, "content": { "type": "string" } } } }, "vaultAddress": { "type": "string", "description": "RigoBlock vault (smart pool) address for vault-scoped operations", "example": "0xYourVaultAddress" }, "contextDocs": { "type": "array", "description": "Optional request-scoped context snippets (for example markdown excerpts) injected into the model prompt for this request.", "items": { "type": "string" } }, "chain": { "type": "string", "description": "Target chain context", "default": "base", "enum": [ "base", "arbitrum", "ethereum", "optimism", "polygon", "bsc", "unichain" ] } } }, "ChatResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "AI-generated response text" }, "reasoning": { "type": "string", "description": "Reasoning trace from the model, when available." }, "modelsUsed": { "type": "array", "description": "Ordered list of model identifiers that contributed to this output.", "items": { "type": "string" } }, "finalModel": { "type": "string", "description": "Model that authored the final natural-language output (or 'tooling' when output is tool-native)." }, "action": { "type": "object", "description": "Executable on-chain action, if applicable", "properties": { "type": { "type": "string", "enum": [ "swap", "position", "analysis" ], "description": "Action type" }, "to": { "type": "string", "description": "Contract address" }, "calldata": { "type": "string", "description": "Encoded transaction calldata" }, "value": { "type": "string", "description": "ETH value to attach" }, "gasEstimate": { "type": "string", "description": "Estimated gas" } } } } }, "X402PaymentRequired": { "type": "object", "description": "Standard x402 payment challenge", "properties": { "x402Version": { "type": "integer", "example": 1 }, "error": { "type": "string", "example": "X-PAYMENT-REQUIRED" }, "accepts": { "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string", "example": "exact" }, "network": { "type": "string", "example": "base" }, "maxAmountRequired": { "type": "string", "example": "2000" }, "resource": { "type": "string", "example": "https://trader.rigoblock.com/api/quote" }, "description": { "type": "string" }, "mimeType": { "type": "string", "example": "application/json" }, "payTo": { "type": "string", "description": "USDC recipient address on Base" }, "maxTimeoutSeconds": { "type": "integer", "example": 300 }, "asset": { "type": "string", "description": "USDC contract address on Base", "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "extra": { "type": "object", "properties": { "name": { "type": "string", "example": "USDC" }, "version": { "type": "string", "example": "2" } } } } } } } }, "ToolDefinition": { "type": "object", "description": "OpenAI-compatible function schema for a single DeFi tool", "required": [ "name", "description", "category", "parameters", "requiresOperatorAuth", "readOnly" ], "properties": { "name": { "type": "string", "description": "Canonical tool name used in POST /api/tools?toolName={name}" }, "description": { "type": "string", "description": "What the tool does and when to use it" }, "category": { "type": "string", "description": "Functional group", "enum": [ "Spot Trading", "Vault Info", "GMX Perpetuals", "Uniswap v4 LP", "Cross-Chain", "GRG Staking", "Vault Management", "Delegation", "TWAP Orders", "NAV Sync", "Operator Settings", "Oracle", "Strategy", "Other" ] }, "parameters": { "type": "object", "description": "JSON Schema for the tool's arguments object" }, "requiresOperatorAuth": { "type": "boolean", "description": "If true, the tool can only be invoked when the request includes a valid operator signature" }, "readOnly": { "type": "boolean", "description": "If true, the tool only reads data and never produces transaction calldata" } } }, "ToolCatalogResponse": { "type": "object", "required": [ "description", "usage", "price", "toolCount", "tools" ], "properties": { "description": { "type": "string" }, "usage": { "type": "string", "example": "POST /api/tools?toolName={name}" }, "price": { "type": "string", "example": "$0.0020–$0.0025 USDC per call (x402 exact scheme, eip155:8453)" }, "toolCount": { "type": "integer", "description": "Total number of tools in the catalog" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolDefinition" } } } }, "OracleEnrichment": { "type": "object", "description": "On-chain oracle spot-price metadata appended to DEX API responses", "properties": { "priceFeedExists": { "type": "boolean", "description": "Whether both tokens have an active BackgeoOracle price feed" }, "deltaBps": { "type": "integer", "description": "Divergence between DEX expected output and oracle spot price, in basis points. Positive = DEX gives less than oracle. Negative = DEX gives more.", "example": 12 }, "oracleAmount": { "type": "string", "description": "Expected output amount from oracle spot price, in base units (wei/smallest token unit)", "example": "2079548076" } } }, "OperatorSettingsRequest": { "type": "object", "required": ["vaultAddress", "chainId", "operatorAddress", "authSignature", "authTimestamp"], "properties": { "vaultAddress": { "type": "string", "description": "Vault contract address" }, "chainId": { "type": "integer", "description": "Chain ID where the vault exists" }, "operatorAddress": { "type": "string", "description": "Vault owner address" }, "authSignature": { "type": "string", "description": "EIP-191 signature of the auth message" }, "authTimestamp": { "type": "integer", "description": "Timestamp included in the signed auth message" }, "slippage": { "type": "string", "description": "Slippage value (e.g. '0.5%', '50bps', or '0.5')" }, "tolerance": { "type": "string", "description": "Swap Shield tolerance percentage (e.g. '30%')" }, "threshold": { "type": "string", "description": "NAV Shield threshold percentage (e.g. '15%')" }, "reset": { "type": "boolean", "description": "When true, reset the setting to its default value" } } }, "ExecModeRequest": { "type": "object", "required": ["vaultAddress", "chainId", "operatorAddress", "authSignature", "authTimestamp", "mode"], "properties": { "vaultAddress": { "type": "string", "description": "Vault contract address" }, "chainId": { "type": "integer", "description": "Chain ID where the vault exists" }, "operatorAddress": { "type": "string", "description": "Vault owner address" }, "authSignature": { "type": "string", "description": "EIP-191 signature of the auth message" }, "authTimestamp": { "type": "integer", "description": "Timestamp included in the signed auth message" }, "mode": { "type": "string", "enum": ["autonomous", "confirm"], "description": "Autonomous executes trades immediately; confirm requires an explicit approval" } } }, "ExecModeResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "mode": { "type": "string", "enum": ["autonomous", "confirm"] } } }, "SettingsResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "message": { "type": "string" } } }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } } }, "tags": [ { "name": "Quotes", "description": "DEX price quotes — no wallet or vault context required" }, { "name": "Agent", "description": "AI-powered DeFi agent interface — natural language to calldata" }, { "name": "Tools", "description": "Direct tool invocation without LLM overhead — structured input/output" }, { "name": "Operator Settings", "description": "Operator-scoped safety settings — requires vault ownership proof, bypasses the LLM" } ] }