{"openapi":"3.1.0","info":{"title":"Beamswap Agent API","version":"1.0.0","description":"Pay-per-call Base data for AI agents. Payments via x402 (USDC on Base)."},"servers":[{"url":"https://api.beamswap.io"}],"paths":{"/v1/session":{"post":{"summary":"Exchange an EIP-712 Session signature for a 24h bearer token (quota holders only)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["address","issuedAt","signature"],"properties":{"address":{"type":"string"},"issuedAt":{"type":"integer"},"signature":{"type":"string"}}}}}},"responses":{"200":{"description":"{ token, expiresAt }"},"401":{"description":"bad signature"}}}},"/v1/openapi.json":{"get":{"summary":"This document (free, no payment required)","responses":{"200":{"description":"OpenAPI 3.1 document"}}}},"/v1/watch/{id}":{"get":{"summary":"State and recent deliveries of one watch (free; the id is the capability)","parameters":[{"name":"id","in":"path","required":true,"description":"Watch id returned by POST /v1/watch","schema":{"type":"string"}}],"responses":{"200":{"description":"{ id, type, params, status, expiresAt, lastCheckedAt, state, deliveries }"},"404":{"description":"no such watch"}}},"delete":{"summary":"Stop a watch (free, idempotent, no refund for the days left)","parameters":[{"name":"id","in":"path","required":true,"description":"Watch id returned by POST /v1/watch","schema":{"type":"string"}}],"responses":{"204":{"description":"the watch is no longer polled"}}}},"/v1/distribution/{id}":{"get":{"summary":"Distribution metadata and current funded balance (free)","parameters":[{"name":"id","in":"path","required":true,"description":"Distribution id returned by POST /v1/distribution","schema":{"type":"string"}}],"responses":{"200":{"description":"Distribution metadata, status and funded balance"},"404":{"description":"no such distribution"}}}},"/v1/distribution/{id}/claims.csv":{"get":{"summary":"Creator-only cumulative allocation CSV (free; bearer session required)","parameters":[{"name":"id","in":"path","required":true,"description":"Distribution id returned by POST /v1/distribution","schema":{"type":"string"}}],"responses":{"200":{"description":"address,cumulativeAmount CSV"},"403":{"description":"session address is not the creator"},"404":{"description":"no such distribution"}}}},"/v1/token/{address}":{"get":{"summary":"Token facts for a Base ERC-20: metadata, supply, deployer, price, round-trip quote","description":"Base token facts: metadata, supply, deployer, USD price, round-trip liquidity check (quote-based proxy).","x-x402":{"price":"$0.005","network":"eip155:8453","asset":"USDC","discounts":{"tier1":"10%","tier2":"25%","tier3":"40%"}},"parameters":[{"name":"address","in":"path","required":true,"description":"ERC-20 contract address","example":"0x55B423D0189F2315073DFb49845ea9eFFD9815A4","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"address":"0x55b423d0189f2315073dfb49845ea9effd9815a4","name":"Beamswap Token","symbol":"GLINT","decimals":18,"totalSupply":"1941031836082027011050588144","deployer":{"address":"0xe598c65f960a8c39b539f31cabf2c28f1567fd54","txHash":"0x9e1c0a3f2b7d4e5a6c8f0b1d2e3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a"},"usdPrice":0.0123,"liquidity":{"buyQuoteOk":true,"sellQuoteOk":true,"roundTripLossBps":180},"asOf":"2026-09-14T00:00:00.000Z"}}}},"400":{"description":"Invalid input (no payment requested)."},"402":{"description":"Payment required (x402). Body lists `accepts`."}}}},"/v1/portfolio/{address}":{"get":{"summary":"ETH + ERC-20 balances of a Base address with USD values","description":"All ERC-20 + ETH balances of a Base address with USD values.","x-x402":{"price":"$0.02","network":"eip155:8453","asset":"USDC","discounts":{"tier1":"10%","tier2":"25%","tier3":"40%"}},"parameters":[{"name":"address","in":"path","required":true,"description":"Wallet address","example":"0xe598c65f960a8c39b539f31cabf2c28f1567fd54","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"address":"0xe598c65f960a8c39b539f31cabf2c28f1567fd54","chain":"base","asOf":"2026-09-14T00:00:00.000Z","totalUsd":"1002.00","assets":[{"contract":"native","symbol":"ETH","decimals":18,"balance":"500000000000000000","usdPrice":2000,"usdValue":"1000.00"}]}}}},"400":{"description":"Invalid input (no payment requested)."},"402":{"description":"Payment required (x402). Body lists `accepts`."}}}},"/v1/quote":{"get":{"summary":"Best swap output across Base aggregators (quote only, no calldata)","description":"Best swap output across Base aggregators (quote only, no calldata).","x-x402":{"price":"$0.005","network":"eip155:8453","asset":"USDC","discounts":{"tier1":"10%","tier2":"25%","tier3":"40%"}},"parameters":[{"name":"sell","in":"query","required":true,"description":"Token address or ETH","example":"ETH","schema":{"type":"string"}},{"name":"buy","in":"query","required":true,"description":"Token address or ETH","example":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","schema":{"type":"string"}},{"name":"amount","in":"query","required":true,"description":"Sell amount in the sell token’s smallest unit","example":"1000000000000000000","schema":{"type":"string"}},{"name":"slippageBps","in":"query","required":false,"description":"1..5000, default 50","example":"50","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"sell":"0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee","buy":"0x833589fcd6edb6e08f4c7c32d4f71b54bda02913","amountIn":"1000000000000000000","slippageBps":50,"best":{"source":"kyberswap","amountOut":"2010000000","minOut":"1999950000"},"sources":[{"source":"kyberswap","amountOut":"2010000000","error":null},{"source":"0x","amountOut":"2008400000","error":null}]}}}},"400":{"description":"Invalid input (no payment requested)."},"402":{"description":"Payment required (x402). Body lists `accepts`."}}}},"/v1/execute/route":{"post":{"summary":"Best swap route as ready-to-sign calldata, Beamswap fee included","description":"Best swap route across Base aggregators as ready-to-sign calldata, with a Beamswap fee of 10 bps (less for GLINT tiers) taken from the output token.","x-x402":{"price":"$0.01","network":"eip155:8453","asset":"USDC","discounts":{"tier1":"10%","tier2":"25%","tier3":"40%"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sell","buy","amount","from"],"properties":{"sell":{"type":"string","description":"Token address or ETH"},"buy":{"type":"string","description":"Token address or ETH"},"amount":{"type":"string","description":"Sell amount in the sell token’s smallest unit, as a decimal string"},"from":{"type":"string","description":"Address that will sign and send the transaction"},"recipient":{"type":"string","description":"Receiver of the output token; defaults to from"},"slippageBps":{"type":"integer","description":"1..2000, default 50"}}},"example":{"sell":"ETH","buy":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","amount":"1000000000000000000","from":"0xe598c65f960a8c39b539f31cabf2c28f1567fd54","recipient":"0xe598c65f960a8c39b539f31cabf2c28f1567fd54","slippageBps":50}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"sell":"0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee","buy":"0x833589fcd6edb6e08f4c7c32d4f71b54bda02913","amountIn":"1000000000000000000","from":"0xe598c65f960a8c39b539f31cabf2c28f1567fd54","recipient":"0xe598c65f960a8c39b539f31cabf2c28f1567fd54","slippageBps":50,"feeBps":10,"feeRecipient":"0x1111111111111111111111111111111111111111","deadline":1789000060,"best":{"source":"kyberswap","to":"0x6131B5fae19EA4f9D964eAc0408E4408b66337b5","data":"0x…","value":"1000000000000000000","gas":"210000","allowanceTarget":null,"expectedOut":"2008000000","minOut":"1997960000","feeAmount":null,"simulated":true,"simulation":{"ok":true,"reason":null}},"sources":[{"source":"kyberswap","expectedOut":"2008000000","error":null},{"source":"0x","expectedOut":"2006400000","error":null}],"notes":["Base has no public mempool, so sandwiching is limited to the sequencer. The route sets minOut and a 60 s deadline; that is the protection offered."]}}}},"400":{"description":"Invalid input (no payment requested)."},"402":{"description":"Payment required (x402). Body lists `accepts`."}}}},"/v1/watch":{"post":{"summary":"Watch Base balances or USD prices; signed webhook when a condition trips","description":"Watch Base balances or USD prices and get a signed webhook when a condition trips. Priced per item per day.","x-x402":{"price":"$0.01","network":"eip155:8453","asset":"USDC","discounts":{"tier1":"10%","tier2":"25%","tier3":"40%"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items","days","webhookUrl"],"properties":{"items":{"type":"array","description":"Conditions to watch, 1..50. Each is {type: balance_below|balance_above, address, token (address or \"native\"), threshold (wei string)} or {type: price_cross, token, usd, direction: above|below}."},"days":{"type":"integer","description":"How long to watch, 1..90 days. The price is $0.01 per item per day."},"webhookUrl":{"type":"string","description":"https URL on a public host, no credentials, max 2048 chars. Each trip POSTs the payload signed as x-beamswap-signature: sha256=HMAC-SHA256(secret, rawBody)."}}},"example":{"items":[{"type":"balance_below","address":"0xe598c65f960a8c39b539f31cabf2c28f1567fd54","token":"native","threshold":"100000000000000000"},{"type":"price_cross","token":"0x55B423D0189F2315073DFb49845ea9eFFD9815A4","usd":0.02,"direction":"above"}],"days":3,"webhookUrl":"https://hooks.example.com/beamswap"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"ids":["6f1f3a1e-9e2b-4a5c-8d7e-0b1c2d3e4f5a","7a2e4b2f-0f3c-4b6d-9e8f-1c2d3e4f5a6b"],"secret":"f3c1…64 hex chars…9ab2","expiresAt":"2026-09-18T00:00:00.000Z","price":"$0.06","webhookUrl":"https://hooks.example.com/beamswap"}}}},"400":{"description":"Invalid input (no payment requested)."},"402":{"description":"Payment required (x402). Body lists `accepts`."}}}},"/v1/distribution":{"post":{"summary":"Deploy a hosted ERC-20 merkle distribution on Base","description":"Build and deploy a hosted cumulative-merkle distribution for up to 100,000 Base addresses.","x-x402":{"price":"$50","network":"eip155:8453","asset":"USDC","discounts":{"tier1":"10%","tier2":"25%","tier3":"40%"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token","entries"],"properties":{"token":{"type":"string","description":"ERC-20 token contract address on Base"},"entries":{"type":"array","description":"1..100000 unique recipients with amounts in the token smallest unit"},"deadline":{"type":"integer","description":"Future Unix timestamp, at most 365 days away; defaults to 90 days"},"name":{"type":"string","description":"Distribution name, at most 80 characters"}}},"example":{"token":"0x55B423D0189F2315073DFb49845ea9eFFD9815A4","entries":[{"address":"0xe598c65f960a8c39b539f31cabf2c28f1567fd54","amount":"1000000000000000000"}],"deadline":1790000000,"name":"Community rewards"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"id":"6f1f3a1e-9e2b-4a5c-8d7e-0b1c2d3e4f5a","contract":"0x0000000000000000000000000000000000000001","root":"0x…","total":"1000000000000000000","rows":1,"feeBps":10,"fundTx":{"grossAmount":"1001001001001001002","approve":{"to":"0x…token","data":"0x…","value":"0"},"fund":{"to":"0x…factory","data":"0x…","value":"0"},"unpause":{"to":"0x…distributor","data":"0x…","value":"0"}},"claimUrl":"https://app.beamswap.io/d/6f1f3a1e-9e2b-4a5c-8d7e-0b1c2d3e4f5a"}}}},"400":{"description":"Invalid input (no payment requested)."},"402":{"description":"Payment required (x402). Body lists `accepts`."}}}},"/v1/distribution/{id}/proof/{address}":{"get":{"summary":"Proof and cumulative allocation for one distribution recipient","description":"Fetch one recipient proof for a hosted distribution.","x-x402":{"price":"$0.001","network":"eip155:8453","asset":"USDC","discounts":{"tier1":"10%","tier2":"25%","tier3":"40%"}},"parameters":[{"name":"id","in":"path","required":true,"description":"Distribution id returned by distribution creation","example":"6f1f3a1e-9e2b-4a5c-8d7e-0b1c2d3e4f5a","schema":{"type":"string"}},{"name":"address","in":"path","required":true,"description":"Recipient wallet address","example":"0xe598c65f960a8c39b539f31cabf2c28f1567fd54","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"address":"0xe598c65f960a8c39b539f31cabf2c28f1567fd54","cumulativeAmount":"1000000000000000000","proof":["0x…"],"root":"0x…","contract":"0x0000000000000000000000000000000000000001"}}}},"400":{"description":"Invalid input (no payment requested)."},"402":{"description":"Payment required (x402). Body lists `accepts`."}}}}}}