{
  "openapi": "3.0.0",
  "info": {
    "title": "Carbon DeFi API",
    "version": "0.7.0",
    "description": "REST API for creating and managing on-chain maker trading strategies on Carbon DeFi. All write operations return unsigned transactions — the user signs and broadcasts."
  },
  "servers": [
    {
      "url": "https://mcp.carbondefi.xyz",
      "description": "Production"
    },
    {
      "url": "http://localhost:3000",
      "description": "Local"
    }
  ],
  "paths": {
    "/tools/get_strategies": {
      "post": {
        "operationId": "get_strategies",
        "summary": "Fetch all active strategies for a wallet",
        "tags": [
          "Read"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "wallet_address",
                  "chain"
                ],
                "properties": {
                  "wallet_address": {
                    "type": "string",
                    "description": "EVM wallet address (0x...)"
                  },
                  "chain": {
                    "type": "string",
                    "enum": [
                      "ethereum",
                      "sei",
                      "celo",
                      "tac"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success — returns strategy preview and unsigned transaction"
          },
          "400": {
            "description": "Invalid parameters or business logic error"
          }
        }
      }
    },
    "/tools/create_limit_order": {
      "post": {
        "operationId": "create_limit_order",
        "summary": "Create a one-time limit order at exact price",
        "tags": [
          "Create"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "wallet_address",
                  "chain",
                  "base_token",
                  "quote_token",
                  "direction",
                  "price",
                  "budget"
                ],
                "properties": {
                  "wallet_address": {
                    "type": "string"
                  },
                  "chain": {
                    "type": "string",
                    "enum": [
                      "ethereum",
                      "sei",
                      "celo",
                      "tac"
                    ]
                  },
                  "base_token": {
                    "type": "string"
                  },
                  "quote_token": {
                    "type": "string"
                  },
                  "direction": {
                    "type": "string",
                    "enum": [
                      "buy",
                      "sell"
                    ]
                  },
                  "price": {
                    "type": "number",
                    "description": "Exact execution price in quote per base"
                  },
                  "budget": {
                    "type": "number",
                    "description": "Quote token for buy, base token for sell"
                  },
                  "market_price": {
                    "type": "number"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success — returns strategy preview and unsigned transaction"
          },
          "400": {
            "description": "Invalid parameters or business logic error"
          }
        }
      }
    },
    "/tools/create_range_order": {
      "post": {
        "operationId": "create_range_order",
        "summary": "Create a one-time range order across a price range. Good for DCA.",
        "tags": [
          "Create"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "wallet_address",
                  "chain",
                  "base_token",
                  "quote_token",
                  "direction",
                  "price_low",
                  "price_high",
                  "budget"
                ],
                "properties": {
                  "wallet_address": {
                    "type": "string"
                  },
                  "chain": {
                    "type": "string",
                    "enum": [
                      "ethereum",
                      "sei",
                      "celo",
                      "tac"
                    ]
                  },
                  "base_token": {
                    "type": "string"
                  },
                  "quote_token": {
                    "type": "string"
                  },
                  "direction": {
                    "type": "string",
                    "enum": [
                      "buy",
                      "sell"
                    ]
                  },
                  "price_low": {
                    "type": "number"
                  },
                  "price_high": {
                    "type": "number"
                  },
                  "budget": {
                    "type": "number"
                  },
                  "market_price": {
                    "type": "number"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success — returns strategy preview and unsigned transaction"
          },
          "400": {
            "description": "Invalid parameters or business logic error"
          }
        }
      }
    },
    "/tools/create_recurring_strategy": {
      "post": {
        "operationId": "create_recurring_strategy",
        "summary": "Create a looping buy+sell strategy with zero gas on fills",
        "tags": [
          "Create"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "wallet_address",
                  "chain",
                  "base_token",
                  "quote_token",
                  "buy_price_low",
                  "buy_price_high",
                  "buy_budget",
                  "sell_price_low",
                  "sell_price_high",
                  "sell_budget"
                ],
                "properties": {
                  "wallet_address": {
                    "type": "string"
                  },
                  "chain": {
                    "type": "string",
                    "enum": [
                      "ethereum",
                      "sei",
                      "celo",
                      "tac"
                    ]
                  },
                  "base_token": {
                    "type": "string"
                  },
                  "quote_token": {
                    "type": "string"
                  },
                  "buy_price_low": {
                    "type": "number"
                  },
                  "buy_price_high": {
                    "type": "number"
                  },
                  "buy_price_marginal": {
                    "type": "number"
                  },
                  "buy_budget": {
                    "type": "number"
                  },
                  "sell_price_low": {
                    "type": "number"
                  },
                  "sell_price_high": {
                    "type": "number"
                  },
                  "sell_budget": {
                    "type": "number"
                  },
                  "market_price": {
                    "type": "number"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success — returns strategy preview and unsigned transaction"
          },
          "400": {
            "description": "Invalid parameters or business logic error"
          }
        }
      }
    },
    "/tools/create_concentrated_strategy": {
      "post": {
        "operationId": "create_concentrated_strategy",
        "summary": "Create two-sided liquidity with a defined spread",
        "tags": [
          "Create"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "wallet_address",
                  "chain",
                  "base_token",
                  "quote_token",
                  "price_low",
                  "price_high",
                  "spread_percentage",
                  "anchor",
                  "budget",
                  "market_price"
                ],
                "properties": {
                  "wallet_address": {
                    "type": "string"
                  },
                  "chain": {
                    "type": "string",
                    "enum": [
                      "ethereum",
                      "sei",
                      "celo",
                      "tac"
                    ]
                  },
                  "base_token": {
                    "type": "string"
                  },
                  "quote_token": {
                    "type": "string"
                  },
                  "price_low": {
                    "type": "number"
                  },
                  "price_high": {
                    "type": "number"
                  },
                  "spread_percentage": {
                    "type": "number"
                  },
                  "anchor": {
                    "type": "string",
                    "enum": [
                      "buy",
                      "sell"
                    ]
                  },
                  "budget": {
                    "type": "number"
                  },
                  "market_price": {
                    "type": "number"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success — returns strategy preview and unsigned transaction"
          },
          "400": {
            "description": "Invalid parameters or business logic error"
          }
        }
      }
    },
    "/tools/create_full_range_strategy": {
      "post": {
        "operationId": "create_full_range_strategy",
        "summary": "Create full range liquidity (up to 1000x from market price)",
        "tags": [
          "Create"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "wallet_address",
                  "chain",
                  "base_token",
                  "quote_token",
                  "spread_percentage",
                  "anchor",
                  "budget",
                  "market_price"
                ],
                "properties": {
                  "wallet_address": {
                    "type": "string"
                  },
                  "chain": {
                    "type": "string",
                    "enum": [
                      "ethereum",
                      "sei",
                      "celo",
                      "tac"
                    ]
                  },
                  "base_token": {
                    "type": "string"
                  },
                  "quote_token": {
                    "type": "string"
                  },
                  "spread_percentage": {
                    "type": "number"
                  },
                  "anchor": {
                    "type": "string",
                    "enum": [
                      "buy",
                      "sell"
                    ]
                  },
                  "budget": {
                    "type": "number"
                  },
                  "market_price": {
                    "type": "number"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success — returns strategy preview and unsigned transaction"
          },
          "400": {
            "description": "Invalid parameters or business logic error"
          }
        }
      }
    },
    "/tools/reprice_strategy": {
      "post": {
        "operationId": "reprice_strategy",
        "summary": "Update price ranges of an existing strategy",
        "tags": [
          "Manage"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "wallet_address",
                  "chain",
                  "strategy_id"
                ],
                "properties": {
                  "wallet_address": {
                    "type": "string"
                  },
                  "chain": {
                    "type": "string",
                    "enum": [
                      "ethereum",
                      "sei",
                      "celo",
                      "tac"
                    ]
                  },
                  "strategy_id": {
                    "type": "string"
                  },
                  "buy_price_low": {
                    "type": "number"
                  },
                  "buy_price_high": {
                    "type": "number"
                  },
                  "sell_price_low": {
                    "type": "number"
                  },
                  "sell_price_high": {
                    "type": "number"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success — returns strategy preview and unsigned transaction"
          },
          "400": {
            "description": "Invalid parameters or business logic error"
          }
        }
      }
    },
    "/tools/edit_strategy": {
      "post": {
        "operationId": "edit_strategy",
        "summary": "Edit prices and budgets together in one transaction",
        "tags": [
          "Manage"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "wallet_address",
                  "chain",
                  "strategy_id"
                ],
                "properties": {
                  "wallet_address": {
                    "type": "string"
                  },
                  "chain": {
                    "type": "string",
                    "enum": [
                      "ethereum",
                      "sei",
                      "celo",
                      "tac"
                    ]
                  },
                  "strategy_id": {
                    "type": "string"
                  },
                  "buy_price_low": {
                    "type": "number"
                  },
                  "buy_price_high": {
                    "type": "number"
                  },
                  "buy_budget": {
                    "type": "number"
                  },
                  "sell_price_low": {
                    "type": "number"
                  },
                  "sell_price_high": {
                    "type": "number"
                  },
                  "sell_budget": {
                    "type": "number"
                  },
                  "market_price": {
                    "type": "number"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success — returns strategy preview and unsigned transaction"
          },
          "400": {
            "description": "Invalid parameters or business logic error"
          }
        }
      }
    },
    "/tools/deposit_budget": {
      "post": {
        "operationId": "deposit_budget",
        "summary": "Add funds to an existing strategy",
        "tags": [
          "Manage"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "wallet_address",
                  "chain",
                  "strategy_id"
                ],
                "properties": {
                  "wallet_address": {
                    "type": "string"
                  },
                  "chain": {
                    "type": "string",
                    "enum": [
                      "ethereum",
                      "sei",
                      "celo",
                      "tac"
                    ]
                  },
                  "strategy_id": {
                    "type": "string"
                  },
                  "buy_budget_increase": {
                    "type": "number"
                  },
                  "sell_budget_increase": {
                    "type": "number"
                  },
                  "anchor": {
                    "type": "string",
                    "enum": [
                      "buy",
                      "sell"
                    ]
                  },
                  "budget_increase": {
                    "type": "number"
                  },
                  "market_price": {
                    "type": "number"
                  },
                  "spread_percentage": {
                    "type": "number"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success — returns strategy preview and unsigned transaction"
          },
          "400": {
            "description": "Invalid parameters or business logic error"
          }
        }
      }
    },
    "/tools/withdraw_budget": {
      "post": {
        "operationId": "withdraw_budget",
        "summary": "Withdraw funds from a strategy without closing it",
        "tags": [
          "Manage"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "wallet_address",
                  "chain",
                  "strategy_id"
                ],
                "properties": {
                  "wallet_address": {
                    "type": "string"
                  },
                  "chain": {
                    "type": "string",
                    "enum": [
                      "ethereum",
                      "sei",
                      "celo",
                      "tac"
                    ]
                  },
                  "strategy_id": {
                    "type": "string"
                  },
                  "buy_budget_decrease": {
                    "type": "number"
                  },
                  "sell_budget_decrease": {
                    "type": "number"
                  },
                  "anchor": {
                    "type": "string",
                    "enum": [
                      "buy",
                      "sell"
                    ]
                  },
                  "budget_decrease": {
                    "type": "number"
                  },
                  "market_price": {
                    "type": "number"
                  },
                  "spread_percentage": {
                    "type": "number"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success — returns strategy preview and unsigned transaction"
          },
          "400": {
            "description": "Invalid parameters or business logic error"
          }
        }
      }
    },
    "/tools/pause_strategy": {
      "post": {
        "operationId": "pause_strategy",
        "summary": "Pause a strategy - prices zeroed, funds stay",
        "tags": [
          "Manage"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "wallet_address",
                  "chain",
                  "strategy_id"
                ],
                "properties": {
                  "wallet_address": {
                    "type": "string"
                  },
                  "chain": {
                    "type": "string",
                    "enum": [
                      "ethereum",
                      "sei",
                      "celo",
                      "tac"
                    ]
                  },
                  "strategy_id": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success — returns strategy preview and unsigned transaction"
          },
          "400": {
            "description": "Invalid parameters or business logic error"
          }
        }
      }
    },
    "/tools/resume_strategy": {
      "post": {
        "operationId": "resume_strategy",
        "summary": "Resume a paused strategy by restoring price ranges",
        "tags": [
          "Manage"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "wallet_address",
                  "chain",
                  "strategy_id",
                  "market_price"
                ],
                "properties": {
                  "wallet_address": {
                    "type": "string"
                  },
                  "chain": {
                    "type": "string",
                    "enum": [
                      "ethereum",
                      "sei",
                      "celo",
                      "tac"
                    ]
                  },
                  "strategy_id": {
                    "type": "string"
                  },
                  "buy_price_low": {
                    "type": "number"
                  },
                  "buy_price_high": {
                    "type": "number"
                  },
                  "sell_price_low": {
                    "type": "number"
                  },
                  "sell_price_high": {
                    "type": "number"
                  },
                  "market_price": {
                    "type": "number"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success — returns strategy preview and unsigned transaction"
          },
          "400": {
            "description": "Invalid parameters or business logic error"
          }
        }
      }
    },
    "/tools/delete_strategy": {
      "post": {
        "operationId": "delete_strategy",
        "summary": "Permanently close a strategy and return all funds",
        "tags": [
          "Manage"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "wallet_address",
                  "chain",
                  "strategy_id"
                ],
                "properties": {
                  "wallet_address": {
                    "type": "string"
                  },
                  "chain": {
                    "type": "string",
                    "enum": [
                      "ethereum",
                      "sei",
                      "celo",
                      "tac"
                    ]
                  },
                  "strategy_id": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success — returns strategy preview and unsigned transaction"
          },
          "400": {
            "description": "Invalid parameters or business logic error"
          }
        }
      }
    },
    "/tools/get_activity": {
      "post": {
        "operationId": "get_activity",
        "summary": "Fetch trade and event history for a wallet or strategy",
        "tags": [
          "Explore"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "chain"
                ],
                "properties": {
                  "chain": {
                    "type": "string",
                    "enum": [
                      "ethereum",
                      "sei",
                      "celo",
                      "tac"
                    ]
                  },
                  "wallet_address": {
                    "type": "string"
                  },
                  "strategy_id": {
                    "type": "string"
                  },
                  "actions": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "start": {
                    "type": "number"
                  },
                  "end": {
                    "type": "number"
                  },
                  "limit": {
                    "type": "number"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success — returns strategy preview and unsigned transaction"
          },
          "400": {
            "description": "Invalid parameters or business logic error"
          }
        }
      }
    },
    "/tools/simulate_strategy": {
      "post": {
        "operationId": "simulate_strategy",
        "summary": "Backtest a strategy against historical price data",
        "tags": [
          "Explore"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "chain",
                  "base_token",
                  "quote_token",
                  "start",
                  "end"
                ],
                "properties": {
                  "chain": {
                    "type": "string",
                    "enum": [
                      "ethereum",
                      "sei",
                      "celo",
                      "tac"
                    ]
                  },
                  "base_token": {
                    "type": "string"
                  },
                  "quote_token": {
                    "type": "string"
                  },
                  "start": {
                    "type": "number",
                    "description": "Backtest start as Unix timestamp"
                  },
                  "end": {
                    "type": "number",
                    "description": "Backtest end as Unix timestamp"
                  },
                  "strategy_type": {
                    "type": "string",
                    "enum": [
                      "recurring",
                      "concentrated",
                      "full_range"
                    ],
                    "description": "Default: recurring"
                  },
                  "buy_price_low": {
                    "type": "number"
                  },
                  "buy_price_high": {
                    "type": "number"
                  },
                  "buy_budget": {
                    "type": "number"
                  },
                  "sell_price_low": {
                    "type": "number"
                  },
                  "sell_price_high": {
                    "type": "number"
                  },
                  "sell_budget": {
                    "type": "number"
                  },
                  "price_low": {
                    "type": "number"
                  },
                  "price_high": {
                    "type": "number"
                  },
                  "spread_percentage": {
                    "type": "number"
                  },
                  "anchor": {
                    "type": "string",
                    "enum": [
                      "buy",
                      "sell"
                    ]
                  },
                  "budget": {
                    "type": "number"
                  },
                  "market_price": {
                    "type": "number"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success — returns strategy preview and unsigned transaction"
          },
          "400": {
            "description": "Invalid parameters or business logic error"
          }
        }
      }
    },
    "/tools/explore_pair": {
      "post": {
        "operationId": "explore_pair",
        "summary": "Explore market liquidity and top strategies for a token pair",
        "tags": [
          "Explore"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "chain",
                  "base_token",
                  "quote_token"
                ],
                "properties": {
                  "chain": {
                    "type": "string",
                    "enum": [
                      "ethereum",
                      "sei",
                      "celo",
                      "tac"
                    ]
                  },
                  "base_token": {
                    "type": "string"
                  },
                  "quote_token": {
                    "type": "string"
                  },
                  "top_n": {
                    "type": "number"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success — returns strategy preview and unsigned transaction"
          },
          "400": {
            "description": "Invalid parameters or business logic error"
          }
        }
      }
    },
    "/tools/help": {
      "post": {
        "operationId": "help",
        "summary": "Get detailed guidance on any tool or a full overview",
        "tags": [
          "Help"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [],
                "properties": {
                  "tool": {
                    "type": "string",
                    "description": "Tool name to get help for. Omit for full overview."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success — returns strategy preview and unsigned transaction"
          },
          "400": {
            "description": "Invalid parameters or business logic error"
          }
        }
      }
    },
    "/tools/learn": {
      "post": {
        "operationId": "learn",
        "summary": "Learn about Carbon DeFi concepts, protocol mechanics, and technical details",
        "tags": [
          "Help"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [],
                "properties": {
                  "topic": {
                    "type": "string",
                    "description": "Topic to learn about. Omit for full topic index."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success — returns strategy preview and unsigned transaction"
          },
          "400": {
            "description": "Invalid parameters or business logic error"
          }
        }
      }
    },
    "/tools/resolve_token": {
      "post": {
        "operationId": "resolve_token",
        "summary": "Resolve a token symbol or name to its on-chain address",
        "tags": [
          "Explore"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "chain",
                  "query"
                ],
                "properties": {
                  "chain": {
                    "type": "string",
                    "enum": [
                      "ethereum",
                      "sei",
                      "celo",
                      "tac"
                    ]
                  },
                  "query": {
                    "type": "string",
                    "description": "Token symbol or name, e.g. 'USDC', 'ETH', 'wrapped ether'"
                  },
                  "limit": {
                    "type": "number",
                    "description": "Max results (default 5)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success — returns strategy preview and unsigned transaction"
          },
          "400": {
            "description": "Invalid parameters or business logic error"
          }
        }
      }
    },
    "/tools/find_opportunities": {
      "post": {
        "operationId": "find_opportunities",
        "summary": "Find discount buy or premium sell opportunities on a token pair",
        "tags": [
          "Explore"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "chain",
                  "base_token",
                  "quote_token"
                ],
                "properties": {
                  "chain": {
                    "type": "string",
                    "enum": [
                      "ethereum",
                      "sei",
                      "celo",
                      "tac"
                    ]
                  },
                  "base_token": {
                    "type": "string"
                  },
                  "quote_token": {
                    "type": "string"
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "discount_buy",
                      "premium_sell",
                      "both"
                    ],
                    "description": "Default: both"
                  },
                  "top_n": {
                    "type": "number",
                    "description": "Max results per category (default 10)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success — returns strategy preview and unsigned transaction"
          },
          "400": {
            "description": "Invalid parameters or business logic error"
          }
        }
      }
    },
    "/tools/get_strategy": {
      "post": {
        "operationId": "get_strategy",
        "summary": "Look up any strategy by ID — type, status, owner, prices, budgets, trades",
        "tags": [
          "Explore"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "chain",
                  "strategy_id"
                ],
                "properties": {
                  "chain": {
                    "type": "string",
                    "enum": [
                      "ethereum",
                      "sei",
                      "celo",
                      "tac"
                    ]
                  },
                  "strategy_id": {
                    "type": "string",
                    "description": "Strategy ID to look up"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success — returns strategy preview and unsigned transaction"
          },
          "400": {
            "description": "Invalid parameters or business logic error"
          }
        }
      }
    },
    "/tools/get_protocol_stats": {
      "post": {
        "operationId": "get_protocol_stats",
        "summary": "Get protocol TVL, volume, and fees history",
        "tags": [
          "Explore"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "chain"
                ],
                "properties": {
                  "chain": {
                    "type": "string",
                    "enum": [
                      "ethereum",
                      "sei",
                      "celo",
                      "tac"
                    ]
                  },
                  "days": {
                    "type": "number",
                    "description": "Days to look back (default 30)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success — returns strategy preview and unsigned transaction"
          },
          "400": {
            "description": "Invalid parameters or business logic error"
          }
        }
      }
    },
    "/tools/get_price_history": {
      "post": {
        "operationId": "get_price_history",
        "summary": "Get historical OHLC price data for a token pair",
        "tags": [
          "Explore"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "chain",
                  "base_token",
                  "quote_token"
                ],
                "properties": {
                  "chain": {
                    "type": "string",
                    "enum": [
                      "ethereum",
                      "sei",
                      "celo",
                      "tac"
                    ]
                  },
                  "base_token": {
                    "type": "string"
                  },
                  "quote_token": {
                    "type": "string"
                  },
                  "days": {
                    "type": "number",
                    "description": "Days to look back (default 30)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success — returns strategy preview and unsigned transaction"
          },
          "400": {
            "description": "Invalid parameters or business logic error"
          }
        }
      }
    },
    "/tools/get_trade_quote": {
      "post": {
        "operationId": "get_trade_quote",
        "summary": "Get a swap quote against Carbon DeFi liquidity",
        "tags": [
          "Trade"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "chain",
                  "source_token",
                  "target_token",
                  "amount"
                ],
                "properties": {
                  "chain": {
                    "type": "string",
                    "enum": [
                      "ethereum",
                      "sei",
                      "celo",
                      "tac"
                    ]
                  },
                  "source_token": {
                    "type": "string"
                  },
                  "target_token": {
                    "type": "string"
                  },
                  "amount": {
                    "type": "number"
                  },
                  "by_target": {
                    "type": "boolean",
                    "description": "If true, amount is target amount to receive"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success — returns strategy preview and unsigned transaction"
          },
          "400": {
            "description": "Invalid parameters or business logic error"
          }
        }
      }
    },
    "/tools/execute_trade": {
      "post": {
        "operationId": "execute_trade",
        "summary": "Build an unsigned swap transaction against Carbon DeFi liquidity",
        "tags": [
          "Trade"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "chain",
                  "wallet_address",
                  "source_token",
                  "target_token",
                  "trade_actions",
                  "source_amount",
                  "target_amount"
                ],
                "properties": {
                  "chain": {
                    "type": "string",
                    "enum": [
                      "ethereum",
                      "sei",
                      "celo",
                      "tac"
                    ]
                  },
                  "wallet_address": {
                    "type": "string"
                  },
                  "source_token": {
                    "type": "string"
                  },
                  "target_token": {
                    "type": "string"
                  },
                  "trade_actions": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  },
                  "by_target": {
                    "type": "boolean"
                  },
                  "source_amount": {
                    "type": "number"
                  },
                  "target_amount": {
                    "type": "number"
                  },
                  "deadline_minutes": {
                    "type": "number"
                  },
                  "slippage_percent": {
                    "type": "number"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success — returns strategy preview and unsigned transaction"
          },
          "400": {
            "description": "Invalid parameters or business logic error"
          }
        }
      }
    }
  }
}