{"openapi":"3.1.0","info":{"title":"FlexYield API","version":"1.0.0","description":"One API key, one bill, every provider. JSON-RPC relay across 6 chains, the toolbox, the data API and account statements. Weighted metering (standard 1 · heavy 2 · data 10 · toolbox 1 · cache hit 0); every error carries data.request_id and data.support. Agents: the same capabilities are MCP tools at https://flexyield.io/mcp.","contact":{"email":"hello@flexyield.io","url":"https://flexyield.io/support"},"termsOfService":"https://flexyield.io/terms"},"servers":[{"url":"https://flexyield.io"}],"x-pricing":{"rule":"Price per unit falls with commitment, never with identity: more volume committed per month → lower USD per 1M units; yearly < monthly; per call is the dearest lane; no pack undercuts the yearly tier; a subscription is cheapest per unit at its included volume.","unit":"USD per 1,000,000 standard units (standard 1 · heavy 2 · data 10 · cache hit 0), net — VAT is added where it applies on every lane, incl. per call (by the payer's location)","tierMultipliers":{"cheap":0.5,"balanced":1.0,"fast":2.0},"lanes":[{"key":"scale_yearly","label":"Scale (yearly)","kind":"subscription","commitmentUsd":2990.0,"priceUsd":249.17,"units":60000000,"usdPerMillionUnits":4.15,"supply":"premium","fastShare":0.25,"live":true},{"key":"growth_yearly","label":"Growth (yearly)","kind":"subscription","commitmentUsd":8990.0,"priceUsd":749.17,"units":200000000,"usdPerMillionUnits":3.75,"supply":"premium","fastShare":0.2,"live":true},{"key":"pro_yearly","label":"Pro (yearly)","kind":"subscription","commitmentUsd":990.0,"priceUsd":82.5,"units":15000000,"usdPerMillionUnits":5.5,"supply":"premium","fastShare":0.3,"live":true},{"key":"scale_monthly","label":"Scale","kind":"subscription","commitmentUsd":299.0,"priceUsd":299.0,"units":60000000,"usdPerMillionUnits":4.98,"supply":"premium","fastShare":0.25,"live":true},{"key":"growth_monthly","label":"Growth","kind":"subscription","commitmentUsd":899.0,"priceUsd":899.0,"units":200000000,"usdPerMillionUnits":4.5,"supply":"premium","fastShare":0.2,"live":true},{"key":"pack_l","label":"Pack L","kind":"pack","commitmentUsd":200.0,"priceUsd":200.0,"units":32000000,"usdPerMillionUnits":6.25,"supply":"premium","fastShare":0.0,"live":true},{"key":"pro_monthly","label":"Pro","kind":"subscription","commitmentUsd":99.0,"priceUsd":99.0,"units":15000000,"usdPerMillionUnits":6.6,"supply":"premium","fastShare":0.3,"live":true},{"key":"pack_m","label":"Pack M","kind":"pack","commitmentUsd":50.0,"priceUsd":50.0,"units":7000000,"usdPerMillionUnits":7.14,"supply":"premium","fastShare":0.0,"live":true},{"key":"pack_s","label":"Pack S","kind":"pack","commitmentUsd":10.0,"priceUsd":10.0,"units":1200000,"usdPerMillionUnits":8.33,"supply":"premium","fastShare":0.0,"live":true},{"key":"per_call","label":"Per call (x402) / PAYG","kind":"per_call","commitmentUsd":0.0,"priceUsd":9.0,"units":1000000,"usdPerMillionUnits":9.0,"supply":"premium","fastShare":1.0,"live":false},{"key":"builder","label":"Builder","kind":"flat","commitmentUsd":12.0,"priceUsd":12.0,"units":20000000,"usdPerMillionUnits":0.6,"supply":"public","fastShare":0.0,"live":true},{"key":"free","label":"Free","kind":"free","commitmentUsd":0.0,"priceUsd":0.0,"units":1000000,"usdPerMillionUnits":0.0,"supply":"public","fastShare":0.0,"live":true},{"key":"door1","label":"Anonymous key (door 1)","kind":"free","commitmentUsd":0.0,"priceUsd":0.0,"units":300000,"usdPerMillionUnits":0.0,"supply":"public","fastShare":0.0,"live":false},{"key":"founding","label":"Founding (Pro locked 12 months; until 2026-12-05 or while seats last)","kind":"subscription","commitmentUsd":79.0,"priceUsd":79.0,"units":15000000,"usdPerMillionUnits":5.27,"supply":"premium","fastShare":0.3,"live":true}]},"externalDocs":{"url":"https://flexyield.io/docs","description":"Developer docs"},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Your FlexYield API key (fy_…). Free tier at https://flexyield.io/registration/new"},"x402":{"type":"apiKey","in":"header","name":"X-PAYMENT","description":"x402 lane: the one-time credential (fyx_…) returned by POST https://flexyield.io/x402/redeem after a payment against the menu at https://flexyield.io/x402 (base-sepolia); the redeem needs an EIP-191 signature by the paying wallet — the tx hash alone is public and is not a credential"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"integer","description":"JSON-RPC style code, e.g. -32005 rate window"},"message":{"type":"string"},"data":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"support":{"type":"string","description":"Path to file this call as a ticket"}}}}}}},"JsonRpcRequest":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{},"method":{"type":"string"},"params":{"type":"array"}}},"JsonRpcResponse":{"type":"object","properties":{"jsonrpc":{"type":"string"},"id":{},"result":{},"error":{"type":"object"}}}}},"paths":{"/rpc/{chain}":{"post":{"summary":"JSON-RPC relay with multi-provider failover","security":[{"bearer":[]},{"x402":[]}],"parameters":[{"name":"chain","in":"path","required":true,"schema":{"type":"string","enum":["eth_mainnet","base_mainnet","arbitrum_one","optimism_mainnet","polygon_pos","solana_mainnet"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcRequest"}}}},"responses":{"200":{"description":"The upstream's JSON-RPC response (also for in-band JSON-RPC errors)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}}}},"402":{"description":"x402 lane: the settlement is unknown, spent or expired — pay against the menu at /x402 and retry with X-PAYMENT","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown chain (-32600) or method not in the catalog (-32601, with the concierge doorway)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key (-32001)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate window, key budget, plan quota or service cap reached (-32005/-32006/-32007/-32014) — the body says what to do next","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Service switched off for this account/key (-32012) or account suspended (-32009)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-payment-info":{"x402Version":1,"scheme":"exact","network":"base-sepolia","asset":"USDC","mainnetLive":false,"menu":"https://flexyield.io/x402","redeem":"https://flexyield.io/x402/redeem","header":"X-PAYMENT","redeemBody":{"tx_hash":"<settlement tx hash>","tier":"cheap | balanced | fast","signature":"EIP-191 personal_sign by the paying wallet over messageToSign"},"messageToSign":"FlexYield x402 redeem\n<settlement tx hash>","credential":"one-time token (fyx_…) in the redeem response; the tx hash is not a credential","maxUnitsPerSettlement":20000,"unitsPerPayment":1000,"windowSeconds":3600,"tax":"Prices are net. VAT is added on top where it applies, by the payer's location at quote time (IP evidence): 20 % for payers in the EU or not located, none outside the EU. Units follow the net amount paid.","tiers":[{"name":"cheap","label":"Public-pool supply, best-effort","priceAtomicPer1kUnits":4500,"usdPerMillionUnits":4.5,"netAmountRequired":"4500","maxAmountRequired":"5400"},{"name":"balanced","label":"Measured wholesale blend, health-scored routing","priceAtomicPer1kUnits":9000,"usdPerMillionUnits":9.0,"netAmountRequired":"9000","maxAmountRequired":"10800"},{"name":"fast","label":"Premium slice, lowest measured latency","priceAtomicPer1kUnits":18000,"usdPerMillionUnits":18.0,"netAmountRequired":"18000","maxAmountRequired":"21600"}]}}},"/toolbox/gas/{chain}":{"get":{"summary":"EIP-1559 gas recommendations (slow / standard / fast)","security":[{"bearer":[]}],"parameters":[{"name":"chain","in":"path","required":true,"schema":{"type":"string","enum":["eth_mainnet","base_mainnet","arbitrum_one","optimism_mainnet","polygon_pos","solana_mainnet"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Invalid or missing API key (-32001)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate window, key budget, plan quota or service cap reached (-32005/-32006/-32007/-32014) — the body says what to do next","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Service switched off for this account/key (-32012) or account suspended (-32009)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/toolbox/tx/{chain}/{hash}":{"get":{"summary":"Transaction status","security":[{"bearer":[]}],"parameters":[{"name":"chain","in":"path","required":true,"schema":{"type":"string","enum":["eth_mainnet","base_mainnet","arbitrum_one","optimism_mainnet","polygon_pos","solana_mainnet"]}},{"name":"hash","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Invalid or missing API key (-32001)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate window, key budget, plan quota or service cap reached (-32005/-32006/-32007/-32014) — the body says what to do next","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Service switched off for this account/key (-32012) or account suspended (-32009)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/toolbox/ens/resolve/{name}":{"get":{"summary":"ENS name → address","security":[{"bearer":[]}],"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Invalid or missing API key (-32001)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate window, key budget, plan quota or service cap reached (-32005/-32006/-32007/-32014) — the body says what to do next","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Service switched off for this account/key (-32012) or account suspended (-32009)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/toolbox/ens/reverse/{address}":{"get":{"summary":"Address → ENS name","security":[{"bearer":[]}],"parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Invalid or missing API key (-32001)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate window, key budget, plan quota or service cap reached (-32005/-32006/-32007/-32014) — the body says what to do next","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Service switched off for this account/key (-32012) or account suspended (-32009)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/toolbox/prices":{"get":{"summary":"Token prices","security":[{"bearer":[]}],"parameters":[{"name":"symbols","in":"query","schema":{"type":"string"},"description":"Comma-separated symbols"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Invalid or missing API key (-32001)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate window, key budget, plan quota or service cap reached (-32005/-32006/-32007/-32014) — the body says what to do next","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Service switched off for this account/key (-32012) or account suspended (-32009)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/toolbox/abi/{chain}/{address}":{"get":{"summary":"Verified contract ABI + name","security":[{"bearer":[]}],"parameters":[{"name":"chain","in":"path","required":true,"schema":{"type":"string","enum":["eth_mainnet","base_mainnet","arbitrum_one","optimism_mainnet","polygon_pos","solana_mainnet"]}},{"name":"address","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Invalid or missing API key (-32001)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate window, key budget, plan quota or service cap reached (-32005/-32006/-32007/-32014) — the body says what to do next","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Service switched off for this account/key (-32012) or account suspended (-32009)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/toolbox/decode/{chain}/{address}":{"post":{"summary":"Decode calldata against the verified ABI","security":[{"bearer":[]}],"parameters":[{"name":"chain","in":"path","required":true,"schema":{"type":"string","enum":["eth_mainnet","base_mainnet","arbitrum_one","optimism_mainnet","polygon_pos","solana_mainnet"]}},{"name":"address","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string","pattern":"^0x[0-9a-fA-F]*$"}}}}}},"responses":{"200":{"description":"Function signature + arguments","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Invalid or missing API key (-32001)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate window, key budget, plan quota or service cap reached (-32005/-32006/-32007/-32014) — the body says what to do next","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Service switched off for this account/key (-32012) or account suspended (-32009)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/data/{chain}/balances/{address}":{"get":{"summary":"Native + token balances (paid tiers, 10 units)","security":[{"bearer":[]}],"parameters":[{"name":"chain","in":"path","required":true,"schema":{"type":"string","enum":["eth_mainnet","base_mainnet","arbitrum_one","optimism_mainnet","polygon_pos","solana_mainnet"]}},{"name":"address","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Invalid or missing API key (-32001)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate window, key budget, plan quota or service cap reached (-32005/-32006/-32007/-32014) — the body says what to do next","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Service switched off for this account/key (-32012) or account suspended (-32009)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/data/{chain}/history/{address}":{"get":{"summary":"Transfer history (paid tiers, 10 units)","security":[{"bearer":[]}],"parameters":[{"name":"chain","in":"path","required":true,"schema":{"type":"string","enum":["eth_mainnet","base_mainnet","arbitrum_one","optimism_mainnet","polygon_pos","solana_mainnet"]}},{"name":"address","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Invalid or missing API key (-32001)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate window, key budget, plan quota or service cap reached (-32005/-32006/-32007/-32014) — the body says what to do next","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Service switched off for this account/key (-32012) or account suspended (-32009)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/statements":{"get":{"summary":"The account's billing periods (an agent's key: its own scope)","security":[{"bearer":[]}],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Invalid or missing API key (-32001)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate window, key budget, plan quota or service cap reached (-32005/-32006/-32007/-32014) — the body says what to do next","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Service switched off for this account/key (-32012) or account suspended (-32009)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/statements/{period}":{"get":{"summary":"Statement for a period — usage by key/agent, chain, method class; .csv variant available","security":[{"bearer":[]}],"parameters":[{"name":"period","in":"path","required":true,"schema":{"type":"string","format":"date"},"description":"Period key = its start date"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Invalid or missing API key (-32001)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate window, key budget, plan quota or service cap reached (-32005/-32006/-32007/-32014) — the body says what to do next","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Service switched off for this account/key (-32012) or account suspended (-32009)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/x402":{"get":{"summary":"x402 pay-per-request menu (testnet lane)","responses":{"200":{"description":"Tiers, prices and the settlement network","content":{"application/json":{"schema":{"type":"object"}}}}},"x-payment-info":{"x402Version":1,"scheme":"exact","network":"base-sepolia","asset":"USDC","mainnetLive":false,"menu":"https://flexyield.io/x402","redeem":"https://flexyield.io/x402/redeem","header":"X-PAYMENT","redeemBody":{"tx_hash":"<settlement tx hash>","tier":"cheap | balanced | fast","signature":"EIP-191 personal_sign by the paying wallet over messageToSign"},"messageToSign":"FlexYield x402 redeem\n<settlement tx hash>","credential":"one-time token (fyx_…) in the redeem response; the tx hash is not a credential","maxUnitsPerSettlement":20000,"unitsPerPayment":1000,"windowSeconds":3600,"tax":"Prices are net. VAT is added on top where it applies, by the payer's location at quote time (IP evidence): 20 % for payers in the EU or not located, none outside the EU. Units follow the net amount paid.","tiers":[{"name":"cheap","label":"Public-pool supply, best-effort","priceAtomicPer1kUnits":4500,"usdPerMillionUnits":4.5,"netAmountRequired":"4500","maxAmountRequired":"5400"},{"name":"balanced","label":"Measured wholesale blend, health-scored routing","priceAtomicPer1kUnits":9000,"usdPerMillionUnits":9.0,"netAmountRequired":"9000","maxAmountRequired":"10800"},{"name":"fast","label":"Premium slice, lowest measured latency","priceAtomicPer1kUnits":18000,"usdPerMillionUnits":18.0,"netAmountRequired":"18000","maxAmountRequired":"21600"}]}}},"/x402/receipts/{tx_hash}":{"get":{"summary":"Per-settlement receipt (HTML, or JSON with .json): seller, wallet, amount, tax treatment by payer country","security":[],"parameters":[{"name":"tx_hash","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"The receipt","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"No settlement with that hash","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/keys":{"post":{"summary":"Door 1: an anonymous capability key, no input — public supply, 10,000 weighted units per UTC day, 5 req/s; 3 keys per IP address per day","security":[],"responses":{"201":{"description":"The key (shown once) plus the welcome: door, fences, doorways (bind, adopt with claim_code, pay per call), terms version","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string"},"door":{"type":"string"},"fences":{"type":"object"},"doorways":{"type":"object"}}}}}},"429":{"description":"Address quota for new keys used up — the body carries the doorways","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/keys/bind/start":{"post":{"summary":"Door 2, step 1: a SIWE message to sign with the wallet that will own this key","security":[{"bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["address"],"properties":{"address":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}}}}}},"responses":{"200":{"description":"message_to_sign and expires_in_seconds","content":{"application/json":{"schema":{"type":"object"}}}},"422":{"description":"Bad address or key already bound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key (-32001)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/keys/bind":{"post":{"summary":"Door 2, step 2: bind the key to the wallet — persistent identity, 1M units/month, one key per wallet","security":[{"bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["address","signature"],"properties":{"address":{"type":"string"},"signature":{"type":"string"}}}}}},"responses":{"200":{"description":"bound: true plus the welcome","content":{"application/json":{"schema":{"type":"object"}}}},"422":{"description":"Signature or nonce invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key (-32001)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agents/adopt":{"post":{"summary":"Door 3b: a signed-in owner adopts a door key by its claim_code — the key inherits the account's plan, packs, allowances and fleet controls (dashboard session; MCP twins: claim tools)","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["claim_code"],"properties":{"claim_code":{"type":"string"}}}}}},"responses":{"302":{"description":"Back to /agents with the result"}}}}}}