{"openapi":"3.1.0","info":{"title":"CarryLens API","version":"0.3.0","description":"Live, cost-aware cross-venue perpetual-funding screens for trading agents. Per-call x402 or anonymous 30-day bearer access from $9.","x-guidance":"Call GET /v1/perps/preview for free proof. For paid analysis, choose notionalUsd per matched leg, holdingHours, and totalCostBps; then call pulse for three pairs, radar for fifteen, or report for regime and risk context. Treat projected net funding as a screen, not guaranteed profit.","contact":{"url":"https://carry-lens-api.vercel.app"}},"servers":[{"url":"https://carry-lens-api.vercel.app"}],"tags":[{"name":"free","description":"No-payment discovery and product proof."},{"name":"paid","description":"x402-protected Base USDC resources."},{"name":"subscriptions","description":"Anonymous 30-day API access paid in Base USDC; manual renewal."}],"paths":{"/v1/perps/preview":{"get":{"tags":["free"],"security":[],"summary":"Free live carry teaser","description":"Shows the top current venue pair with midpoint-referenced two-leg entry slippage, point-in-time notional sensitivity, snapshot timing, and side-by-side instantaneous and descriptive 24-hour rolling-mean economics when supported.","parameters":[{"name":"notionalUsd","description":"Matched USD notional on each hedged leg.","schema":{"type":"number","minimum":100,"maximum":100000000,"default":10000},"in":"query","required":false},{"name":"holdingHours","description":"Expected time the matched position remains open.","schema":{"type":"number","minimum":1,"maximum":2160,"default":168},"in":"query","required":false},{"name":"totalCostBps","description":"Caller-supplied hard ceiling for all-in entry and planned-exit fees plus slippage, against one leg's notional; not auto-scaled with spread or volatility.","schema":{"type":"number","minimum":0,"maximum":2000,"default":20},"in":"query","required":false}],"responses":{"200":{"description":"Live teaser.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid cost assumptions."}}}},"/v1/perps/pulse":{"get":{"tags":["paid"],"summary":"Cost-aware carry pulse","description":"Three ranked venue pairs with projected gross, assumed costs, projected net funding, break-even time, liquidity tier, and benchmark context.","operationId":"cost-aware_carry_pulse","parameters":[{"name":"notionalUsd","description":"Matched USD notional on each hedged leg.","schema":{"type":"number","minimum":100,"maximum":100000000,"default":10000},"in":"query","required":false},{"name":"holdingHours","description":"Expected time the matched position remains open.","schema":{"type":"number","minimum":1,"maximum":2160,"default":168},"in":"query","required":false},{"name":"totalCostBps","description":"Caller-supplied hard ceiling for all-in entry and planned-exit fees plus slippage, against one leg's notional; not auto-scaled with spread or volatility.","schema":{"type":"number","minimum":0,"maximum":2000,"default":20},"in":"query","required":false}],"responses":{"200":{"description":"Fresh cost-aware perpetual-funding analysis.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid cost assumptions; no payment is requested.","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required. Requirements are encoded in Payment-Required.","headers":{"Payment-Required":{"description":"Base64-encoded x402 v2 payment requirements.","schema":{"type":"string"}}}},"502":{"description":"Fresh upstream data could not be produced."}},"security":[{"x402":[]},{"subscriptionBearer":[]}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.003000"},"protocols":[{"x402":{}}]}}},"/v1/perps/radar":{"get":{"tags":["paid"],"summary":"Cross-venue carry radar","description":"Fifteen cost-aware opportunities across interval-normalized funding predictions.","operationId":"cross-venue_carry_radar","parameters":[{"name":"notionalUsd","description":"Matched USD notional on each hedged leg.","schema":{"type":"number","minimum":100,"maximum":100000000,"default":10000},"in":"query","required":false},{"name":"holdingHours","description":"Expected time the matched position remains open.","schema":{"type":"number","minimum":1,"maximum":2160,"default":168},"in":"query","required":false},{"name":"totalCostBps","description":"Caller-supplied hard ceiling for all-in entry and planned-exit fees plus slippage, against one leg's notional; not auto-scaled with spread or volatility.","schema":{"type":"number","minimum":0,"maximum":2000,"default":20},"in":"query","required":false}],"responses":{"200":{"description":"Fresh cost-aware perpetual-funding analysis.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid cost assumptions; no payment is requested.","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required. Requirements are encoded in Payment-Required.","headers":{"Payment-Required":{"description":"Base64-encoded x402 v2 payment requirements.","schema":{"type":"string"}}}},"502":{"description":"Fresh upstream data could not be produced."}},"security":[{"x402":[]},{"subscriptionBearer":[]}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]}}},"/v1/perps/report":{"get":{"tags":["paid"],"summary":"Carry risk report","description":"Cost-aware opportunities plus regime, breadth, basis, crowding, open interest, persistence, and risk flags.","operationId":"carry_risk_report","parameters":[{"name":"notionalUsd","description":"Matched USD notional on each hedged leg.","schema":{"type":"number","minimum":100,"maximum":100000000,"default":10000},"in":"query","required":false},{"name":"holdingHours","description":"Expected time the matched position remains open.","schema":{"type":"number","minimum":1,"maximum":2160,"default":168},"in":"query","required":false},{"name":"totalCostBps","description":"Caller-supplied hard ceiling for all-in entry and planned-exit fees plus slippage, against one leg's notional; not auto-scaled with spread or volatility.","schema":{"type":"number","minimum":0,"maximum":2000,"default":20},"in":"query","required":false}],"responses":{"200":{"description":"Fresh cost-aware perpetual-funding analysis.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid cost assumptions; no payment is requested.","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required. Requirements are encoded in Payment-Required.","headers":{"Payment-Required":{"description":"Base64-encoded x402 v2 payment requirements.","schema":{"type":"string"}}}},"502":{"description":"Fresh upstream data could not be produced."}},"security":[{"x402":[]},{"subscriptionBearer":[]}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.030000"},"protocols":[{"x402":{}}]}}},"/v1/subscriptions/starter":{"get":{"tags":["subscriptions"],"summary":"Purchase Starter 30-day access","description":"Pays once in Base USDC and returns an anonymous signed bearer token valid for 30 days. Starter covers pulse and radar. Renewal is manual.","operationId":"purchase_starter_subscription","responses":{"200":{"description":"Bearer token and 30-day subscription metadata.","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required. Requirements are encoded in Payment-Required.","headers":{"Payment-Required":{"description":"Base64-encoded x402 v2 payment requirements.","schema":{"type":"string"}}}},"503":{"description":"Subscription issuance is temporarily unavailable."}},"security":[{"x402":[]}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"9.000000"},"protocols":[{"x402":{}}]}}},"/v1/subscriptions/pro":{"get":{"tags":["subscriptions"],"summary":"Purchase Pro 30-day access","description":"Pays once in Base USDC and returns an anonymous signed bearer token valid for 30 days. Pro covers pulse, radar, and report. Renewal is manual.","operationId":"purchase_pro_subscription","responses":{"200":{"description":"Bearer token and 30-day subscription metadata.","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required. Requirements are encoded in Payment-Required.","headers":{"Payment-Required":{"description":"Base64-encoded x402 v2 payment requirements.","schema":{"type":"string"}}}},"503":{"description":"Subscription issuance is temporarily unavailable."}},"security":[{"x402":[]}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"19.000000"},"protocols":[{"x402":{}}]}}},"/v1/subscriptions/status":{"get":{"tags":["subscriptions"],"summary":"Check subscription status","description":"Validates a CarryLens bearer token without charging it.","security":[{"subscriptionBearer":[]}],"responses":{"200":{"description":"The subscription is active."},"401":{"description":"The bearer token is missing, invalid, or expired."}}}},"/health":{"get":{"tags":["free"],"security":[],"summary":"Health check","responses":{"200":{"description":"Service is running."}}}},"/.well-known/x402":{"get":{"tags":["free"],"security":[],"summary":"x402 resource manifest","responses":{"200":{"description":"Machine-readable x402 resource catalog."}}}}},"components":{"securitySchemes":{"x402":{"type":"apiKey","in":"header","name":"Payment-Signature","description":"x402 v2 exact-payment authorization. Make an unsigned request first to receive Payment-Required."},"subscriptionBearer":{"type":"http","scheme":"bearer","bearerFormat":"CarryLens cl1 token","description":"Anonymous 30-day access token returned by a Starter or Pro subscription purchase."}}}}