{
  "openapi": "3.1.0",
  "info": {
    "title": "DexPaprika MCP Server API",
    "description": "Access comprehensive DeFi and cryptocurrency data across multiple blockchain networks. This API provides the same functionality as our MCP server but in OpenAPI format for platforms like ChatGPT Actions.",
    "version": "1.2.0",
    "contact": {
      "name": "DexPaprika Support",
      "url": "https://dexpaprika.com"
    }
  },
  "servers": [
    {
      "url": "https://mcp.dexpaprika.com",
      "description": "DexPaprika MCP Server (dexpaprika)"
    }
  ],
  "paths": {
    "/api/networks": {
      "get": {
        "summary": "Get Networks",
        "description": "REQUIRED FIRST STEP: Get all supported blockchain networks. Always call this first to see available networks before using any network-specific functions.",
        "operationId": "getNetworks",
        "responses": {
          "200": {
            "description": "List of supported blockchain networks",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "Network identifier"
                      },
                      "display_name": {
                        "type": "string",
                        "description": "Human-readable network name"
                      }
                    },
                    "required": [
                      "id",
                      "display_name"
                    ]
                  }
                }
              }
            }
          },
          "/api/capabilities": {
            "get": {
              "summary": "Get Capabilities",
              "description": "Return server capabilities, workflow patterns, network synonyms, common pitfalls, and best-practice sequences.",
              "operationId": "getCapabilities",
              "responses": {
                "200": {
                  "description": "Capabilities",
                  "content": {
                    "application/json": {
                      "schema": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/networks/{network}/pools": {
      "get": {
        "summary": "Get Network Pools",
        "description": "PRIMARY POOL FUNCTION: Get top liquidity pools on a specific network. This is the MAIN way to get pool data.",
        "operationId": "getNetworkPools",
        "parameters": [
          {
            "name": "network",
            "in": "path",
            "required": true,
            "description": "Network ID from getNetworks (e.g., 'ethereum', 'solana')",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "description": "Optional comma-separated list of top-level fields to include (e.g., 'pools,volume_usd').",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number for pagination (default: 1, 1-indexed)",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Number of items per page (default: 10, max: 100)",
            "schema": {
              "type": "integer",
              "default": 10,
              "maximum": 100
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sort order (default: 'desc')",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "desc"
            }
          },
          {
            "name": "order_by",
            "in": "query",
            "required": false,
            "description": "Field to order by (default: 'volume_usd')",
            "schema": {
              "type": "string",
              "enum": [
                "volume_usd",
                "price_usd",
                "transactions",
                "last_price_change_usd_24h",
                "created_at"
              ],
              "default": "volume_usd"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of liquidity pools",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pools": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "dex_name": {
                            "type": "string"
                          },
                          "chain": {
                            "type": "string"
                          },
                          "volume_usd": {
                            "type": "number"
                          },
                          "price_usd": {
                            "type": "number"
                          },
                          "transactions": {
                            "type": "integer"
                          },
                          "tokens": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "id": {
                                  "type": "string"
                                },
                                "name": {
                                  "type": "string"
                                },
                                "symbol": {
                                  "type": "string"
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    "page_info": {
                      "type": "object",
                      "properties": {
                        "limit": {
                          "type": "integer"
                        },
                        "page": {
                          "type": "integer"
                        },
                        "total_items": {
                          "type": "integer"
                        },
                        "total_pages": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/networks/{network}/dexes": {
      "get": {
        "summary": "Get Network DEXes",
        "description": "Get available DEXes on a specific network. First call getNetworks to see valid network IDs.",
        "operationId": "getNetworkDexes",
        "parameters": [
          {
            "name": "network",
            "in": "path",
            "required": true,
            "description": "Network ID from getNetworks (e.g., 'ethereum', 'solana')",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "description": "Optional comma-separated list of top-level fields to include.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number for pagination",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Number of items per page",
            "schema": {
              "type": "integer",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of DEXes on the network",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "dexes": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "dex_id": {
                            "type": "string"
                          },
                          "dex_name": {
                            "type": "string"
                          },
                          "chain": {
                            "type": "string"
                          },
                          "protocol": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/networks/{network}/dexes/{dex}/pools": {
      "get": {
        "summary": "Get DEX Pools",
        "description": "Get pools from a specific DEX on a network. First use getNetworks, then getNetworkDexes to find valid DEX IDs.",
        "operationId": "getDexPools",
        "parameters": [
          {
            "name": "network",
            "in": "path",
            "required": true,
            "description": "Network ID from getNetworks",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "dex",
            "in": "path",
            "required": true,
            "description": "DEX identifier from getNetworkDexes (e.g., 'uniswap_v3')",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of pools from the DEX",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pools": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/networks/{network}/pools/{pool_address}": {
      "get": {
        "summary": "Get Pool Details",
        "description": "Get detailed information about a specific pool. Returns comprehensive pool data including tokens, prices, volume, and transaction metrics.",
        "operationId": "getPoolDetails",
        "parameters": [
          {
            "name": "network",
            "in": "path",
            "required": true,
            "description": "Network ID from getNetworks",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pool_address",
            "in": "path",
            "required": true,
            "description": "Pool address or identifier",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "inversed",
            "in": "query",
            "required": false,
            "description": "Whether to invert the price ratio",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Detailed pool information",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "chain": {
                      "type": "string"
                    },
                    "dex_name": {
                      "type": "string"
                    },
                    "tokens": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "symbol": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "last_price_usd": {
                      "type": "number"
                    },
                    "volume_usd": {
                      "type": "number"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/api/networks/{network}/pools/{pool_address}/ohlcv": {
      "get": {
        "summary": "Get Pool OHLCV",
        "description": "Get historical price data (OHLCV) for a pool - essential for price analysis, backtesting, and visualization.",
        "operationId": "getPoolOHLCV",
        "parameters": [
          {
            "name": "network",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pool_address",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "start",
            "in": "query",
            "required": true,
            "description": "Start time for historical data (Unix timestamp, RFC3339 timestamp, or yyyy-mm-dd format)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "end",
            "in": "query",
            "required": false,
            "description": "End time for historical data",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Number of data points to retrieve",
            "schema": {
              "type": "integer",
              "default": 1,
              "maximum": 366
            }
          },
          {
            "name": "interval",
            "in": "query",
            "required": false,
            "description": "Interval granularity",
            "schema": {
              "type": "string",
              "enum": [
                "1m",
                "5m",
                "10m",
                "15m",
                "30m",
                "1h",
                "6h",
                "12h",
                "24h"
              ],
              "default": "24h"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Historical OHLCV data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "timestamp": {
                        "type": "string"
                      },
                      "open": {
                        "type": "number"
                      },
                      "high": {
                        "type": "number"
                      },
                      "low": {
                        "type": "number"
                      },
                      "close": {
                        "type": "number"
                      },
                      "volume": {
                        "type": "number"
                      }
                    },
                    "additionalProperties": true
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/networks/{network}/pools/{pool_address}/transactions": {
      "get": {
        "summary": "Get Pool Transactions",
        "description": "Get recent transactions for a specific pool. Shows swaps, adds, removes with detailed transaction data.",
        "operationId": "getPoolTransactions",
        "parameters": [
          {
            "name": "network",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "pool_address",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of pool transactions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "transaction_hash": {
                        "type": "string"
                      },
                      "type": {
                        "type": "string"
                      },
                      "amount_usd": {
                        "type": "number"
                      },
                      "timestamp": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": true
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/networks/{network}/tokens/{token_address}": {
      "get": {
        "summary": "Get Token Details",
        "description": "Get detailed information about a specific token on a network. Returns token metadata, current price, FDV, liquidity, and trading metrics.",
        "operationId": "getTokenDetails",
        "parameters": [
          {
            "name": "network",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "token_address",
            "in": "path",
            "required": true,
            "description": "Token contract address",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Detailed token information",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "symbol": {
                      "type": "string"
                    },
                    "chain": {
                      "type": "string"
                    },
                    "last_price_usd": {
                      "type": "number"
                    },
                    "market_cap_usd": {
                      "type": "number"
                    },
                    "volume_usd": {
                      "type": "number"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/api/networks/{network}/tokens/{token_address}/pools": {
      "get": {
        "summary": "Get Token Pools",
        "description": "Get liquidity pools containing a specific token on a network. Great for finding where a token is traded.",
        "operationId": "getTokenPools",
        "parameters": [
          {
            "name": "network",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "token_address",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of pools containing the token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "chain": {
                        "type": "string"
                      },
                      "dex_name": {
                        "type": "string"
                      },
                      "last_price_usd": {
                        "type": "number"
                      },
                      "volume_usd": {
                        "type": "number"
                      }
                    },
                    "additionalProperties": true
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/networks/{network}/multi/prices": {
      "get": {
        "summary": "Get Token Multi Prices",
        "description": "Get batched prices for multiple tokens on a network. The 'tokens' query param is a single comma-separated list (style=form, explode=false). Max 10 tokens. Unknown/unpriced tokens are omitted.",
        "operationId": "getTokenMultiPrices",
        "parameters": [
          {
            "name": "network",
            "in": "path",
            "required": true,
            "description": "Network ID from getNetworks",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tokens",
            "in": "query",
            "required": true,
            "description": "Comma-separated token addresses (max 10). style=form, explode=false",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "maxItems": 10
            },
            "style": "form",
            "explode": false
          }
        ],
        "responses": {
          "200": {
            "description": "Array of token prices",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "chain": {
                        "type": "string"
                      },
                      "price_usd": {
                        "type": "number"
                      }
                    },
                    "additionalProperties": true
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request: invalid query or too many tokens.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                },
                "examples": {
                  "invalid": {
                    "value": {
                      "error": "invalid query param"
                    }
                  },
                  "maxExceeded": {
                    "value": {
                      "error": "max 10 tokens allowed."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/search": {
      "get": {
        "summary": "Search",
        "description": "Search across ALL networks for tokens, pools, and DEXes by name, symbol, or address. Good starting point when you don't know the specific network.",
        "operationId": "search",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "description": "Search term (e.g., 'uniswap', 'bitcoin', 'ethereum', or a token address)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tokens": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "symbol": {
                            "type": "string"
                          },
                          "chain": {
                            "type": "string"
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "pools": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "dexes": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/api/stats": {
      "get": {
        "summary": "Get Stats",
        "description": "Get high-level statistics about the DexPaprika ecosystem: total networks, DEXes, pools, and tokens available.",
        "operationId": "getStats",
        "responses": {
          "200": {
            "description": "Platform statistics",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "networks": {
                      "type": "number"
                    },
                    "dexes": {
                      "type": "number"
                    },
                    "pools": {
                      "type": "number"
                    },
                    "tokens": {
                      "type": "number"
                    },
                    "total_volume_usd": {
                      "type": "number"
                    },
                    "total_liquidity_usd": {
                      "type": "number"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    }
  }
}