{
  "name": "Cowrie",
  "description": "Foreign exchange rates for autonomous agents, priced on Celo via the Mento protocol.",
  "version": "0.4.1",
  "pricing": {
    "reads": "free — /, /currencies, /pairs, /status, /quote, /errors, /openapi.json",
    "POST /swap": "0.001 USD per call, paid over x402 in USDC or USD₮ on Celo. No account or API key; the 402 response carries the payment options."
  },
  "chain": {
    "name": "Celo",
    "chain_id": 42220
  },
  "agent_id": 9796,
  "agent_card": "https://raw.githubusercontent.com/olanrewajuakeem/cowrie/main/agent-card.json",
  "endpoints": {
    "GET /": "This description. Returns an HTML page to browsers.",
    "GET /openapi.json": "OpenAPI 3.1 description of this API.",
    "GET /errors": "Every error this API can return, with an example payload and how to handle it.",
    "GET /proof": "Mined Celo mainnet transactions built by this API, so its claims can be checked rather than trusted.",
    "GET /healthz": "Standard health check: version, uptime, market state, cache backend.",
    "GET /balance/{address}": "Every non-zero balance that address holds across the currencies Cowrie knows, so an agent can check it can afford a swap before planning one.",
    "GET /currencies": "Every supported currency with its ISO code and on-chain address.",
    "GET /pairs": "Which pairs are quotable right now, and which are waiting on market hours.",
    "GET /status": "FX market state and service health.",
    "GET /quote?from=USD&to=NGN&amount=100": "Price an amount from one currency into another.",
    "POST /swap": "Build unsigned transactions that execute a conversion. Body: {from, to, amount, recipient}. Returns approval (when needed) and swap calldata with feeCurrency preset, so an agent holding no CELO can still settle."
  },
  "example": "/quote?from=USD&to=NGN&amount=100",
  "attribution_tag": "celo_e46217d1e056",
  "notes": [
    "Currencies accept ISO 4217 codes (USD, NGN) or Mento symbols (USDm, NGNm).",
    "Global FX markets close Friday 21:00 UTC and reopen Sunday 21:00 UTC. While closed, quotes return code \"market_closed\" with retry_after in seconds and, where known, the last observed rate.",
    "Dollar-denominated pairs (USD, USDC, USDT, axlUSDC) cross no exchange rate and are quotable at any hour."
  ],
  "live_proof": {
    "note": "Both computed when you requested this, not static examples. Reproduce them by calling /quote yourself.",
    "computed_in_ms": 993,
    "always_on_pair": {
      "request": "GET /quote?from=USD&to=USDC&amount=100",
      "why": "Dollar-to-dollar crosses no exchange rate, so it prices at any hour including weekends.",
      "result": {
        "from": "USD",
        "to": "USDC",
        "amount_in": "100",
        "amount_out": "99.995191",
        "rate": 0.99995191,
        "inverse_rate": 1.0000480923127593,
        "cost_percent": 0.02,
        "route": [
          "USD",
          "USDC"
        ],
        "as_of": "2026-09-13T19:29:12.496Z",
        "max_age_seconds": 300,
        "expires_at": "2026-09-13T19:34:12.496Z",
        "limits": {
          "max_amount_in": "500000",
          "max_amount_out": "500000",
          "circuit_breaker_ok": true,
          "note": "Mento's own caps for this pool, in whole units of each currency. Exceeding max_amount_in (USD) or max_amount_out (USDC) makes the swap revert."
        },
        "market": {
          "open": true,
          "source": "observed",
          "closes_at": "2026-09-18T21:00:00.000Z"
        }
      }
    },
    "oracle_priced_pair": {
      "request": "GET /quote?from=USD&to=NGN&amount=100",
      "why": "Needs an FX oracle. At weekends this returns a documented market_closed error with a retry window — the error contract working, not a fault.",
      "error": {
        "code": "rate_unavailable",
        "message": "No oracle price is currently available for USD/NGN. Other pairs are pricing, so this is specific to this feed rather than a market-wide closure.",
        "detail": "The contract function \"getAmountsOut\" reverted with the following reason: no valid median",
        "retry_after": 60
      }
    }
  }
}