# UnlockBot API
> Pay-per-call crypto risk data for AI agents. No API key or signup: each call costs a few cents of USDC on Base mainnet, paid with the x402 v2 protocol (HTTP 402).

Use it before an agent buys a token (is it a honeypot? are whales dumping on exchanges? is a big unlock coming?) and to research tokens and wallets on Ethereum, Base and Arbitrum.

## How to pay (x402 v2)
1. GET the endpoint. You receive HTTP 402 with a base64 JSON `PAYMENT-REQUIRED` header (scheme "exact", network eip155:8453, asset USDC, payTo 0x21e4F3c6EcDb0F0CADC59511BF675B9BcBbeD304, amount in 6-decimal atomic units).
2. Sign an EIP-3009 transferWithAuthorization for that amount (any x402 client: @x402/fetch, @x402/axios, x402 Python, x402-enabled MCP wallets).
3. Repeat the same GET with header `PAYMENT-SIGNATURE: <base64 payload>`. You get 200 + JSON + a `PAYMENT-RESPONSE` header with the settlement tx.
- You are charged only on HTTP 200. 400 (bad input, checked before payment), 429 and 503 (upstream timeout) are never charged.
- Retrying the same signed payment on the same URL returns the same response again for free (idempotent, header X-Idempotent-Replay: true). A payment cannot be reused for a different URL.
- No gas needed: the facilitator submits the transfer.

## Endpoints
### GET /pre-trade-check  ($0.05 USDC)
Pre-trade check / rug check before buying a token: honeypot, token safety, unlocks, whale + smart money flows, one buy/avoid verdict.
The one call a trading agent should make before buying an ERC-20 on Ethereum, Base or Arbitrum. Combines /token-safety (honeypot & sell-tax simulation, contract permissions, proxy, holder concentration, liquidity, age), /whale-flows (24h net exchange flow) and /unlock-risk (when the contract is a tracked token, matched by address, never by ticker). Returns decision = proceed | caution | avoid, a 0-100 score, plain-English reasons and the full component reports. Keywords: pre-trade, should I buy, rug check, rug pull, honeypot, scam token, token safety, token unlock, whale, smart money, trading agent, memecoin, Base, Ethereum, Arbitrum.
Params: chain (ethereum|base|arbitrum), address (string)
Example: https://zeg5gyw3v84q.hostc.app/pre-trade-check?chain=ethereum&address=0xCa14007Eff0dB1f8135f4C25B34De49AB0d42766
Free sample output: https://zeg5gyw3v84q.hostc.app/demo/pre-trade-check

### GET /token-safety  ($0.03 USDC)
Honeypot & rug check / token safety scanner: buy-sell tax, mint, blacklist, proxy, owner, LP lock, holders (ERC-20 on Base, Ethereum, Arbitrum).
Scam and rug-pull screen for any ERC-20: honeypot + buy/sell tax simulation (honeypot.is), GoPlus security flags, and our own on-chain checks (EIP-1967 upgradeable proxy, owner/renounced, mint/pause/blacklist function selectors in bytecode). Plus verified source, holder concentration, DEX liquidity, LP lock and pair age. Returns a 0-100 risk score, level, verdict and flags with plain explanations and sources. Cached 15 min. Keywords: honeypot check, rug check, rug pull detector, token safety, token security, scam token, contract audit, buy tax, sell tax, mintable, blacklist, memecoin, GoPlus, Base, Ethereum.
Params: chain (ethereum|base|arbitrum), address (string)
Example: https://zeg5gyw3v84q.hostc.app/token-safety?chain=base&address=0x940181a94A35A4569E4529A3CDfB74e38FD98631
Free sample output: https://zeg5gyw3v84q.hostc.app/demo/token-safety

### GET /whale-flows  ($0.02 USDC)
Whale alerts & smart money exchange flows: large CEX deposits/withdrawals, net inflow/outflow, top movers.
Large ERC-20 transfers into and out of labelled centralized-exchange hot wallets (Binance, Coinbase, OKX, Bybit, Kraken, Gate, KuCoin, Bitfinex, Crypto.com) over the last N hours. Returns inflow, outflow, net exchange flow, a sell-pressure signal, per-exchange breakdown, top movers and the largest transfers with explorer links. Pass symbol= for a tracked token, or chain= and address= for any ERC-20. Keywords: whale alert, whale tracker, smart money, exchange inflow, exchange outflow, CEX flows, Binance, Coinbase, large transfers, on-chain analytics, sell pressure.
Params: symbol? (AERO|ARB|EIGEN|ENA|STRK|ZETA|ZK|ZRO), chain? (ethereum|base|arbitrum), address? (string), hours? (integer), min? (number)
Example: https://zeg5gyw3v84q.hostc.app/whale-flows?symbol=STRK&hours=24
Free sample output: https://zeg5gyw3v84q.hostc.app/demo/whale-flows

### GET /unlock-risk  ($0.01 USDC)
Token unlock / vesting risk: next unlock size vs circulating supply, CEX inflows, sell-pressure score.
Next scheduled token unlock for a tracked token (curated from primary sources): date, amount (with upper-bound/estimated-date flags), days until, % of circulating supply (CoinGecko), USD value, 24h whale exchange flows, and a 0-100 unlock risk score with explanation and sources. Keywords: token unlock, vesting, cliff, unlock schedule, supply inflation, dilution, sell pressure, tokenomics, airdrop unlock.
Params: symbol (APT|ARB|EIGEN|ENA|PYTH|STRK|ZETA|ZK|ZRO)
Example: https://zeg5gyw3v84q.hostc.app/unlock-risk?symbol=STRK
Free sample output: https://zeg5gyw3v84q.hostc.app/demo/unlock-risk

### GET /unlocks/upcoming  ($0.02 USDC)
Token unlock calendar: upcoming vesting unlocks in the next N days, sized vs supply.
Every curated token unlock in the next N days (default 30, max 365) with date, amount, precision flags (exact / estimated date / upper bound), label and primary source link. Keywords: token unlocks calendar, upcoming unlocks, vesting schedule, tokenomics, cliff unlock, supply events.
Params: days? (integer)
Example: https://zeg5gyw3v84q.hostc.app/unlocks/upcoming?days=30
Free sample output: https://zeg5gyw3v84q.hostc.app/demo/unlocks/upcoming

### GET /wallet-profile  ($0.05 USDC)
Wallet profiler: smart money / exchange / bot label, balances, activity across Ethereum, Base, Arbitrum.
Profile any EVM address across Ethereum, Base and Arbitrum: CEX label (if a known exchange wallet), type (eoa / contract_or_smart_wallet / centralized_exchange / fresh_unused / high_activity_bot_or_service), transaction counts, native ETH, USDC/USDT and tracked-token balances. Useful for counterparty checks and for judging who is behind a whale transfer. Keywords: wallet analysis, wallet profiler, smart money, portfolio, balances, address label, counterparty check, KYT, on-chain analytics.
Params: address (string)
Example: https://zeg5gyw3v84q.hostc.app/wallet-profile?address=0x28C6c06298d514Db089934071355E5743bf21d60
Free sample output: https://zeg5gyw3v84q.hostc.app/demo/wallet-profile

### GET /token-price  ($0.005 USDC)
Token price API: real-time DEX price, liquidity, volume, FDV for any ERC-20 (Base, Ethereum, Arbitrum).
Liquidity-weighted USD price of any ERC-20 across all DEX pools (DexScreener), with total liquidity, 1h/24h volume, price change, FDV/market cap, cross-pool spread (arbitrage hint) and the top 8 pools with links. Cached 60 s. Keywords: token price, crypto price, DEX price, liquidity, market cap, FDV, volume, price feed, oracle, DexScreener, memecoin price.
Params: chain (ethereum|base|arbitrum), address (string)
Example: https://zeg5gyw3v84q.hostc.app/token-price?chain=base&address=0x940181a94A35A4569E4529A3CDfB74e38FD98631
Free sample output: https://zeg5gyw3v84q.hostc.app/demo/token-price

### GET /new-tokens  ($0.02 USDC)
New token launches feed with auto honeypot / rug screening (new DEX pools, sniping research).
Tokens that got their first DEX pool in the last N hours on Base (default), Ethereum or Arbitrum (GeckoTerminal), ranked by 1h volume: price, liquidity, FDV, 1h buys/sells, price change. The top 10 are screened with /token-safety (honeypot, sell tax, risk score) and red flags are added (zero sells, fake liquidity). Built for sniping and launch-monitoring agents. Keywords: new tokens, new pairs, token launch, new listings, sniper, memecoin, Base memecoins, honeypot filter, rug check, early gems.
Params: chain? (ethereum|base|arbitrum), hours? (integer), limit? (integer), screen? (boolean)
Example: https://zeg5gyw3v84q.hostc.app/new-tokens?chain=base&hours=6&limit=10
Free sample output: https://zeg5gyw3v84q.hostc.app/demo/new-tokens

### GET /yields  ($0.01 USDC)
DeFi yields / best APY finder by asset and chain with risk notes (stablecoin yield, lending, LP).
Top DeFi yields from 15k+ pools (DefiLlama): filter by asset (e.g. USDC, ETH), chain, minimum TVL and stablecoin-only. Each pool has APY split into base and reward, a 30-day average, TVL, impermanent-loss risk and plain-English risk notes (emission-driven, APY spike, small TVL). Keywords: defi yields, best APY, stablecoin yield, USDC yield, lending rates, Aave, Morpho, staking, farming, DefiLlama, treasury.
Params: asset? (string), chain? (ethereum|base|arbitrum|optimism|polygon|solana|bsc|avalanche), min_tvl? (number), stablecoin? (boolean), limit? (integer)
Example: https://zeg5gyw3v84q.hostc.app/yields?asset=USDC&chain=base&limit=10
Free sample output: https://zeg5gyw3v84q.hostc.app/demo/yields

### GET /gas  ($0.001 USDC)
Gas price / gas fee tracker + forecast for Ethereum, Base, Arbitrum ($0.001, cheapest call).
Current base fee, 20-block average, block utilization, trend, next-block forecast, and suggested slow/standard/fast EIP-1559 fees from eth_feeHistory, plus the cost of an ETH transfer, an ERC-20 transfer and a swap in ETH. Our cheapest endpoint: a good first x402 call to test your payment setup. Keywords: gas price, gas fee, gas tracker, gwei, base fee, priority fee, transaction cost, when to transact, cheap.
Params: chain? (ethereum|base|arbitrum)
Example: https://zeg5gyw3v84q.hostc.app/gas?chain=ethereum
Free sample output: https://zeg5gyw3v84q.hostc.app/demo/gas

### GET /crypto-news  ($0.01 USDC)
Crypto news API with headline sentiment per token / topic.
Latest headlines from Cointelegraph, Decrypt and CryptoSlate (public RSS), filtered by keywords (e.g. q=bitcoin or q=solana,sol), each with a positive/negative/neutral tag, plus an aggregate sentiment score from -1 to 1. Cached 5 min. Keywords: crypto news, bitcoin news, news sentiment, headlines, market news, token news, RSS.
Params: q? (string), limit? (integer)
Example: https://zeg5gyw3v84q.hostc.app/crypto-news?q=bitcoin&limit=10
Free sample output: https://zeg5gyw3v84q.hostc.app/demo/crypto-news

### GET /due-diligence  ($0.05 USDC)
Token due diligence report (DD) in Markdown for LLM agents: rug check, honeypot, holders, whales, unlocks, news.
One call returns a ready-to-read Markdown due-diligence report for any ERC-20 on Ethereum, Base or Arbitrum. It covers verdict and risk score, key reasons, market data (price, liquidity, volume, FDV), contract safety (honeypot, taxes, proxy, owner, mint/blacklist), holders, whale exchange flows, token unlocks and news sentiment, plus structured JSON. Paste it straight into an LLM context or show it to a user. Keywords: due diligence, token research, DD report, rug check, honeypot, token safety, holders, whale, unlocks, sentiment, investment memo.
Params: chain (ethereum|base|arbitrum), address (string)
Example: https://zeg5gyw3v84q.hostc.app/due-diligence?chain=ethereum&address=0xCa14007Eff0dB1f8135f4C25B34De49AB0d42766
Free sample output: https://zeg5gyw3v84q.hostc.app/demo/due-diligence

### GET /address-check  ($0.005 USDC)
Scam / phishing / sanctioned (OFAC) address check before sending funds or approving (AML screening).
Screens any EVM address against public threat intelligence (GoPlus, which aggregates SlowMist, BlockSec and others): phishing, theft, sanctions (OFAC), money laundering, mixers, honeypot creators, fake tokens. Adds the exchange label, contract/EOA type and tx count. Returns a risk score and a verdict. Call it before every transfer or approval. Keywords: address screening, scam address, phishing, sanctions, OFAC, AML, KYT, mixer, Tornado Cash, drainer, wallet security.
Params: address (string), chain? (ethereum|base|arbitrum)
Example: https://zeg5gyw3v84q.hostc.app/address-check?address=0x098B716B8Aaf21512996dC57EB0615e2383E2f96
Free sample output: https://zeg5gyw3v84q.hostc.app/demo/address-check

### GET /tx-explain  ($0.01 USDC)
Transaction explainer / decoder: plain-English swaps, transfers, approvals (flags unlimited approvals).
Decodes an Ethereum, Base or Arbitrum transaction: a one-line plain-English summary, type (swap, transfer, approval, deployment), decoded method name, token transfers with symbols and amounts, approvals (flags UNLIMITED), event names, fee and status, plus risk notes. Good for agents that verify their own transactions or explain wallet activity to users. Keywords: decode transaction, explain transaction, tx decoder, swap, approval, unlimited approval, calldata, event logs, receipt.
Params: chain (ethereum|base|arbitrum), hash (string)
Example: https://zeg5gyw3v84q.hostc.app/tx-explain?chain=base&hash=0xbb45307b75671c41aafcbf97974497de6ea5194ee40437283f96f7148b68d7b0
Free sample output: https://zeg5gyw3v84q.hostc.app/demo/tx-explain

### GET /stablecoin-peg  ($0.002 USDC)
Stablecoin depeg monitor: USDC, USDT, DAI, USDe, FDUSD, PYUSD vs $1 ($0.002).
Live USD prices for 14 major stablecoins with deviation from the $1 peg, 24h change, market cap and a status (ok / watch / warning / DEPEGGED), plus alert lines. Cached 60 s. Cheap enough to poll before any stablecoin-denominated trade, payment or treasury move. Keywords: stablecoin, depeg, peg monitor, USDC, USDT, DAI, USDe, risk alert, treasury.
Params: 
Example: https://zeg5gyw3v84q.hostc.app/stablecoin-peg?
Free sample output: https://zeg5gyw3v84q.hostc.app/demo/stablecoin-peg

### GET /polymarket  ($0.005 USDC)
Polymarket odds / prediction market probabilities by keyword.
Current implied probabilities for active Polymarket markets that match keywords (e.g. q=bitcoin, q=fed,rates, q=election), ranked by 24h volume, with each outcome's probability %, volume, liquidity, end date and link. Without q you get the most-traded markets. Keywords: polymarket, prediction market, odds, probability, election odds, bitcoin odds, forecasting, betting.
Params: q? (string), limit? (integer)
Example: https://zeg5gyw3v84q.hostc.app/polymarket?q=bitcoin&limit=5
Free sample output: https://zeg5gyw3v84q.hostc.app/demo/polymarket

### GET /ens  ($0.002 USDC)
ENS resolver: .eth name to address and reverse lookup, avatar ($0.002).
Resolves an ENS name (vitalik.eth) to its address, or an address to its primary ENS name, with display name, avatar and our exchange label. Cached 1h. Keywords: ENS, .eth, name resolution, reverse lookup, resolve address, web3 identity, avatar.
Params: q (string)
Example: https://zeg5gyw3v84q.hostc.app/ens?q=vitalik.eth
Free sample output: https://zeg5gyw3v84q.hostc.app/demo/ens

### GET /liquidation-risk  ($0.005 USDC)
Liquidation risk / health factor monitor for Aave v3 & Spark positions by address ($0.005).
Aave v3 (Ethereum, Base, Arbitrum) and Spark (Ethereum) lending positions for any address: health factor, collateral, debt, LTV vs liquidation threshold, % collateral price drop that triggers liquidation, and a risk level (safe / low / medium / high / critical / liquidatable) with suggested actions. Read live from the Pool contracts, cached 30 s. Cheap enough to poll every few minutes as a liquidation alert. Keywords: liquidation risk, health factor, Aave, Aave v3, Spark, lending, borrow, LTV, liquidation alert, collateral, DeFi risk, position monitor.
Params: address (string), chain? (ethereum|base|arbitrum)
Example: https://zeg5gyw3v84q.hostc.app/liquidation-risk?address=0x52e31ea3c6367e2f777276cf75d42673b3786034
Free sample output: https://zeg5gyw3v84q.hostc.app/demo/liquidation-risk

### GET /approvals-audit  ($0.01 USDC)
Token approvals audit / revoke checker: risky & unlimited ERC-20 allowances for a wallet ($0.01).
Lists a wallet's active ERC-20 token approvals (allowances) on Ethereum, Base or Arbitrum, flags unlimited allowances, malicious or unverified spenders, EOA spenders and stale approvals, scores each, and says which to revoke. Data from GoPlus approval security, cached 2 min. Keywords: token approvals, allowance checker, revoke, revoke.cash, unlimited approval, wallet security, drainer, phishing approval, ERC-20 allowance, wallet audit.
Params: address (string), chain? (ethereum|base|arbitrum)
Example: https://zeg5gyw3v84q.hostc.app/approvals-audit?address=0x28C6c06298d514Db089934071355E5743bf21d60&chain=ethereum
Free sample output: https://zeg5gyw3v84q.hostc.app/demo/approvals-audit

### GET /governance  ($0.005 USDC)
DAO governance feed: active Snapshot proposals & vote results for Aave, Uniswap, Arbitrum, Optimism, Lido + 25 more ($0.005).
Latest Snapshot governance proposals for 30 major DAOs (Aave, Uniswap, Arbitrum, Optimism, ENS, Lido, Safe, Balancer, Convex, GMX, ApeCoin, Stargate, ...): title, state, time left, vote counts, leading choice and %, results, quorum, and a link, plus an 'ending soon' list. Filter by dao=aave,uniswap and state=active|closed|pending|all. Cached 2 min. Keywords: DAO governance, Snapshot, proposals, voting, vote results, Aave governance, Uniswap governance, Arbitrum DAO, Optimism, quorum, governance alerts.
Params: dao? (string), state? (active|closed|pending|all), limit? (integer)
Example: https://zeg5gyw3v84q.hostc.app/governance?state=active&limit=10
Free sample output: https://zeg5gyw3v84q.hostc.app/demo/governance

### GET /swap-risk  ($0.005 USDC)
Swap MEV / sandwich risk estimate + recommended slippage for a proposed trade ($0.005).
Before you swap: estimates price impact across the token's top DEX pools, how much a sandwich bot could extract within your slippage tolerance, attacker cost, net MEV risk (low/medium/high), and the recommended slippage. Tells you when to use a private RPC or intent DEX. Works for any ERC-20 on Ethereum, Base and Arbitrum. Heuristic model, documented in the response. Keywords: MEV, sandwich attack, front-running, slippage, price impact, swap simulation, trade size, private RPC, Flashbots, MEV protection, DEX trade, best execution.
Params: chain (ethereum|base|arbitrum), token (string), amount_usd (number), slippage_pct? (number)
Example: https://zeg5gyw3v84q.hostc.app/swap-risk?chain=ethereum&token=0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984&amount_usd=50000&slippage_pct=3
Free sample output: https://zeg5gyw3v84q.hostc.app/demo/swap-risk

## Response format
Success: {"ok":true,"endpoint":"...","version":"2.4.2","as_of":"ISO-8601","query":{...},"partial":false,"warnings":[],"data":{...}}
If an upstream source is down you still get data, with partial=true and the reason in warnings. Every report includes sources[] links.
Error: {"ok":false,"error":{"code":"bad_request|rate_limited|upstream_unavailable|payment_already_used","message":"...","hint":"..."}}

## Coverage
Chains: ethereum, base, arbitrum. Unlock schedules: APT, ARB, EIGEN, ENA, PYTH, STRK, ZETA, ZK, ZRO. Whale-flow symbols: ARB, AERO, STRK, ENA, EIGEN, ZRO, ZETA, ZK (any ERC-20 via chain+address).

## Free resources
- https://zeg5gyw3v84q.hostc.app/openapi.json: OpenAPI 3.1 with x-payment-info
- https://zeg5gyw3v84q.hostc.app/tools.json: MCP-style tool definitions (name, description, inputSchema)
- https://zeg5gyw3v84q.hostc.app/recommend?goal=is+this+token+a+honeypot: FREE recommender, describe your goal and get the right paid endpoint
- Stable docs + current base URL: https://unlockbot.surge.sh/api/ and https://unlockbot.surge.sh/api.json (use these if this hostname changes)
- Local MCP server (stdio, pays with your own x402 wallet): npx -y https://unlockbot.surge.sh/mcp/onchain-intel-x402.tgz  (Official MCP Registry: sh.surge.unlockbot/onchain-intel)
- https://zeg5gyw3v84q.hostc.app/mcp: MCP server (streamable HTTP; tools/list and tools/call return free samples and the paid URL)
- https://zeg5gyw3v84q.hostc.app/.well-known/x402: x402 discovery
- https://zeg5gyw3v84q.hostc.app/.well-known/x402.json: x402 v2 resource manifest (accepts[] per endpoint)
- https://zeg5gyw3v84q.hostc.app/demo: sample responses for every endpoint
- https://zeg5gyw3v84q.hostc.app/symbols: coverage

Free trial: send header "X-Free-Trial: true" on GET /gas to get one free call per client (later calls cost $0.001). Free endpoints are limited to 60 requests/min per client. Data comes from public sources (GoPlus, honeypot.is, CoinGecko, on-chain RPC, project docs). Not financial advice.