{
  "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.002 USDC payment.\n\n**Price:** $0.002 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/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.6 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/tools/{toolName}": {
      "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**Price:** $0.002 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`\n\n**State-changing tools:**\n`build_vault_swap`, `add_liquidity`, `remove_liquidity`, `collect_lp_fees`, `burn_position`, `gmx_open_position`, `gmx_close_position`, `gmx_increase_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`, `disable_swap_shield`, `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": "path",
            "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_open_position",
                "gmx_close_position",
                "gmx_increase_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",
                "disable_swap_shield",
                "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": []
          }
        ]
      }
    }
  },
  "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"
            }
          },
          "routingMode": {
            "type": "string",
            "description": "Force Llama-only routing. Omit for the default Kimi K2.6 orchestration.",
            "enum": [
              "llama_only"
            ]
          },
          "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": "DeepSeek R1 reasoning trace (contents of <think> block). Only present when using Workers AI DeepSeek model."
          },
          "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"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "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"
    }
  ]
}