{"info":{"title":"Flow API","version":"0.4.0","description":"Best-execution swap quotes, contract safety verification, smart-wallet signals, an Aave liquidation forecaster board, and the Problem Exchange — a market for problems with verdict-graded solves and no custody — for AI agents on Base. The quote engine compares Uniswap V3, PancakeSwap V3 and Aerodrome across fee tiers, plus two-hop routes via WETH, and answers in ~100ms. Pay-per-call via x402 on Base (quotes $0.01, safety verdicts $0.02, forecaster board $0.05) — no API key, no account.","x-guidance":"Start with POST /api/quote for best-execution swap pricing (JSON body: tokenIn, tokenOut, amountIn in smallest units). Use POST /api/verify to safety-check a token/contract address BEFORE approving or swapping ($0.02/call). POST /api/verdict is the bundled pre-payment verdict ($0.05/call): one ALLOW/REVIEW/BLOCK decision over the contract AND the payee who receives the money, with address-poisoning look-alike detection when you pass expectedPayee. POST /api/wallet-check is the wallet safety audit ($0.05/call): a Base wallet’s live ERC-20 approval exposure, graded with revoke calldata for risky pairs. POST /api/precheck is a free combined quote+safety check. POST /api/settlement-verify is the free settlement verifier: a three-way match for an x402 EIP-3009 authorization (signature recovers to the payer, USDC authorizationState(from, nonce) consumed on-chain, settlement tx Transfer matches from/to/value inside the validity window) — a payment is not a receipt. POST /api/found-money/scan is the free found-money scan: it checks one EVM wallet for unclaimed or dormant value — native + USDC balances on Base, Ethereum, Polygon, Arbitrum One and BNB Chain, Aave V3 supplied positions on Base + Ethereum, Aave V2 and Compound V2 positions on Ethereum — and returns a scoped report (merkle/airdrop claim distributors are NOT scanned in v1). Scan and report only; recovery needs the owner’s own signature. Free; Flow earns 15% of recovered value only after the owner’s claim succeeds, $0 on zero finds. Human page: https://flow-kg4x.vercel.app/found-money. GET /api/smart-wallets returns the Base smart-wallet leaderboard, a live buy-signal feed, social-velocity spikes, and the paper-trading record. GET /api/signals is the polling feed behind it: chronological buy signals + social-velocity spikes, newest first, each with timestamp + block number + wallet + token + signal score, with incremental polling via ?since=<unix timestamp or block number> ($0.01/call). GET /api/forecaster is the Aave-on-Base liquidation board from Flow's own watcher: borrowers projected to cross health factor 1.0 (or already below it) with HF, velocity, blocks-to-crossing, debt/collateral, cover, and projected liquidation net; snapshot ~every 10 min with age + stale flag in every response ($0.05/call). Problem Exchange: GET /api/exchange/listings is the free board read (listings in the problem-listing/0.1 schema, JSON Schema at https://flow-kg4x.vercel.app/schemas/problem-listing-0.1.json); GET /api/exchange/listing?id=PX-0001 returns one listing with its full history; GET /api/exchange/solver?id=<solver> returns a solver’s graded record (exchange-solver-record/0.1); GET /api/exchange/bypass?id=<listing> sells that listing’s verified workaround as data (price set per listing; PX-0001 is $0.005). DONE solves are graded by POST /api/verify ($0.02) and the payer pays the solver directly — Flow takes no cut of the solve price and never holds funds. Listing fee $0.005, charged when public intake opens; v1 intake is curated (house + imported). Paid endpoints return HTTP 402 with an x402 v2 payment challenge when unpaid; payTo is a Base wallet, asset is USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913), network eip155:8453. Work hub (Problem Exchange hub layer): POST /api/exchange/worker registers a worker (personal_sign of flow-exchange:register:<wallet>); GET /api/exchange/workers is the directory ranked by graded record; POST /api/exchange/claim claims an OPEN listing (first claim wins, wallet-signed); POST /api/exchange/escrow locks the poster budget as a signed EIP-3009 authorization to the claimed worker, held unsettled; POST /api/exchange/deliver posts the deliverable (wallet-signed); on a graded pass the operator settles the escrow via POST /api/exchange/release and the listing is marked SETTLED only with the real settlement tx ref.","contact":{"email":"Flowexecutor@yahoo.com"}},"openapi":"3.0.3","paths":{"/api/health":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"blockNumber":{"type":"integer"},"chain":{"type":"string"},"status":{"type":"string"}},"type":"object"}}},"description":"Healthy"}},"summary":"Service health"}},"/api/quote":{"post":{"description":"Returns the best available price across Uniswap V3, PancakeSwap V3 and Aerodrome (including two-hop routes via WETH) for a token swap on Base, plus the edge in basis points over the Uniswap baseline.","requestBody":{"content":{"application/json":{"schema":{"properties":{"amountIn":{"description":"Input amount in smallest units","example":"1000000","type":"string"},"tokenIn":{"description":"ERC-20 contract address of input token","example":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","type":"string"},"tokenInDecimals":{"default":6,"description":"Decimals of input token","type":"integer"},"tokenOut":{"description":"ERC-20 contract address of output token","example":"0x4200000000000000000000000000000000000006","type":"string"}},"required":["tokenIn","tokenOut","amountIn"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"bestOut":{"description":"Best output amount in smallest units","type":"string"},"edgeBps":{"description":"Edge over Uniswap baseline in basis points","type":"number"},"uniswapOut":{"description":"Uniswap V3 output for comparison","type":"string"},"venue":{"description":"Winning DEX","enum":["uniswap","pancakeswap","aerodrome"],"type":"string"}},"type":"object"}}},"description":"Best quote"},"402":{"description":"Payment required — x402 v2 exact, $0.01 USDC on Base (eip155:8453)."}},"summary":"Get best swap price","x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]}}},"/api/stats":{"get":{"description":"Shared counters across all instances (Upstash-backed): quotes served and errors.","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"errors":{"type":"integer"},"instanceStarted":{"format":"date-time","type":"string"},"quotesServed":{"type":"integer"}},"type":"object"}}},"description":"Stats snapshot"}},"summary":"Usage statistics"}},"/api/verify":{"post":{"description":"Contract safety check for AI agents: verifies whether a contract's source is published, detects upgradeable proxies, scans verified source for dangerous owner privileges (mint/pause/blacklist/taxes), checks ownership, and simulates a buy+sell to catch honeypots. Returns a plain-English risk report with a safe/caution/danger verdict.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","description":"Contract address to check (0x + 40 hex chars). 'token' is accepted as an alias.","example":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"},"chain":{"type":"string","description":"Chain name or chain id. Default: base.","default":"base","example":"base"}},"required":["address"]}}},"required":true},"responses":{"200":{"description":"Risk report","content":{"application/json":{"schema":{"type":"object","properties":{"verdict":{"type":"string","enum":["safe","caution","danger"],"description":"Overall verdict."},"score":{"type":"integer","description":"0-100, starts at 100 with deductions per red flag."},"agentAdvice":{"type":"string","enum":["APPROVE","REVIEW_MANUALLY","DO_NOT_APPROVE"]},"summary":{"type":"string","description":"Plain-English risk report, 2-4 sentences."},"flags":{"type":"array","items":{"type":"object","properties":{"severity":{"type":"string","enum":["critical","high","medium","low","info"]},"text":{"type":"string"}}}},"details":{"type":"object","description":"Full check results: sourceVerified, proxy, owner, privileges, honeypot simulation."}}}}}},"400":{"description":"Invalid address or chain."},"402":{"description":"Payment required — x402 v2 exact, $0.02 USDC on Base (eip155:8453)."},"405":{"description":"POST only."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.020000"},"protocols":[{"x402":{}}]}}},"/api/smart-wallets":{"get":{"description":"Smart-wallet tracker for Base: leaderboard of wallets ranked by early buys on pumping tokens, a real-time buy-signal feed (each signal carries timestamp + block number; signals older than 10 min are flagged stale), a social-velocity overlay (DexScreener boost acceleration + GeckoTerminal trending rank, raw inputs included), and a PAPER paper-trading record that copy-trades top wallets with $50 simulated positions. x402 pay-per-call: $0.01 USDC on Base.","responses":{"200":{"description":"Leaderboard (top 20), signals (latest 20), paperRecord, methodology, dataAsOf, source, disclaimer.","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required — x402 v2 exact, $0.01 USDC on Base (eip155:8453)."},"503":{"description":"Tracker has not produced data yet."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]}}},"/api/signals":{"get":{"description":"Use when an agent is polling for fresh smart-wallet buy signals on Base and needs only what's new since its last check. Chronological signal feed: recent buy signals from tracked Base wallets plus social-velocity spikes, newest first, every entry with timestamp, block number, wallet, token, and a labeled signal score. Supports incremental polling via ?since=<unix seconds, unix ms, ISO 8601, or Base block number> and ?limit=<1..100> (default 50). x402 pay-per-call: $0.01 USDC on Base.","parameters":[{"name":"since","in":"query","required":false,"description":"Only return entries strictly newer than this: unix seconds (>=1e9), unix milliseconds (>=1e12), an ISO 8601 timestamp, or a Base block number (<1e9).","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Max signals to return, 1..100 (default 50).","schema":{"type":"integer"}}],"responses":{"200":{"description":"signals (newest first), socialSpikes, returned/available counts, cursor for the next poll, dataAsOf, source, scoreMethod, disclaimer.","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required — x402 v2 exact, $0.01 USDC on Base (eip155:8453)."},"503":{"description":"Tracker has not produced data yet."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]}}},"/api/forecaster":{"get":{"description":"Use when an agent runs liquidations, keeps Aave positions, or watches liquidation risk on Base and needs to know which borrowers are about to tip. Flow forecaster board: the Aave Base borrowers our liquidation watcher currently projects to cross health factor 1.0 (or that are already below it), most urgent first, each with current health factor, HF velocity per block, projected blocks to crossing (plus estimated seconds at ~2s Base blocks), debt and collateral assets, cover size in USD, and projected liquidation net from the watcher's pre-stage economics. Snapshotted every ~10 minutes; every response prints generatedAt, snapshotAgeSeconds, and stale (true once the snapshot is older than 15 minutes). x402 pay-per-call: $0.05 USDC on Base.","responses":{"200":{"description":"generatedAt, snapshotAgeSeconds, stale, source, count, positions[] (borrower, status, hf, hfVelocityPerBlock, blocksToCross, estSecondsToCross, blocksToProfitable, preArmed, projectedNetUsd, debtAsset, collateralAsset, coverUsd, latestNetUsd, forecastAt, forecastBlock), boardRule, ledgerTip, note.","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required — x402 v2 exact, $0.05 USDC on Base (eip155:8453)."},"503":{"description":"Forecaster board not available yet — returned WITHOUT settling, so the payer is not charged."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.050000"},"protocols":[{"x402":{}}]}}},"/api/verdict":{"post":{"summary":"Bundled pre-payment verdict — contract + payee in one call ($0.05)","description":"Use when an agent is about to make an irreversible payment and needs ONE decision over both sides of the spend. Grades the contract with the full /api/verify engine and the payee by kind (EOA/contract), on-chain activity history, and address-poisoning look-alike detection against an optional expectedPayee. Returns decision ALLOW | REVIEW | BLOCK, a combined 0-100 score, per-side grades and flags, and a dated evidence list. The contract-only check stays at /api/verify ($0.02); the free taste is /api/precheck.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contract":{"type":"string","description":"Contract/token address the payment interacts with (0x + 40 hex chars).","example":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"},"payee":{"type":"string","description":"Address that will receive the money (0x + 40 hex chars).","example":"0xcF8A8350cb42a6680005ca7FF9E485Bb55fa74FA"},"expectedPayee":{"type":"string","description":"Optional: the payee you intended — enables look-alike / address-poisoning detection."},"amountUsd":{"type":"number","description":"Optional payment size in USD — escalates first-payment risk flags on unproven payees."},"chain":{"type":"string","description":"Chain name or chain id. Default: base.","default":"base"}},"required":["contract","payee"]}}}},"responses":{"200":{"description":"Bundled verdict","content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","enum":["ALLOW","REVIEW","BLOCK"]},"score":{"type":"integer","description":"Combined 0-100 score (the lower of the two sides)."},"contract":{"type":"object","description":"Full contract grade: verdict, score, agentAdvice, flags."},"payee":{"type":"object","description":"Payee grade: kind (eoa|contract|burn), verdict, score, flags, txCount and balance for EOAs."},"evidence":{"type":"array","items":{"type":"string"},"description":"Dated list of what was read on-chain to reach the decision."}}}}}},"402":{"description":"x402 payment required ($0.05 USDC on Base), or send an Early Builder Key as the x-flow-builder-key header."}}}},"/api/wallet-check":{"post":{"summary":"Wallet safety audit — approval exposure ($0.05)","description":"Use when an agent or wallet owner needs to know whether a Base wallet is safe to fund or keep using: a live approval-exposure audit. Reads the wallet’s current allowances (canonical token/spender pairs probed at the latest block; coverage stated in every report), grades every spender holding a live allowance with the full contract-safety engine, flags unlimited approvals and approvals to EOAs, and returns SAFE | REVIEW | EXPOSED with a 0-100 score and the exact revoke calldata (approve(spender, 0)) for every risky pair. Read-only; never touches funds. Also covered by the Early Builder Key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"wallet":{"type":"string","description":"Base wallet address to audit (0x + 40 hex chars).","example":"0x3D650013F46DD2d96B5afEFe4acAb7A7f2727561"}},"required":["wallet"]}}}},"responses":{"200":{"description":"Wallet safety audit","content":{"application/json":{"schema":{"type":"object","properties":{"verdict":{"type":"string","enum":["SAFE","REVIEW","EXPOSED"]},"score":{"type":"integer","description":"0-100 safety score."},"allowances":{"type":"array","description":"Live allowances found in coverage, each with its spender grade."},"fixes":{"type":"array","description":"Revoke calldata for every risky pair."}}}}}},"402":{"description":"x402 payment required ($0.05 USDC on Base), or send an Early Builder Key as the x-flow-builder-key header."}}}},"/api/precheck":{"post":{"summary":"Free combined quote + safety precheck","description":"Free pre-trade check: best-execution quote plus a safety verdict for the output token in one call (verdict safe|caution|danger, score 0-100, safeToProceed). No payment required.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tokenIn":{"type":"string","example":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"},"tokenOut":{"type":"string","example":"0x4200000000000000000000000000000000000006"},"amountIn":{"type":"string","example":"1000000"}},"required":["tokenIn","tokenOut","amountIn"]}}}},"responses":{"200":{"description":"Quote + safety verdict","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Missing tokenIn, tokenOut, or amountIn."}}}},"/api/settlement-verify":{"post":{"summary":"Settlement verifier — three-way match for an x402 payment (free)","description":"Use when an agent has paid (or been paid) via x402 and needs to prove the settlement actually landed. Checks: (1) the EIP-3009 signature recovers to from, (2) USDC authorizationState(from, nonce) is consumed on-chain, (3) the settlement tx's USDC Transfer log matches from/to/value exactly, (4) the settled block sits inside the validity window. Body: {authorization: {from, to, value, validAfter, validBefore, nonce, v, r, s}, txHash? (optional — without it checks 3-4 are skipped), network?}. Base only for now. Free — no payment required. A GET returns the how-doc.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"authorization":{"type":"object"},"txHash":{"type":"string"},"network":{"type":"string"}},"required":["authorization"]}}}},"responses":{"200":{"description":"Per-check results plus the overall verified flag."},"400":{"description":"Malformed authorization."}}},"get":{"summary":"Settlement verifier how-doc (free)","responses":{"200":{"description":"The how document: endpoint, body shape, and the four checks."}}}},"/api/found-money/scan":{"post":{"summary":"Found-money scan — unclaimed / dormant wallet value (free)","description":"Use when a wallet may hold value it does not know about. Checks: native + USDC balances on Base, Ethereum, Polygon, Arbitrum One and BNB Chain; Aave V3 supplied collateral/debt on Base + Ethereum (plus the aUSDC detail); Aave V2 and Compound V2 positions on Ethereum. Returns a scoped report — exactly what was checked and what was not (merkle/airdrop claim distributors are NOT scanned in v1). Scan and report only: no custody, no keys, no claim execution; recovery needs the owner’s own signature. Body: {address}. Free — no payment required. Fee terms: Flow earns 15% of recovered value, charged only after the owner’s claim succeeds; $0 if nothing is recovered. A GET returns the how-doc.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","description":"EVM wallet address to scan (0x + 40 hex chars). 'wallet' is accepted as an alias."}},"required":["address"]}}}},"responses":{"200":{"description":"Scoped scan report: findings per chain with USD estimates where a price is available, totals, the exact checked/not-checked scope, and next steps."},"400":{"description":"Malformed address."},"429":{"description":"Rate limited (max 10 scans per minute per IP)."}}},"get":{"summary":"Found-money scan how-doc (free)","responses":{"200":{"description":"The how document: endpoint, body shape, fee terms, and the exact scan scope. With ?address=0x… it runs the scan."}}}},"/api/exchange/listings":{"get":{"summary":"Problem Exchange board (free read)","description":"The Problem Exchange board as data: every listing with its funding state, reason codes, doors, bids, and — on graded DONE solves — solution and verdict. Listings follow the problem-listing/0.1 schema (JSON Schema: https://flow-kg4x.vercel.app/schemas/problem-listing-0.1.json). Optional filters: ?status=OPEN|WATCH|... and ?door=ROUTE|BYPASS|DONE. Free — no payment, no API key.","parameters":[{"name":"status","in":"query","required":false,"description":"Filter by listing status (OPEN, WATCH, GRADED_PASS, SETTLED, ...).","schema":{"type":"string"}},{"name":"door","in":"query","required":false,"description":"Filter by door offered: ROUTE, BYPASS, or DONE.","schema":{"type":"string"}}],"responses":{"200":{"description":"Board envelope: service, schema, schema_url, counts, listings (problem-listing/0.1 records), recent events.","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"Exchange state unavailable."}}}},"/api/exchange/listing":{"get":{"summary":"One Problem Exchange listing, full record","description":"Returns one listing by id (e.g. PX-0001) with bids, solution, verdict, and the full history its history_root commits to. The response carries a Link: <https://flow-kg4x.vercel.app/schemas/problem-listing-0.1.json>; rel=\"describedby\" header. Free.","parameters":[{"name":"id","in":"query","required":true,"description":"Listing id, PX-NNNN.","schema":{"type":"string","pattern":"^PX-[0-9]{4}$"}}],"responses":{"200":{"description":"The listing record (problem-listing/0.1).","content":{"application/json":{"schema":{"$ref":"https://flow-kg4x.vercel.app/schemas/problem-listing-0.1.json"}}}},"400":{"description":"Missing or malformed id."},"404":{"description":"No listing with that id on the board."}}}},"/api/exchange/solver":{"get":{"summary":"Problem Exchange solver record","description":"A solver's exchange record (exchange-solver-record/0.1; JSON Schema: https://flow-kg4x.vercel.app/schemas/exchange-solver-record-0.1.json): solved / failed / graded counts that move only on real verdict-engine grades. With no id, returns the list of solver ids that have records. A solver with no graded history has no record — 404, never a fabricated card. Free.","parameters":[{"name":"id","in":"query","required":false,"description":"Solver id as it appears on listings (e.g. flowexecutor).","schema":{"type":"string"}}],"responses":{"200":{"description":"The solver record, or the index of solver ids when id is omitted.","content":{"application/json":{"schema":{"$ref":"https://flow-kg4x.vercel.app/schemas/exchange-solver-record-0.1.json"}}}},"404":{"description":"No exchange record for that solver."}}}},"/api/exchange/bypass":{"get":{"summary":"Problem Exchange BYPASS payload (x402)","description":"The BYPASS door: a verified workaround for a listed problem, sold as data behind the x402 gate. The price is set per listing in its bypass_offer (PX-0001: $0.005). Delivery returns the payload and its evidence; it does not close the listing — the DONE door stays open for a full solve. GET or POST; the id rides the query string either way.","parameters":[{"name":"id","in":"query","required":true,"description":"Listing id carrying a bypass offer, PX-NNNN.","schema":{"type":"string","pattern":"^PX-[0-9]{4}$"}}],"responses":{"200":{"description":"listing, title, summary, payload, evidence, note.","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required — x402 v2 exact, USDC on Base (eip155:8453); amount is the listing's own bypass_offer price (PX-0001: $0.005)."},"404":{"description":"No such listing, or the listing carries no bypass offer."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.005000"},"protocols":[{"x402":{}}]}}},"/api/fill":{"post":{"summary":"Pay-for-improvement execution rail (x402, dynamic price)","description":"Path C, live: POST an intended swap (tokenIn, tokenOut, amountIn as addresses + atomic string). Flow measures the improvement over the baseline route at a pinned block and answers 402 with a challenge priced at 25% of YOUR measured improvement (capped at 10 bps of output), payable in USDC on Base via x402 v2 exact. Retry with the X-PAYMENT header to receive the executable route package; you swap wallet-to-DEX yourself. Flow never holds funds. A GET returns the terms document.","responses":{"200":{"description":"Route package with terms + measurement evidence."},"402":{"description":"Payment required — amount is 25% of the measured improvement for this swap, capped at 10 bps."}}},"get":{"summary":"Fill rail terms (free)","description":"The terms + call-shape document for POST /api/fill.","responses":{"200":{"description":"Terms document."}}}},"/api/builder-key":{"post":{"summary":"Claim a free Early Builder Key (100 calls)","description":"Body {address, botName?} — one key per wallet address, shown once. The key carries 100 free calls across /api/quote, /api/verify, /api/verdict, /api/signals, /api/smart-wallets and /api/wallet-check, sent as the x-flow-builder-key header. GET ?address= reads calls used/remaining (never the key). GET with no address returns the program offer. Free.","responses":{"200":{"description":"Key issued (POST) or status/offer (GET)."}}},"get":{"summary":"Builder Key status / program offer","description":"?address=0x… — issued?, callsUsed, callsRemaining for that wallet. No address — the program offer + live issuance count. Free.","responses":{"200":{"description":"Status or offer."}}}},"/api/exchange/worker":{"post":{"summary":"Register / update a hub worker profile (wallet-signed)","description":"Body {wallet, name, headline?, skills?[], solver_id?, signature}; signature is personal_sign (EIP-191) of flow-exchange:register:<wallet, lowercase> by the wallet. Free.","responses":{"200":{"description":"The stored worker profile."},"401":{"description":"Signature does not recover to the wallet; the response carries the exact sign_message."}}},"get":{"summary":"One hub worker profile with its merged record","description":"?id=<wallet> returns the profile plus its exchange passport counts (solved / failed / graded), hub claims, and settled USD. Records move only on real grades and real settlements. Free.","responses":{"200":{"description":"Worker profile."},"404":{"description":"No hub worker with that wallet."}}}},"/api/exchange/workers":{"get":{"summary":"Hub worker directory","description":"Every registered worker with graded record and settled totals, ranked by the record. Free.","responses":{"200":{"description":"Directory."}}}},"/api/exchange/claim":{"post":{"summary":"Claim a listing (wallet-signed, first claim wins)","description":"Body {id, wallet, signature}; signature is personal_sign of flow-exchange:claim:<PX-ID>:<wallet, lowercase>. The listing must be OPEN or BIDDING and unclaimed. Free.","responses":{"200":{"description":"The recorded claim."},"409":{"description":"Already claimed, or the listing is not claimable."}}}},"/api/exchange/deliver":{"post":{"summary":"Deliver work on a claimed listing (wallet-signed)","description":"Body {id, wallet, text?, url?, signature}; signature is personal_sign of flow-exchange:deliver:<PX-ID>:<wallet, lowercase> by the claiming wallet. Delivery is graded by the verdict engine (the $0.02 DONE toll on /api/verify) before any escrow can release. Free.","responses":{"200":{"description":"The claim, marked DELIVERED, with the deliverable and its sha256."}}}},"/api/exchange/escrow":{"post":{"summary":"Lock a listing budget as a held authorization","description":"Body {id, payment} where payment is an x402 v2 payload whose EIP-3009 authorization pays the listing exact budget amount to the CLAIMED worker wallet. The authorization is stored UNSETTLED — the signature is the lock; it can only ever pay that worker that amount. Flow holds no funds. Free.","responses":{"200":{"description":"The escrow record, status HELD (signature never exposed)."},"409":{"description":"No active claim, no fixed budget, or an escrow is already held."}}},"get":{"summary":"Public escrow status","description":"?id=PX-0001 — poster, worker, amount, status (HELD / RELEASED), settlement tx when released. The authorization signature is never exposed. Free.","responses":{"200":{"description":"Escrow record."},"404":{"description":"No escrow on that listing."}}}},"/api/exchange/release":{"post":{"summary":"Settle a held escrow (operator only)","description":"Requires the x-exchange-key operator header and a GRADED_PASS listing. Settles the held authorization through the facilitator and marks the listing SETTLED only with the real settlement tx ref.","responses":{"200":{"description":"Escrow RELEASED + the SETTLED listing."},"409":{"description":"Listing is not GRADED_PASS, or the escrow is not HELD."}}}}},"servers":[{"url":"https://flow-kg4x.vercel.app"}]}