{ "openapi": "3.1.0", "info": { "title": "Flash Tokenized Perps API", "version": "1.0.0", "description": "Read-only market data and quotes for Flash Tokenized Perps on Base. For unsigned swap calldata and pairing info use the MCP server at https://api.tryflash.app/mcp (tools build_perp_swap and perp_pairing_info). Guide: https://tryflash.app/agents/flash-perps/SKILL.md" }, "servers": [ { "url": "https://api.tryflash.app" } ], "paths": { "/v1/perps": { "get": { "operationId": "listPerps", "summary": "List every perp market", "description": "Requests without an Origin header, or with Origin https://tryflash.app, are served. Other Origins receive 403.", "parameters": [ { "name": "account", "in": "query", "required": false, "description": "Wallet address; adds that wallet's balances under `wallet`.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } ], "responses": { "200": { "description": "The catalogue.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "chainId": { "type": "integer" }, "priceSource": { "type": "string", "examples": [ "morpho-nav" ] }, "refreshIntervalMs": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PerpMarket" } }, "updatedAt": { "type": "integer" } } } } } }, "403": { "description": "Origin not allowed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "examples": [ "UNKNOWN_PERP_MARKET" ] } } } } } } } } }, "/v1/perps/{token}": { "get": { "operationId": "getPerp", "summary": "Live snapshot of one market", "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Perp token address (preferred) or its vault address.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "account", "in": "query", "required": false, "description": "Wallet address; adds that wallet's balances under `wallet`.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } ], "responses": { "200": { "description": "One market.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PerpMarket" } } } }, "400": { "description": "UNKNOWN_PERP_MARKET or a malformed address.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "examples": [ "UNKNOWN_PERP_MARKET" ] } } } } } }, "403": { "description": "Origin not allowed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "examples": [ "UNKNOWN_PERP_MARKET" ] } } } } } } } } }, "/v1/perps/{token}/quote": { "get": { "operationId": "quotePerp", "summary": "Exact-input quote", "description": "buy: amount is USDC raw units (6 decimals), amountOut is perp tokens (18). sell: amount is perp tokens (18), amountOut is USDC (6). USDC pair only; for ETH quotes use the MCP quote_perp tool with asset=eth.", "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Perp token address (preferred) or its vault address.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "side", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "buy", "sell" ] } }, { "name": "amount", "in": "query", "required": true, "description": "Exact input in raw units, digits only, 1 to 2^128-1.", "schema": { "type": "string", "pattern": "^[0-9]+$" } } ], "responses": { "200": { "description": "A quote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PerpQuote" } } } }, "400": { "description": "UNKNOWN_PERP_MARKET, INVALID_PERP_SIDE, INVALID_PERP_AMOUNT, PERP_RECOVERY_BUY_DISABLED or NO_EXECUTABLE_PERP_ROUTE.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "examples": [ "UNKNOWN_PERP_MARKET" ] } } } } } }, "403": { "description": "Origin not allowed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "examples": [ "UNKNOWN_PERP_MARKET" ] } } } } } } } } }, "/mcp": { "post": { "operationId": "mcp", "summary": "MCP server (Streamable HTTP, JSON-RPC 2.0)", "description": "Stateless, JSON responses, any Origin. Methods: initialize, ping, tools/list, tools/call. Tools: list_perps, get_perp, quote_perp, build_perp_swap, perp_pairing_info. All read-only. 60 requests/min per client (a tools/call counts 3); 429 carries Retry-After.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "integer", "string" ] }, "method": { "type": "string", "examples": [ "tools/call" ] }, "params": { "type": "object", "examples": [ { "name": "quote_perp", "arguments": { "market": "ETH2xL", "side": "buy", "amount": "100" } } ] } } } } } }, "responses": { "200": { "description": "JSON-RPC response." }, "202": { "description": "Notification accepted, no body." }, "429": { "description": "Rate limited." } } } } }, "components": { "schemas": { "PerpMarket": { "type": "object", "additionalProperties": true, "description": "One market snapshot. Additional fields exist (capacity, wallet, lastRebalance, ...) and may be added.", "properties": { "chainId": { "type": "integer", "const": 8453 }, "generation": { "type": "string", "examples": [ "v3" ] }, "symbol": { "type": "string", "examples": [ "ETH2xL" ] }, "name": { "type": "string", "examples": [ "ETH 2x Long" ] }, "direction": { "type": "string", "enum": [ "long", "short" ] }, "token": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "The perp token (B20, 18 decimals)." }, "vault": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "adapter": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "hook": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "rail": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "sourcer": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "decimals": { "type": "integer", "const": 18 }, "poolId": { "type": "string", "pattern": "^0x[0-9a-f]{64}$" }, "poolKey": { "type": "object", "required": [ "currency0", "currency1", "fee", "tickSpacing", "hooks" ], "properties": { "currency0": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "currency1": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "fee": { "type": "integer", "description": "8388608 = 0x800000, the dynamic-fee flag" }, "tickSpacing": { "type": "integer" }, "hooks": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } }, "settlement": { "type": "object", "properties": { "address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "symbol": { "type": "string", "examples": [ "USDC" ] }, "decimals": { "type": "integer", "examples": [ 6 ] } } }, "collateral": { "type": "object", "properties": { "address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "symbol": { "type": "string" }, "onchainSymbol": { "type": "string" }, "decimals": { "type": "integer" } } }, "recoveryOnly": { "type": "boolean", "description": "Retired market kept only for exits. Do not list or buy." }, "canary": { "type": "boolean" }, "issuerFeeBps": { "type": "integer", "examples": [ 5 ] }, "lpFeePips": { "type": "integer", "examples": [ 500 ], "description": "Pool fee in hundredths of a basis point: 500 = 0.05%." }, "totalSupply": { "type": "string", "pattern": "^[0-9]+$", "description": "Raw 18-decimal token units." }, "effectiveSupply": { "type": "string", "pattern": "^[0-9]+$", "description": "Raw 18-decimal token units." }, "navUsdg": { "type": "string", "pattern": "^[0-9]+$", "description": "Total NAV in USDC raw units (6 decimals)." }, "navPerShareUsdg": { "type": "string", "pattern": "^[0-9]+$", "description": "NAV per token in USDC raw units (6 decimals). priceUsd = navPerShareUsdg / 1e6." }, "priceUsd": { "type": "number" }, "navPriceUsd": { "type": "number" }, "marketCapUsd": { "type": "number" }, "change24hPct": { "type": [ "number", "null" ] }, "currentLeverageWad": { "type": "string", "pattern": "^[0-9]+$", "description": "1e18 fixed point." }, "targetLeverageWad": { "type": "string", "pattern": "^[0-9]+$", "description": "1e18 fixed point." }, "minLeverageWad": { "type": "string", "pattern": "^[0-9]+$", "description": "1e18 fixed point." }, "maxLeverageWad": { "type": "string", "pattern": "^[0-9]+$", "description": "1e18 fixed point." }, "currentLtvWad": { "type": "string", "pattern": "^[0-9]+$", "description": "1e18 fixed point loan-to-value." }, "ripcordLtvWad": { "type": "string", "pattern": "^[0-9]+$", "description": "1e18 fixed point; at this LTV the market deleverages." }, "mintCapacityUsdg": { "type": "string", "pattern": "^[0-9]+$", "description": "USDC raw units that can currently be issued." }, "supplyCapUsdg": { "type": "string", "pattern": "^[0-9]+$", "description": "Issuance cap in USDC raw units (max uint256 = uncapped)." }, "issuanceCap": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "uncapped", "fixed" ] }, "maxUsdg": { "type": [ "string", "null" ] } } }, "maxSwapBps": { "type": "string", "pattern": "^[0-9]+$", "description": "Largest venue-execution slippage the vault tolerates, in bps." }, "collateralAmount": { "type": "string", "pattern": "^[0-9]+$", "description": "Collateral held, in collateral raw units." }, "debtUsdg": { "type": "string", "pattern": "^[0-9]+$", "description": "Morpho debt in USDC raw units." }, "morpho": { "type": "object", "additionalProperties": true, "properties": { "totalSupplyUsd": { "type": "number" }, "totalBorrowUsd": { "type": "number" }, "availableUsd": { "type": "number" }, "idleUsd": { "type": "number" }, "reallocatableUsd": { "type": "number" }, "utilizationBps": { "type": "string" }, "liquidityHealth": { "type": "string", "examples": [ "deep" ] } } }, "liquidationCount": { "type": "integer" }, "lastLiquidationAt": { "type": "string", "pattern": "^[0-9]+$", "description": "Unix seconds, 0 = never." }, "lastRebalance": { "type": "string", "pattern": "^[0-9]+$", "description": "Unix seconds." }, "activity": { "type": "object", "additionalProperties": true, "properties": { "trades": { "type": "integer" }, "buys": { "type": "integer" }, "sells": { "type": "integer" }, "volumeUsdg": { "type": "string", "pattern": "^[0-9]+$", "description": "USDC raw units." }, "volume24hUsdg": { "type": "string", "pattern": "^[0-9]+$", "description": "USDC raw units." }, "feesUsdg": { "type": "string", "pattern": "^[0-9]+$", "description": "USDC raw units." }, "holders": { "type": "integer" }, "recent": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "blockNumber": { "type": "string" }, "transactionHash": { "type": "string" }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "settlementAmount": { "type": "string", "pattern": "^[0-9]+$", "description": "USDC raw units." }, "shares": { "type": "string", "pattern": "^[0-9]+$", "description": "Token raw units." }, "fee": { "type": "string", "pattern": "^[0-9]+$", "description": "USDC raw units." }, "priceUsd": { "type": "number" }, "venue": { "type": "string" } } } } } }, "wallet": { "type": "object", "description": "Present when ?account= is given.", "properties": { "perpBalance": { "type": "string", "pattern": "^[0-9]+$", "description": "Token raw units." }, "settlementBalance": { "type": "string", "pattern": "^[0-9]+$", "description": "USDC raw units." } } }, "updatedAt": { "type": "integer", "description": "Unix milliseconds." } } }, "PerpQuote": { "type": "object", "additionalProperties": true, "required": [ "vault", "side", "venue", "poolKey", "amountIn", "amountOut" ], "properties": { "vault": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "venue": { "type": "string", "description": "\"primary\"/\"secondary\" = a Uniswap v4 pool quote; \"direct\" = the issuer (NAV) path, in which case estimate is true." }, "poolKey": { "type": "object", "required": [ "currency0", "currency1", "fee", "tickSpacing", "hooks" ], "properties": { "currency0": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "currency1": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "fee": { "type": "integer", "description": "8388608 = 0x800000, the dynamic-fee flag" }, "tickSpacing": { "type": "integer" }, "hooks": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } }, "amountIn": { "type": "string", "pattern": "^[0-9]+$", "description": "Raw input units." }, "amountOut": { "type": "string", "pattern": "^[0-9]+$", "description": "Raw output units. \"0\" when `refusal` is present. When `estimate` is true this is a conservative floor." }, "referenceAmountOut": { "type": "string", "pattern": "^[0-9]+$", "description": "The same size at NAV, before impact." }, "executionImpactBps": { "type": "number", "description": "Shortfall vs NAV in basis points." }, "poolFeeBps": { "type": "number" }, "estimate": { "type": "boolean" }, "feeUsdg": { "type": "string", "pattern": "^[0-9]+$", "description": "Issuer fee in USDC raw units (issuer path only)." }, "unwindBoundBps": { "type": "integer" }, "issuer": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "issuerCall": { "type": "string", "enum": [ "adapter", "rail", "sourcer" ] }, "gasEstimate": { "type": "string", "pattern": "^[0-9]+$", "description": "Gas units." }, "quotedAt": { "type": "integer", "description": "Unix milliseconds." }, "refusal": { "type": "object", "additionalProperties": true, "description": "The hook declined this size; contains the largest fillable size or the halt reason." } } } } } }