{"openapi":"3.1.0","info":{"title":"MPP Funding-Rate Decision API","version":"0.1.0","description":"Paid funding-rate decision API for AI trading agents. Paid routes require an MPP payment receipt; unpaid requests receive a 402 challenge that lists the per-route price.","x-guidance":"Funding-rate data for AI trading agents across Bybit and Hyperliquid perpetuals. Call GET /v1/funding/current for the latest normalized funding rate per venue, /v1/funding/arbitrage for ranked cross-venue spread opportunities, and /v1/funding/summary/{symbol} for a deep dive on one symbol. Each call returns 402 Payment Required with an MPP challenge; satisfy the challenge with `tempo` (USD) per `x-payment-info` and replay the request with the receipt as `Authorization: Payment <receipt>`. Responses follow a `{ data, meta, warnings }` envelope; check `warnings` for stale-source signals before acting on data."},"servers":[{"url":"https://funding-rates.data-mpp.cloud","description":"Public base URL for this service."}],"paths":{"/v1/funding/current":{"get":{"operationId":"getCurrentFunding","summary":"Current funding rates across supported venues.","description":"Returns the latest normalized funding rate for each requested symbol on each venue.","security":[{"mppPayment":[]}],"parameters":[{"name":"symbols","in":"query","required":false,"description":"Comma-separated list of normalized symbols (e.g. `BTC-USDT,ETH-USDT`). Omit to receive all supported symbols.","schema":{"type":"string"},"example":"BTC-USDT,ETH-USDT"},{"name":"venues","in":"query","required":false,"description":"Comma-separated list of venues to include. Currently supported: `bybit`, `hyperliquid`. Omit for all.","schema":{"type":"string","pattern":"^(bybit|hyperliquid)(,(bybit|hyperliquid))*$"},"example":"bybit,hyperliquid"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.01"},"protocols":[{"mpp":{"method":"tempo","intent":"charge","currency":"USD"}}]},"x-mpp-payment":{"scope":"funding-current","amount":"0.01","currency":"USD","method":"tempo","intent":"charge"},"responses":{"200":{"description":"Paid response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurrentFundingResponse"}}}},"402":{"description":"Payment Required","headers":{"WWW-Authenticate":{"description":"MPP Payment challenge header.","schema":{"type":"string"}},"Cache-Control":{"description":"Always `no-store` on 402 responses.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredResponse"},"example":{"data":{"required":true,"scope":"funding-current","realm":"funding-rates.data-mpp.cloud","amount":"0.01","currency":"USD","method":"tempo","intent":"charge"},"meta":{"source":{"service":"funding-rates","feature":"payment"}},"warnings":["payment_required"]}}}}}}},"/v1/funding/arbitrage":{"get":{"operationId":"getFundingArbitrage","summary":"Cross-venue funding arbitrage opportunities.","description":"Returns ranked arbitrage opportunities computed from current funding rates across supported venues.","security":[{"mppPayment":[]}],"parameters":[{"name":"minAnnualizedSpread","in":"query","required":false,"description":"Minimum annualized spread (decimal, e.g. `0.05` for 5%). Opportunities below this threshold are filtered out.","schema":{"type":"number","minimum":0},"example":"0.05"},{"name":"symbols","in":"query","required":false,"description":"Comma-separated list of normalized symbols (e.g. `BTC-USDT,ETH-USDT`). Omit to receive all supported symbols.","schema":{"type":"string"},"example":"BTC-USDT,ETH-USDT"},{"name":"venues","in":"query","required":false,"description":"Comma-separated list of venues to include. Currently supported: `bybit`, `hyperliquid`. Omit for all.","schema":{"type":"string","pattern":"^(bybit|hyperliquid)(,(bybit|hyperliquid))*$"},"example":"bybit,hyperliquid"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.05"},"protocols":[{"mpp":{"method":"tempo","intent":"charge","currency":"USD"}}]},"x-mpp-payment":{"scope":"funding-arbitrage","amount":"0.05","currency":"USD","method":"tempo","intent":"charge"},"responses":{"200":{"description":"Paid response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FundingArbitrageResponse"}}}},"402":{"description":"Payment Required","headers":{"WWW-Authenticate":{"description":"MPP Payment challenge header.","schema":{"type":"string"}},"Cache-Control":{"description":"Always `no-store` on 402 responses.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredResponse"},"example":{"data":{"required":true,"scope":"funding-arbitrage","realm":"funding-rates.data-mpp.cloud","amount":"0.05","currency":"USD","method":"tempo","intent":"charge"},"meta":{"source":{"service":"funding-rates","feature":"payment"}},"warnings":["payment_required"]}}}}}}},"/v1/funding/summary/{symbol}":{"get":{"operationId":"getFundingSummary","summary":"Funding summary for a single symbol.","description":"Returns a per-venue funding summary for a single normalized symbol, including the latest rate and annualized rate.","security":[{"mppPayment":[]}],"parameters":[{"name":"symbol","in":"path","required":true,"description":"Normalized symbol (e.g. `BTC-USDT`).","schema":{"type":"string","minLength":1},"example":"BTC-USDT"},{"name":"venues","in":"query","required":false,"description":"Comma-separated list of venues to include. Currently supported: `bybit`, `hyperliquid`. Omit for all.","schema":{"type":"string","pattern":"^(bybit|hyperliquid)(,(bybit|hyperliquid))*$"},"example":"bybit,hyperliquid"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.01"},"protocols":[{"mpp":{"method":"tempo","intent":"charge","currency":"USD"}}]},"x-mpp-payment":{"scope":"funding-summary","amount":"0.01","currency":"USD","method":"tempo","intent":"charge"},"responses":{"200":{"description":"Paid response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FundingSummaryResponse"}}}},"402":{"description":"Payment Required","headers":{"WWW-Authenticate":{"description":"MPP Payment challenge header.","schema":{"type":"string"}},"Cache-Control":{"description":"Always `no-store` on 402 responses.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredResponse"},"example":{"data":{"required":true,"scope":"funding-summary","realm":"funding-rates.data-mpp.cloud","amount":"0.01","currency":"USD","method":"tempo","intent":"charge"},"meta":{"source":{"service":"funding-rates","feature":"payment"}},"warnings":["payment_required"]}}}}}}},"/health":{"get":{"operationId":"getHealth","summary":"Service health and per-venue cache freshness.","security":[],"responses":{"200":{"description":"Service is healthy."},"503":{"description":"Cache is unreachable or sources are stale."}}}},"/metrics":{"get":{"operationId":"getMetrics","summary":"Per-route request metrics snapshot.","security":[],"responses":{"200":{"description":"Snapshot of per-route counters and latency histograms."}}}},"/openapi.json":{"get":{"operationId":"getOpenApiSpec","summary":"OpenAPI 3.1 specification for this service.","security":[],"responses":{"200":{"description":"OpenAPI 3.1 document."}}}}},"components":{"schemas":{"FundingVenue":{"type":"string","enum":["bybit","hyperliquid"]},"FundingApiWarningCode":{"type":"string","enum":["source_missing","source_stale","source_refresh_failed","unsupported_symbol","unsupported_venue","unmatched_filter","source_unavailable","insufficient_venues","interval_mismatch","fees_not_included","no_opportunity","invalid_min_annualized_spread"]},"FundingSource":{"type":"object","required":["venue","endpoint","fetchedAt"],"properties":{"venue":{"$ref":"#/components/schemas/FundingVenue"},"endpoint":{"type":"string"},"fetchedAt":{"type":"number","description":"Unix epoch milliseconds."}}},"NormalizedFundingRecord":{"type":"object","required":["venue","symbol","baseAsset","quoteAsset","instrumentId","fundingRate","annualizedRate","fundingIntervalHours","nextFundingTime","fetchedAt","markPrice","source","warnings"],"properties":{"venue":{"$ref":"#/components/schemas/FundingVenue"},"symbol":{"type":"string"},"baseAsset":{"type":"string"},"quoteAsset":{"type":"string"},"instrumentId":{"type":"string"},"fundingRate":{"type":"number","description":"Per-interval funding rate (decimal)."},"annualizedRate":{"type":"number","description":"Annualized funding rate (decimal)."},"fundingIntervalHours":{"type":"number","minimum":0},"nextFundingTime":{"type":["number","null"],"description":"Unix epoch ms of next funding payment, or null if unknown."},"fetchedAt":{"type":"number","description":"Unix epoch milliseconds."},"markPrice":{"type":["number","null"]},"source":{"$ref":"#/components/schemas/FundingSource"},"warnings":{"type":"array","items":{"type":"string"}},"raw":{"type":"object","additionalProperties":true}}},"FundingSourceStatus":{"type":"object","required":["lastFetchedAt","nextExpectedUpdate","lastFailureAt","lastFailureCode"],"properties":{"lastFetchedAt":{"type":"number"},"nextExpectedUpdate":{"type":["number","null"]},"lastFailureAt":{"type":["number","null"]},"lastFailureCode":{"type":["string","null"]}}},"FundingApiRecord":{"type":"object","required":["venue","symbol","record","sourceStatus","warnings"],"properties":{"venue":{"$ref":"#/components/schemas/FundingVenue"},"symbol":{"type":"string"},"record":{"$ref":"#/components/schemas/NormalizedFundingRecord"},"sourceStatus":{"$ref":"#/components/schemas/FundingSourceStatus"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/FundingApiWarningCode"}}}},"ResponseMeta":{"type":"object","required":["timestamp","source"],"properties":{"timestamp":{"type":"string","format":"date-time"},"source":{"type":"object","required":["service"],"properties":{"service":{"type":"string","const":"funding-rates"},"feature":{"type":"string"},"version":{"type":"string"}}}}},"CurrentFundingResponse":{"type":"object","required":["data","meta","warnings"],"properties":{"data":{"type":"object","required":["records"],"properties":{"records":{"type":"array","items":{"$ref":"#/components/schemas/FundingApiRecord"}}}},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"warnings":{"type":"array","items":{"type":"string"}},"raw":{"type":"object","additionalProperties":true}}},"ArbitrageLeg":{"type":"object","required":["venue","side"],"properties":{"venue":{"$ref":"#/components/schemas/FundingVenue"},"side":{"type":"string","enum":["long","short"]}}},"ArbitrageOpportunity":{"type":"object","required":["symbol","annualizedSpread","fundingRateSpread","recommendation","confidence","warnings","records"],"properties":{"symbol":{"type":"string"},"annualizedSpread":{"type":"number"},"fundingRateSpread":{"type":"number"},"recommendation":{"type":"object","required":["legs"],"properties":{"legs":{"type":"array","minItems":2,"items":{"$ref":"#/components/schemas/ArbitrageLeg"}}}},"confidence":{"type":"string","enum":["high","medium","low"]},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/FundingApiWarningCode"}},"records":{"type":"array","minItems":2,"items":{"$ref":"#/components/schemas/FundingApiRecord"}}}},"FundingArbitrageResponse":{"type":"object","required":["data","meta","warnings"],"properties":{"data":{"type":"object","required":["opportunities"],"properties":{"opportunities":{"type":"array","items":{"$ref":"#/components/schemas/ArbitrageOpportunity"}}}},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"warnings":{"type":"array","items":{"type":"string"}},"raw":{"type":"object","additionalProperties":true}}},"FundingSummaryResponse":{"type":"object","required":["data","meta","warnings"],"properties":{"data":{"type":"object","required":["symbol","records","summary","highestAnnualizedVenue","lowestAnnualizedVenue","annualizedSpread","fundingRateSpread","venueCount"],"properties":{"symbol":{"type":"string"},"records":{"type":"array","items":{"$ref":"#/components/schemas/FundingApiRecord"}},"summary":{"type":"string"},"highestAnnualizedVenue":{"oneOf":[{"$ref":"#/components/schemas/FundingVenue"},{"type":"null"}]},"lowestAnnualizedVenue":{"oneOf":[{"$ref":"#/components/schemas/FundingVenue"},{"type":"null"}]},"annualizedSpread":{"type":["number","null"]},"fundingRateSpread":{"type":["number","null"]},"venueCount":{"type":"number"}}},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"warnings":{"type":"array","items":{"type":"string"}},"raw":{"type":"object","additionalProperties":true}}},"PaymentChallenge":{"type":"object","required":["required","scope","realm","amount","currency","method","intent"],"properties":{"required":{"type":"boolean","const":true},"scope":{"type":"string","enum":["funding-current","funding-arbitrage","funding-summary"]},"realm":{"type":"string"},"amount":{"type":"string"},"currency":{"type":"string"},"method":{"type":"string","const":"tempo"},"intent":{"type":"string","const":"charge"}}},"PaymentRequiredResponse":{"type":"object","required":["data","meta","warnings"],"properties":{"data":{"$ref":"#/components/schemas/PaymentChallenge"},"meta":{"type":"object"},"warnings":{"type":"array","items":{"type":"string"}}}}},"securitySchemes":{"mppPayment":{"type":"http","scheme":"Payment","description":"MPP payment receipt. Send the Authorization header returned from a prior 402 challenge. Local development accepts `Authorization: Payment test-paid` when `MPP_MODE=fake`."}}}}