{
  "openapi": "3.1.0",
  "info": {
    "title": "Rampa — LATAM stablecoin cash-out & FX intelligence",
    "version": "1.0.0",
    "summary": "Pay-per-request market data for moving stablecoins into Latin American local currency.",
    "description": "Rampa answers a concrete question for anyone (human or agent) moving money in Latin America: given an amount, a stablecoin and a country, what is the best net way to turn it into local currency, and what does it really cost? Data comes directly from exchange APIs (Bitso, Buda, SatoshiTango, Lemon, Ripio Trade, Mercado Bitcoin, Foxbit) plus Binance P2P where the market is genuinely peer-to-peer, cross-checked against local and international references. Every quote is labelled with its market type and a confidence level.\n\nPayment: the /v1/* endpoints are paid per request via the x402 protocol on Algorand (USDC). Call the endpoint, receive HTTP 402 with payment requirements, pay with an x402 client, retry with the X-PAYMENT header. No account, no API key, no subscription.",
    "contact": { "url": "https://rampa-x402-production.up.railway.app" },
    "x-payment": {
      "protocol": "x402",
      "network": "algorand-mainnet",
      "asset": "USDC",
      "facilitator": "https://facilitator.goplausible.xyz",
      "signupRequired": false
    }
  },
  "servers": [{ "url": "https://rampa-x402-production.up.railway.app" }],
  "tags": [
    { "name": "paid", "description": "Pay-per-request endpoints (x402 on Algorand)" },
    { "name": "free", "description": "Free endpoints, no payment required" }
  ],
  "paths": {
    "/v1/route": {
      "get": {
        "tags": ["paid"],
        "summary": "Best net cash-out route for a stablecoin into LATAM local currency",
        "description": "Given an amount, a stablecoin and a country, returns the exchange that leaves you the most local currency after fees, plus ranked alternatives. Use when deciding where to sell stablecoins for local money. Price: $0.05 USDC.",
        "operationId": "getBestRoute",
        "parameters": [
          { "name": "amount", "in": "query", "required": true, "schema": { "type": "number", "example": 1000 }, "description": "Amount of the stablecoin to sell" },
          { "name": "asset", "in": "query", "schema": { "type": "string", "enum": ["USDC", "USDT", "DAI", "BTC", "ETH"], "default": "USDC" } },
          { "name": "country", "in": "query", "required": true, "schema": { "type": "string", "enum": ["AR", "BO", "BR", "CL", "CO", "DO", "MX", "PE", "PY", "UY", "VE"] } }
        ],
        "responses": {
          "200": { "description": "Best route and alternatives", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RouteResult" } } } },
          "402": { "description": "Payment required — pay $0.05 USDC via x402 and retry with X-PAYMENT header" }
        }
      }
    },
    "/v1/spread": {
      "get": {
        "tags": ["paid"],
        "summary": "Buy/sell spread per exchange and cross-exchange arbitrage",
        "description": "Cheapest place to buy, best place to sell, the cross spread between them and per-exchange spreads ranked tightest-first. Use to assess trading costs or spot arbitrage. Price: $0.03 USDC.",
        "operationId": "getSpread",
        "parameters": [
          { "name": "country", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "asset", "in": "query", "schema": { "type": "string", "default": "USDC" } }
        ],
        "responses": { "200": { "description": "Spread analysis" }, "402": { "description": "Payment required — $0.03 USDC" } }
      }
    },
    "/v1/yields": {
      "get": {
        "tags": ["paid"],
        "summary": "Best APY to hold an asset, CeFi and DeFi compared",
        "description": "Ranked yield opportunities for parking an asset: exchange remunerated accounts (CeFi) and DeFi protocols side by side, with TVL and impermanent-loss risk. Use when deciding where to park idle funds. Price: $0.02 USDC.",
        "operationId": "getYields",
        "parameters": [
          { "name": "asset", "in": "query", "required": true, "schema": { "type": "string", "example": "USDC" } },
          { "name": "type", "in": "query", "schema": { "type": "string", "enum": ["all", "cefi", "defi"], "default": "all" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10, "maximum": 50 } }
        ],
        "responses": { "200": { "description": "Ranked yield offers" }, "402": { "description": "Payment required — $0.02 USDC" } }
      }
    },
    "/v1/fees": {
      "get": {
        "tags": ["paid"],
        "summary": "Withdrawal fees per exchange and network",
        "description": "Withdrawal cost for an asset across ~39 exchanges, broken down by network (Ethereum, Solana, Algorand, Tron, BSC, Polygon and more), ranked cheapest-first, plus taker trading fee where known. Use to minimise the real cost of moving funds off an exchange. Price: $0.02 USDC.",
        "operationId": "getFees",
        "parameters": [
          { "name": "asset", "in": "query", "required": true, "schema": { "type": "string", "example": "USDC" } },
          { "name": "network", "in": "query", "schema": { "type": "string", "example": "ALGORAND" }, "description": "Optional filter by withdrawal network" }
        ],
        "responses": { "200": { "description": "Fees per exchange and network" }, "402": { "description": "Payment required — $0.02 USDC" } }
      }
    },
    "/v1/rates": {
      "get": {
        "tags": ["paid"],
        "summary": "Normalized buy and sell quotes across all sources",
        "description": "Raw normalized quotes for a country and asset: bid, ask, and fee-adjusted totals per exchange, each labelled with market type. Use when you need the underlying data rather than a decision. Price: $0.01 USDC.",
        "operationId": "getRates",
        "parameters": [
          { "name": "country", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "asset", "in": "query", "schema": { "type": "string", "default": "USDC" } },
          { "name": "amount", "in": "query", "schema": { "type": "number", "default": 100 } }
        ],
        "responses": { "200": { "description": "Normalized quotes" }, "402": { "description": "Payment required — $0.01 USDC" } }
      }
    },
    "/demo": {
      "get": {
        "tags": ["free"],
        "summary": "Live headline rate for Argentina (free)",
        "description": "Free sample response showing the best USDC cash-out rate in Argentina right now. No payment required.",
        "operationId": "getDemo",
        "responses": { "200": { "description": "Headline rate" } }
      }
    },
    "/v1/countries": {
      "get": {
        "tags": ["free"],
        "summary": "Supported countries and assets",
        "operationId": "getCountries",
        "responses": { "200": { "description": "Coverage map" } }
      }
    },
    "/health": {
      "get": { "tags": ["free"], "summary": "Service status", "operationId": "getHealth", "responses": { "200": { "description": "OK" } } }
    }
  },
  "components": {
    "schemas": {
      "RouteResult": {
        "type": "object",
        "properties": {
          "country": { "type": "string" },
          "fiat": { "type": "string", "description": "Local currency code" },
          "asset": { "type": "string" },
          "amount": { "type": "number" },
          "best": { "$ref": "#/components/schemas/RouteOption" },
          "alternatives": { "type": "array", "items": { "$ref": "#/components/schemas/RouteOption" } },
          "confidence": { "type": "string", "enum": ["high", "medium", "low"], "description": "high = cross-checked against an independent reference or two independent exchange feeds" },
          "referenceRate": { "type": "number", "description": "Independent market reference used for cross-checking" },
          "global": { "type": "object", "description": "International anchor: global USD price and implied local FX rate", "properties": { "usdPrice": { "type": "number" }, "impliedFxRate": { "type": "number" }, "sources": { "type": "array", "items": { "type": "string" } } } },
          "sources": { "type": "array", "items": { "type": "string" } },
          "warnings": { "type": "array", "items": { "type": "string" } },
          "quotedAt": { "type": "string", "format": "date-time" }
        }
      },
      "RouteOption": {
        "type": "object",
        "properties": {
          "exchange": { "type": "string" },
          "marketType": { "type": "string", "enum": ["exchange", "broker", "p2p", "dex", "reference"], "description": "exchange = order book; broker = quoted price; p2p = peer marketplace; reference = market rate fallback" },
          "grossFiat": { "type": "number" },
          "withdrawalFee": { "type": "number" },
          "netFiat": { "type": "number", "description": "What actually reaches you after fees" },
          "effectiveRate": { "type": "number" }
        }
      }
    }
  }
}