{"openapi":"3.1.0","info":{"title":"PoolPulse API","description":"Pre-computed DEX execution signals for autonomous DeFi agents on Base. CLMM slippage, liquidity profiles, pool state.","version":"0.2.0","contact":{"name":"PoolPulse"}},"servers":[{"url":"https://poolpulse.poolpulse.workers.dev","description":"Production"}],"paths":{"/health":{"get":{"summary":"Health check","description":"Returns API status, last indexed block, and version. Free, no auth.","responses":{"200":{"description":"API is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"last_indexed_block":{"type":"integer","nullable":true},"version":{"type":"string"}}}}}}}}},"/v1/pools":{"get":{"summary":"List indexed pools","description":"Returns the current set of indexed pools. Free, no auth. Use this for discovery.","responses":{"200":{"description":"Pool list","content":{"application/json":{"schema":{"type":"object","properties":{"chain":{"type":"string"},"pool_count":{"type":"integer"},"pools":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string"},"token0":{"type":"string"},"token1":{"type":"string"},"fee":{"type":"integer"},"dex":{"type":"string"}}}}}}}}}}}},"/v1/pool/{chain}/{address}/state":{"get":{"summary":"Pool state (T1 Sentinel)","description":"Returns pool liquidity, current tick, sqrtPriceX96, and tick data. $0.001/call. Requires X-Wallet header with credit balance.","parameters":[{"name":"chain","in":"path","required":true,"schema":{"type":"string","enum":["base"]}},{"name":"address","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}},{"name":"X-Wallet","in":"header","required":true,"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}}],"responses":{"200":{"description":"Pool state returned"},"402":{"description":"Insufficient credit or missing payment"},"404":{"description":"Pool not indexed"}}}},"/v1/pool/{chain}/{address}/slippage":{"get":{"summary":"Slippage computation (T2 Execution)","description":"Returns size-aware CLMM slippage for a given input amount. $0.02/call. Requires X-Wallet header.","parameters":[{"name":"chain","in":"path","required":true,"schema":{"type":"string","enum":["base"]}},{"name":"address","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"}},{"name":"amount_in","in":"query","required":true,"schema":{"type":"string","description":"Token0 amount in wei (smallest unit)"}},{"name":"X-Wallet","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Slippage result","content":{"application/json":{"schema":{"type":"object","properties":{"chain":{"type":"string"},"pool":{"type":"string"},"amount_in":{"type":"string"},"slippage":{"type":"object","properties":{"price_impact_bps":{"type":"integer"},"amount_out":{"type":"string"},"effective_price":{"type":"number"},"ticks_crossed":{"type":"integer"},"liquidity_sufficient":{"type":"boolean"}}}}}}}},"400":{"description":"Invalid chain or amount"},"402":{"description":"Insufficient credit"},"404":{"description":"Pool not indexed"}}}},"/v1/pool/{chain}/{address}/alpha":{"get":{"summary":"MEV Alpha analysis (T3)","description":"Returns slippage + MEV exposure score (0-100) + sandwich risk + private relay recommendation. $0.25/call.","parameters":[{"name":"chain","in":"path","required":true,"schema":{"type":"string","enum":["base"]}},{"name":"address","in":"path","required":true,"schema":{"type":"string"}},{"name":"amount_in","in":"query","required":false,"schema":{"type":"string"}},{"name":"X-Wallet","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Alpha result with MEV score and slippage"},"402":{"description":"Insufficient credit"},"404":{"description":"Pool not indexed"}}}},"/v1/simulate":{"get":{"summary":"Pre-trade simulation (T3)","description":"Best route across all indexed pools. Gas-adjusted net output, MEV risk, alternatives. $0.25/call.","parameters":[{"name":"token_in","in":"query","required":true,"schema":{"type":"string","description":"Input token symbol (e.g. WETH)"}},{"name":"token_out","in":"query","required":false,"schema":{"type":"string","description":"Output token symbol (e.g. USDC)"}},{"name":"amount_in","in":"query","required":true,"schema":{"type":"string","description":"Amount in smallest unit"}},{"name":"X-Wallet","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Simulation with best route, alternatives, gas, MEV assessment"},"402":{"description":"Insufficient credit"}}}},"/v1/forensics/{tx_hash}":{"get":{"summary":"Post-trade forensics (T2)","description":"Analyze a completed swap: Swap event decoding, actual slippage, gas cost, sandwich detection. $0.02/call.","parameters":[{"name":"tx_hash","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"}},{"name":"X-Wallet","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Forensics result"},"402":{"description":"Insufficient credit"}}}},"/v1/topup/requirements":{"get":{"summary":"Payment requirements","description":"Returns the USDC payment address and pricing information. Free, no auth.","responses":{"200":{"description":"Payment requirements"}}}},"/v1/topup":{"post":{"summary":"Top up credit balance","description":"Verify a USDC transfer on Base and credit the wallet balance. Send USDC to the payment address first, then call this with the tx hash.","parameters":[{"name":"X-Wallet","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tx_hash"],"properties":{"tx_hash":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"}}}}}},"responses":{"200":{"description":"Credit applied"},"403":{"description":"Payment verification failed"}}}},"/leaderboard":{"get":{"summary":"Public leaderboard","description":"Shows anonymized wallet activity. HTML by default, JSON with ?format=json or Accept: application/json.","parameters":[{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json"]}}],"responses":{"200":{"description":"Leaderboard data (HTML or JSON)"}}}}},"components":{"schemas":{"Error":{"type":"object","required":["error","message","retryable"],"properties":{"error":{"type":"string","enum":["POOL_NOT_INDEXED","INVALID_CHAIN","INVALID_AMOUNT","MISSING_PAYMENT","INSUFFICIENT_CREDIT","PAYMENT_VERIFICATION_FAILED","RATE_LIMITED","UPSTREAM_TIMEOUT","TICK_LIQUIDITY_EXHAUSTED","CLMM_MATH_ERROR","CONFIG_ERROR"]},"message":{"type":"string"},"retryable":{"type":"boolean"}}}}}}