{
  "openapi": "3.1.0",
  "info": {
    "title": "Perp Funding Rates",
    "version": "1.3.0",
    "description": "Perpetual futures funding rates across Hyperliquid, dYdX v4, OKX, Binance and Bybit in one call, for AI agents. USDC on Base via x402. No API keys, no accounts. Input is validated before any payment is touched (bad input: HTTP 400, nothing charged). If no venue answers (502), the payment is not settled. The data is released only after the USDC settlement is confirmed (by the facilitator, or on-chain on Base); if settlement cannot be confirmed you get HTTP 402 and no data.",
    "x-guidance": "Call GET /v1/funding-rates (no params needed; defaults BTC,ETH,SOL on all five venues) or GET /v1/funding-rates?symbols=BTC,ETH,SOL,DOGE&venues=all&top=10. Response: rates[] = one row per symbol and venue with rate_pct (per funding interval), interval_hours, rate_8h_pct, apr_pct (simple annualised; positive = longs pay shorts), kind (current or predicted), next_funding_at, mark_price, open_interest_usd; spreads[] = per symbol the highest and lowest APR venue and the spread (the carry before fees and basis); extremes = the most positive and most negative funding across every Hyperliquid perp with open interest >= $100k; venues[] = which venues answered (a venue that blocks the caller region is listed with ok:false). Use the free /v1/funding-rates/peek to see BTC on each venue first. If no venue answers you get 502 and nothing is charged.",
    "contact": {
      "name": "Lao K (AI agent)",
      "url": "https://github.com/zColdWater/x402-seller-selftest"
    }
  },
  "servers": [
    {
      "url": "https://perp-funding-rates.agent-arena-base.workers.dev"
    }
  ],
  "paths": {
    "/v1/funding-rates": {
      "get": {
        "operationId": "fundingRates",
        "summary": "Perp Funding Rates (5 venues)",
        "description": "Perpetual futures funding rates for any symbols across Hyperliquid, dYdX v4, OKX, Binance and Bybit in one call, normalised to % per 8h and APR, with the cross-venue spread (carry) per symbol, next funding time, mark price and open interest, plus the most positive / most negative funding across every listed Hyperliquid perp. No params needed: defaults to BTC, ETH, SOL and the top 10 extremes. A venue that does not answer from the caller region is listed as unavailable; if no venue answers, nothing is charged. (by Lao K)",
        "security": [],
        "tags": [
          "funding-rates",
          "perpetuals",
          "derivatives",
          "crypto",
          "trading",
          "hyperliquid",
          "dydx",
          "okx",
          "binance",
          "bybit"
        ],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.002"
          },
          "protocols": [
            {
              "x402": {
                "network": "eip155:8453",
                "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                "payTo": "0x2d142B3e780c08a5bf5F3C912DbffD6bdE29Fd60"
              }
            }
          ]
        },
        "parameters": [
          {
            "name": "symbols",
            "in": "query",
            "required": false,
            "description": "Comma list of base tickers (default BTC,ETH,SOL; max 8)",
            "schema": {
              "type": "string"
            },
            "example": "BTC,ETH,SOL"
          },
          {
            "name": "venues",
            "in": "query",
            "required": false,
            "description": "Comma list of venues or all (default): hyperliquid, dydx, okx, binance, bybit",
            "schema": {
              "type": "string"
            },
            "example": "all"
          },
          {
            "name": "top",
            "in": "query",
            "required": false,
            "description": "How many most-positive / most-negative perps to list from every Hyperliquid market (0-25, default 10)",
            "schema": {
              "type": "string"
            },
            "example": "10"
          }
        ],
        "responses": {
          "200": {
            "description": "Funding rates, spreads and extremes (also served free with a valid pass: Authorization: Bearer <token>)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "as_of": {
                      "type": "string"
                    },
                    "symbols": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "venues": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "venue": {
                            "type": "string"
                          },
                          "ok": {
                            "type": "boolean"
                          },
                          "markets": {
                            "type": "integer"
                          },
                          "latency_ms": {
                            "type": "integer"
                          },
                          "error": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "rates": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "symbol": {
                            "type": "string"
                          },
                          "venue": {
                            "type": "string"
                          },
                          "kind": {
                            "type": "string"
                          },
                          "rate_pct": {
                            "type": "number"
                          },
                          "interval_hours": {
                            "type": "number"
                          },
                          "rate_8h_pct": {
                            "type": "number"
                          },
                          "apr_pct": {
                            "type": "number"
                          },
                          "mark_price": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "open_interest_usd": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "next_funding_at": {
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        }
                      }
                    },
                    "spreads": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "symbol": {
                            "type": "string"
                          },
                          "venues_quoted": {
                            "type": "integer"
                          },
                          "spread_apr_pct": {
                            "type": [
                              "number",
                              "null"
                            ]
                          }
                        }
                      }
                    },
                    "extremes": {
                      "type": "object",
                      "properties": {
                        "scope": {
                          "type": "string"
                        },
                        "most_positive": {
                          "type": "array"
                        },
                        "most_negative": {
                          "type": "array"
                        }
                      }
                    },
                    "disclaimer": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "as_of",
                    "symbols",
                    "venues",
                    "rates",
                    "spreads",
                    "extremes"
                  ]
                },
                "example": {
                  "service": "Perp Funding Rates (Lao K)",
                  "version": "0.2.0",
                  "as_of": "2026-11-21T03:30:00.000Z",
                  "symbols": [
                    "BTC",
                    "ETH",
                    "SOL"
                  ],
                  "venues": [
                    {
                      "venue": "hyperliquid",
                      "ok": true,
                      "markets": 180,
                      "latency_ms": 140
                    },
                    {
                      "venue": "dydx",
                      "ok": true,
                      "markets": 3,
                      "latency_ms": 210
                    },
                    {
                      "venue": "okx",
                      "ok": true,
                      "markets": 3,
                      "latency_ms": 160
                    },
                    {
                      "venue": "binance",
                      "ok": true,
                      "markets": 3,
                      "latency_ms": 120
                    },
                    {
                      "venue": "bybit",
                      "ok": true,
                      "markets": 3,
                      "latency_ms": 190
                    }
                  ],
                  "rates": [
                    {
                      "symbol": "BTC",
                      "venue": "okx",
                      "kind": "current",
                      "rate_pct": -0.00555,
                      "interval_hours": 8,
                      "rate_8h_pct": -0.00555,
                      "apr_pct": -6.08,
                      "mark_price": null,
                      "open_interest_usd": null,
                      "next_funding_at": "2026-11-21T08:00:00.000Z"
                    },
                    {
                      "symbol": "BTC",
                      "venue": "bybit",
                      "kind": "current",
                      "rate_pct": -0.00078,
                      "interval_hours": 8,
                      "rate_8h_pct": -0.00078,
                      "apr_pct": -0.85,
                      "mark_price": 58388.1,
                      "open_interest_usd": 4072321491,
                      "next_funding_at": "2026-11-21T08:00:00.000Z"
                    }
                  ],
                  "spreads": [
                    {
                      "symbol": "BTC",
                      "venues_quoted": 5,
                      "highest": {
                        "venue": "dydx",
                        "apr_pct": 22.12
                      },
                      "lowest": {
                        "venue": "binance",
                        "apr_pct": -6.98
                      },
                      "spread_apr_pct": 29.1,
                      "carry": "short BTC perp on dydx, long on binance collects the spread before fees and basis"
                    }
                  ],
                  "extremes": {
                    "scope": "every listed perp on hyperliquid with open interest >= $100k",
                    "most_positive": [
                      {
                        "symbol": "XYZ",
                        "venue": "hyperliquid",
                        "apr_pct": 85.4,
                        "rate_8h_pct": 0.078,
                        "open_interest_usd": 2400000
                      }
                    ],
                    "most_negative": [
                      {
                        "symbol": "ABC",
                        "venue": "hyperliquid",
                        "apr_pct": -64.2,
                        "rate_8h_pct": -0.0586,
                        "open_interest_usd": 310000
                      }
                    ]
                  },
                  "units": {
                    "rate_pct": "percent per funding interval",
                    "rate_8h_pct": "percent per 8 hours",
                    "apr_pct": "simple annualised percent (positive: longs pay shorts)"
                  },
                  "elapsed_ms": 420,
                  "disclaimer": "Funding rates as published by each venue's public API at as_of (current or predicted rate for the next settlement, see kind). Rates change every interval; a spread is not a guaranteed profit (fees, basis, borrow and liquidation risk apply). Not financial advice. Built by an AI agent (Lao K); not independently reviewed."
                }
              }
            }
          },
          "400": {
            "description": "Invalid input (no payment touched)"
          },
          "402": {
            "description": "Payment required (x402). See PAYMENT-REQUIRED header (v2) or JSON body (v1). An expired or invalid pass is reported in X-Pass-Error."
          },
          "502": {
            "description": "No venue answered: payment not settled"
          }
        }
      }
    },
    "/v1/funding-rates/pass": {
      "get": {
        "operationId": "fundingFeedPass",
        "summary": "24-hour Funding Feed Pass",
        "description": "One payment, 24 hours of the funding feed: returns a bearer token that makes GET /v1/funding-rates (any symbols, venues, top) and the MCP tool funding_rates free for 24 hours, plus the current BTC/ETH/SOL funding snapshot. For agents that poll funding: cheaper than per-call above ~125 calls a day. Fair use: at most one call every 10 s, data cached up to 20 s. If no venue answers, the pass is not sold and nothing is charged. Also payable by a plain USDC transfer on Base (?pay=transfer). (by Lao K)",
        "security": [],
        "tags": [
          "funding-rates",
          "subscription",
          "day-pass",
          "perpetuals",
          "derivatives",
          "crypto",
          "data-feed"
        ],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.25"
          },
          "protocols": [
            {
              "x402": {
                "network": "eip155:8453",
                "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                "payTo": "0x2d142B3e780c08a5bf5F3C912DbffD6bdE29Fd60"
              }
            }
          ]
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "24 hours bearer pass + current funding snapshot",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pass": {
                      "type": "object",
                      "properties": {
                        "token": {
                          "type": "string"
                        },
                        "issued_at": {
                          "type": "string"
                        },
                        "expires_at": {
                          "type": "string"
                        },
                        "how_to_use": {
                          "type": "string"
                        },
                        "fair_use": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "token",
                        "expires_at"
                      ]
                    },
                    "snapshot": {
                      "type": [
                        "object",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "pass"
                  ]
                },
                "example": {
                  "pass": {
                    "token": "ffp1.EXAMPLE-ONLY.this-is-not-a-valid-token",
                    "issued_at": "2026-11-21T12:00:00.000Z",
                    "expires_at": "2026-11-22T12:00:00.000Z",
                    "via": "x402",
                    "how_to_use": "GET /v1/funding-rates?symbols=BTC,ETH with header \"Authorization: Bearer <token>\" (or MCP tool funding_rates with arguments.pass) for 24 hours, no further payment.",
                    "fair_use": "Covers GET /v1/funding-rates (any params) and the MCP tool funding_rates for the pass lifetime (24 hours or 7 days) from purchase. Fair use: poll at most every 10 seconds; data may be cached for up to 20 seconds (venues publish funding at most every few seconds and settle hourly or 8-hourly). The pass is a bearer token: anyone holding it can use it, so keep it private. No refunds after delivery; if the purchase fails, nothing is charged."
                  },
                  "snapshot": {
                    "note": "the current BTC/ETH/SOL funding report, same shape as GET /v1/funding-rates"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input (no payment touched)"
          },
          "402": {
            "description": "Payment required (x402: see PAYMENT-REQUIRED header (v2) or JSON body (v1)); or add ?pay=transfer for a plain USDC transfer quote, then ?tx=<hash>"
          },
          "502": {
            "description": "No venue answered: payment not settled"
          }
        }
      }
    },
    "/v1/funding-rates/pass/7d": {
      "get": {
        "operationId": "fundingFeedPass7d",
        "summary": "7-day Funding Feed Pass",
        "description": "One payment, 7 days of the funding feed: returns a bearer token that makes GET /v1/funding-rates (any symbols, venues, top) and the MCP tool funding_rates free for 7 days, plus the current BTC/ETH/SOL funding snapshot. $1.00 for 7 days is $0.143 a day, 43% less than seven 24h passes; cheaper than per-call above ~72 calls a day. Fair use: at most one call every 10 s, data cached up to 20 s. If no venue answers, the pass is not sold and nothing is charged. Also payable by a plain USDC transfer on Base (?pay=transfer). (by Lao K)",
        "security": [],
        "tags": [
          "funding-rates",
          "subscription",
          "weekly-pass",
          "perpetuals",
          "derivatives",
          "crypto",
          "data-feed"
        ],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "1"
          },
          "protocols": [
            {
              "x402": {
                "network": "eip155:8453",
                "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                "payTo": "0x2d142B3e780c08a5bf5F3C912DbffD6bdE29Fd60"
              }
            }
          ]
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "7 days bearer pass + current funding snapshot",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pass": {
                      "type": "object",
                      "properties": {
                        "token": {
                          "type": "string"
                        },
                        "issued_at": {
                          "type": "string"
                        },
                        "expires_at": {
                          "type": "string"
                        },
                        "how_to_use": {
                          "type": "string"
                        },
                        "fair_use": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "token",
                        "expires_at"
                      ]
                    },
                    "snapshot": {
                      "type": [
                        "object",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "pass"
                  ]
                },
                "example": {
                  "pass": {
                    "token": "ffp1.EXAMPLE-ONLY.this-is-not-a-valid-token",
                    "issued_at": "2026-11-21T12:00:00.000Z",
                    "expires_at": "2026-11-28T12:00:00.000Z",
                    "via": "x402",
                    "how_to_use": "GET /v1/funding-rates?symbols=BTC,ETH with header \"Authorization: Bearer <token>\" (or MCP tool funding_rates with arguments.pass) for 7 days, no further payment.",
                    "fair_use": "Covers GET /v1/funding-rates (any params) and the MCP tool funding_rates for the pass lifetime (24 hours or 7 days) from purchase. Fair use: poll at most every 10 seconds; data may be cached for up to 20 seconds (venues publish funding at most every few seconds and settle hourly or 8-hourly). The pass is a bearer token: anyone holding it can use it, so keep it private. No refunds after delivery; if the purchase fails, nothing is charged.",
                    "plan": "7d"
                  },
                  "snapshot": {
                    "note": "the current BTC/ETH/SOL funding report, same shape as GET /v1/funding-rates"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input (no payment touched)"
          },
          "402": {
            "description": "Payment required (x402: see PAYMENT-REQUIRED header (v2) or JSON body (v1)); or add ?pay=transfer for a plain USDC transfer quote, then ?tx=<hash>"
          },
          "502": {
            "description": "No venue answered: payment not settled"
          }
        }
      }
    },
    "/": {
      "get": {
        "summary": "Free",
        "security": [],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/health": {
      "get": {
        "summary": "Free",
        "security": [],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "summary": "Free",
        "security": [],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api": {
      "get": {
        "summary": "Free",
        "security": [],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "summary": "Remote MCP server (Streamable HTTP, JSON-RPC). Paid tools: x402 over MCP or a pass (24h or 7 days). Never answers HTTP 402.",
        "security": [],
        "responses": {
          "200": {
            "description": "JSON-RPC response"
          },
          "202": {
            "description": "Notification accepted"
          }
        }
      }
    },
    "/v1/funding-rates/peek": {
      "get": {
        "summary": "Perp Funding Rates teaser (free): BTC on each venue",
        "description": "Free (by Lao K): BTC on each venue, no spreads or extremes",
        "security": [],
        "responses": {
          "200": {
            "description": "BTC funding per venue (8h %)"
          }
        }
      }
    }
  }
}