# Liquid Agent — agent guide

- **service**: Liquid Agent: Money Tools for AI Agents
- **what**: Open your own on-chain vault that holds a basket of Coinbase's tokenized US stocks (NVDA, META, AAPL, GOOGL) on Base. Buy from $1, rebalance whenever you want, and cash out any block. No project token, no oracle.
- **howItWorks**: Reads are FREE and need no auth. Every WRITE endpoint returns an UNSIGNED transaction {to,data,value,chainId} that YOU sign with your own wallet and broadcast to Base with your own gas — or, with no ETH at all, hand it to the gas sponsor (step 7: POST /v1/gas, paid per operation in USDC over x402). The server never holds a key, there is no account, and nothing to steal. Network: Base mainnet (eip155:8453).
## addresses

- **chain**: Base
- **chainId**: 8453
- **factory**: 0x1B205660780CbC57849019Df2BA64B719b00AEA8
- **usdc**: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
- **feeSink**: 0x7475e9e0ee7c0d9f1abcaffb74f5f4e195ef3703
### constituents

- symbol: NVDAc; name: NVIDIA; address: 0xb20000000000000000000078ee7ce2fE4908108C; decimals: 8
- symbol: METAc; name: Meta; address: 0xb2000000000000000000008bC8786B856E61707C; decimals: 8
- symbol: AAPLc; name: Apple; address: 0xb200000000000000000000C2e324d24d7eEcd1fb; decimals: 8
- symbol: GOOGLc; name: Alphabet; address: 0xb2000000000000000000002D0BA3164cc74f58B7; decimals: 8

- **onchainIdentity**: erc8004: eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432/74094

## steps

- step: 1; do: Discover the index; call: GET /v1/basket; request: GET https://api.liquidagent.ai/v1/basket; returns: {constituents:[{symbol,address,priceUsd}], factory, usdc, fees, minDepositUsdc, flow}; next: Free read. You now have the 4 stocks, live prices, and fees.
- step: 2; do: Preview a purchase (optional); call: GET /v1/quote?usdc=<amount6>; request: GET https://api.liquidagent.ai/v1/quote?usdc=2000000; returns: {usdcIn, mintFeeUsdc, netUsdc}; next: Free. 2000000 = $2.00 (USDC-6). Shows shares + the 0.20% mint fee before you commit.
- step: 3; do: Open your vault (ONE TIME); call: POST /v1/create-vault; request: POST https://api.liquidagent.ai/v1/create-vault  body: {}; returns: unsigned {to,data,value,chainId} for createVault(); next: SIGN + BROADCAST it (see `signing`). You become the vault's sole strategist. Do this ONCE, then reuse the vault forever.
- step: 4; do: Find your vault address; call: GET /v1/balance/<your-address>; request: GET https://api.liquidagent.ai/v1/balance/0xYourAddress; returns: {agent, vaultCount, vaults:[{vault, shares, value}]}; next: vaults[0].vault is your vault. Returning later? START HERE (skip step 3) then jump to step 6.
- step: 5; do: Set custom weights (optional); call: POST /v1/set-weights; request: POST https://api.liquidagent.ai/v1/set-weights  body: {"vault":"0x...","weightsBps":[4000,2000,2000,2000]}; returns: unsigned tx for setTargetWeights(uint16[]); next: SIGN + BROADCAST. bps must sum to 10000; default is equal-weight 2500 each; each weight moves <=2000 bps per call.
- step: 6; do: Buy in (repeat anytime) — ONE tx, no approve; call: POST /v1/buy; request: POST https://api.liquidagent.ai/v1/buy  body: {"vault":"0x...","usdc":"2000000","permit":true,"owner":"0xYourAddress"}; returns: {typedData} — an EIP-712 permit payload. Sign it OFF-CHAIN (eth_signTypedData_v4, free), then re-POST with {"vault":...,"usdc":...,"permit":{"deadline":<from typedData>,"signature":"0x..."}} to get ONE unsigned depositWithPermit tx.; next: SIGN + BROADCAST that single tx. From $1, 0.20% mint. Buy into the SAME vault as often as you like. (Omit `permit` entirely for the legacy approve+deposit two-step.)
- step: 7; do: No ETH? Let the gas sponsor pay (optional, from $0.03 USDC via x402); call: POST /v1/gas; request: POST https://api.liquidagent.ai/v1/gas  body: {"sender":"0xYourAddress","calls":[{"to":<tx.to>,"data":<tx.data>,"value":"0"}]}  (direct lane; the unsigned tx from step 3, 5, 6, 9 or 10). Smart accounts: see lanes.bringYourOwnOperation below.; returns: HTTP 402 = the exact USDC quote for this operation (valid 120 s). Pay it with your usual x402 signature (X-PAYMENT) and repeat the same call -> {userOperation, typedData, authorization?, validUntil}.; next: Sign typedData with your key (eth_signTypedData_v4) -> userOperation.signature. If authorization is present (first time only) sign it too (EIP-7702). POST {userOperation, authorization} back to the SAME URL before validUntil: we submit it and our deposit pays the gas. No further charge.; how: One URL, two ways in; pick the lane that matches your wallet. Both pay one x402 fee per operation, and the 402 you get first IS the quote.; lanes: {"direct":{"for":"a plain EOA with no smart-account SDK. First use delegates it to Simple7702Account via EIP-7702 (owner = you, reversible).","request":"POST https://api.liquidagent.ai/v1/gas  body: {\"sender\":\"0xYourAddress\",\"calls\":[{\"to\":\"0x..\",\"data\":\"0x..\",\"value\":\"0\"}]}","returns":"402 = the quote. Pay it and repeat -> {userOperation, typedData, authorization? (first time only), validUntil}.","next":"Sign typedData (eth_signTypedData_v4) -> userOperation.signature; sign the authorization if given (viem: account.signAuthorization). POST {userOperation, authorization} back to the same URL before validUntil.","alreadyDelegatedElsewhere":"If your EOA is already EIP-7702-delegated to another implementation (MetaMask, etc.) the first call returns 409. Add \"redelegate\": true to the same body and the sponsor returns an authorization you sign that re-points your wallet to Simple7702Account (owner = you, reversible, applied in the same transaction). Or keep your delegation and use bringYourOwnOperation.","example":"https://github.com/LiquidAgent/liquidagentx402/blob/main/examples/gasless.js"},"bringYourOwnOperation":{"for":"any EntryPoint v0.8 smart account: a wallet already delegated to another EIP-7702 implementation, or a deployed Kernel / Safe / Nexus account. You build the operation with your own SDK; we submit it. No bundler, no paymaster stake.","request":"POST https://api.liquidagent.ai/v1/gas  body: {\"userOperation\":{\"sender\":\"0xYourAccount\",\"nonce\":\"0x..\",\"callData\":\"0x..\",\"callGasLimit\":\"0x..\",\"verificationGasLimit\":\"0x..\",\"preVerificationGas\":\"0x..\",\"maxFeePerGas\":\"0x..\",\"maxPriorityFeePerGas\":\"0x..\",\"signature\":\"0x\"}}  (hex quantities as strings; add factory/factoryData if the account is not deployed yet; no paymaster fields yet)","returns":"402 = the quote for THIS operation (the gas limits you declared set the cap). Pay it with X-PAYMENT and repeat -> {userOperation (now with paymaster, paymasterData, paymasterVerificationGasLimit, paymasterPostOpGasLimit), typedData, validUntil}.","next":"Sign the returned userOperation the way YOUR account expects (viem: account.signUserOperation; Simple7702 = eth_signTypedData_v4 of typedData). POST {userOperation} with the signature back to the same URL before validUntil. We dry-run it through the EntryPoint first: a failing dry run returns 400 with the reason, costs nothing and can be retried; a passing one is submitted from our wallet and our deposit pays the gas.","example":"https://github.com/LiquidAgent/liquidagentx402/blob/main/examples/gasless-bring-your-own.js"},"erc7677":"Smart-wallet SDKs may also use this URL as an ERC-7677 paymaster (pm_getPaymasterStubData free, pm_getPaymasterData paid; the 402 rides inside the JSON-RPC error). Public bundlers only relay staked paymasters and this one is not staked yet, so after pm_getPaymasterData send the signed operation back here (bringYourOwnOperation), not to a bundler."}; price: max($0.03, 1.3 × gas cap); the signed sponsorship locks the gas limits and max fee, so we can never charge more than the quote. Details: GET /v1/gas?docs=1 (a bare GET returns the 402 quote).
- step: 8; do: Check the vault anytime; call: GET /v1/vault/<vault>; request: GET https://api.liquidagent.ai/v1/vault/0xYourVault; returns: {navUsdc, nav, weightsBps[4], rebalanceNeeded, rebalanceBandBps, mintFeeBps}; next: Free. NAV, current vs target weights, and whether it needs rebalancing. Self-priced TWAP, no oracle.
- step: 9; do: Rebalance (optional); call: POST /v1/rebalance; request: POST https://api.liquidagent.ai/v1/rebalance  body: {"vault":"0x..."}; returns: unsigned tx for rebalance(); next: SIGN + BROADCAST. Moves your vault back to its target weights. Permissionless; the caller earns nothing.
- step: 10; do: Sell / cash out any block; call: POST /v1/redeem; request: POST https://api.liquidagent.ai/v1/redeem  body: {"vault":"0x...","shares":"<amount>","inKind":false}; returns: unsigned tx for redeem() (inKind:false -> USDC) or redeemInKind() (inKind:true -> raw stock tokens); next: SIGN + BROADCAST. This is how you SELL: it burns your shares and pays you. Partial or full. inKind:true is price-free and un-trappable, works even if the price source is down.
- … (1 more)

## signing

- **how**: Every WRITE returns an unsigned {to,data,value,chainId} (or {steps:[...]}). The data ends with an ERC-8021 attribution suffix (Base Builder Code); contracts ignore it, so sign and broadcast it exactly as returned. Sign it with the wallet that owns the funds (viem: walletClient.sendTransaction; ethers equivalent), then broadcast via eth_sendRawTransaction to ANY Base RPC (e.g. https://mainnet.base.org or an x402 RPC like https://blockrun.ai/api/v1/rpc/base).
- **gas**: deposit / rebalance / redeem swap B20 precompile tokens, which break naive public-RPC gas estimation. If estimation fails, pass an explicit gas limit of ~3,000,000.
- **order**: For /v1/buy PREFER the one-tx permit flow: POST with {permit:true, owner} -> sign the returned EIP-712 typedData off-chain -> re-POST with {permit:{deadline,signature}} -> broadcast the single depositWithPermit tx. Agents never need an approve. Legacy two-step (approve then deposit) still works if you omit `permit`.
- **keys**: The server NEVER signs and holds no key. Only YOU sign. There is no API key and no account to create.

- **amounts**: USDC amounts are USDC-6 integers: 1000000 = $1.00, 2000000 = $2.00. weightsBps are basis points summing to exactly 10000, e.g. [4000,2000,2000,2000] = NVDA 40 / META 20 / AAPL 20 / GOOGL 20 (order matches `addresses.constituents`).
- **reuse**: One vault per agent is the norm: call create-vault ONCE, then top it up by calling POST /v1/buy on that same vault address whenever you want. To add funds later, do NOT create a new vault, fetch your existing one via GET /v1/balance/<your-address> and buy into vaults[0].vault. create-vault always mints a brand-new, separate vault.
- **network**: Base (eip155:8453) — paid x402 endpoints also accept USDC on Polygon (eip155:137) and Arc (eip155:5042)
- **fees**: 20 bps (0.20%) mint on buy, 90 bps/yr (0.90%) management, no performance fee. Min deposit $1.
## chainTools

### preflight

- **endpoint**: POST /v1/gas/preflight
- **price**: $0.005
- **body**: {to,from?,data?,value?}

### batchPreflight

- **endpoint**: POST /v1/gas/preflight/batch
- **price**: $0.005 + $0.002 per additional call (20 max, $0.043)
- **body**: {calls:[...]}

### decoder

- **endpoint**: POST /v1/gas/decode
- **price**: $0.003
- **body**: {chain,txHash,abi}
#### chains

- 8453
- 137
- 42161
- 10
- 43114


### logs

- **endpoint**: POST /v1/chain/logs
- **price**: $0.005 per started 1,000 blocks
- **body**: {chain,address,topics,fromBlock,toBlock,abi?}
#### chains

- 8453
- 137
- 42161
- 10
- 43114


### enrich

- **endpoint**: POST /v1/leads/enrich
- **price**: $0.01 per input that finds a business; misses free
- **body**: {records:[{domain}|{phone}]}


- **fullSpec**: https://api.liquidagent.ai/openapi.json | https://api.liquidagent.ai/.well-known/x402 | https://api.liquidagent.ai/.well-known/x402-resources
- **examples**: https://github.com/LiquidAgent/liquidagentx402 — open-source, copy-paste code for this exact flow: JavaScript (viem) and Python (web3) that create a vault, buy, rebalance and redeem, plus curl reads, the OpenAPI spec, and llms.txt. Start there if you want working code.
## quickstart

- **clone**: git clone https://github.com/LiquidAgent/liquidagentx402
- **js**: cd liquidagentx402/examples && npm install viem
- **python**: pip install web3
- **run**: node examples/gasless.js (JS) or python3 examples/buy.py (Python) — see the repo README for the full flow
- **note**: No SDK to install and no API key: the examples call this API directly with viem (JS) or web3.py (Python).

- **auth**: No sign-in, no account, no API key. Reads are free; paid endpoints return HTTP 402 with an x402 v2 challenge — sign a USDC (EIP-3009) authorization with your own wallet and send it in the X-PAYMENT header. Free reads may carry an optional SIGN-IN-WITH-X (EIP-4361) identity header. Authorization metadata: /.well-known/oauth-authorization-server
- **catalog**: https://api.liquidagent.ai/.well-known/api-catalog
- **signals**: OPTIONAL PAID ($0.007 USDC via x402): GET https://api.liquidagent.ai/v1/signals returns the whole basket's rebalancing signal in ONE call so you don't hit four sites — per-stock returns/volatility/RSI/trend/relative-strength, a correlation matrix, and an inverse-volatility suggested weightsBps you can drop straight into POST /v1/set-weights (then /v1/rebalance). Add ?vault=<yours> to also get current-vs-suggested drift for your vault. Pay by signing a USDC authorization (x402 exact scheme, EIP-3009); everything above stays free.
- **publish**: OPTIONAL PAID ($0.01 USDC flat via x402): POST https://api.liquidagent.ai/v1/publish {vault,label?} mints a live, shareable portfolio page at https://api.liquidagent.ai/v/<slug> for 24h — holdings, allocation, live prices and signals. Return the viewUrl to your user; they open it with NO wallet and NO login. Re-publish to keep it alive; the page goes dormant when you stop. Check status: GET https://api.liquidagent.ai/v1/published/<vault>.
- **leads**: OPTIONAL PAID ($0.03 per lead, flat, USDC on Base or Arc via x402): LIQUID LEADS, verified US local business leads. GET https://api.liquidagent.ai/v1/leads/search?category=<dentist|plumber|hvac|...>&city=<Atlanta>&limit=<1-1000> returns businesses with a graded email (A/B/C), a contact name when the email shows one, phone, a website proven by the business's own phone number, socials and buying signals. Free first: GET https://api.liquidagent.ai/v1/leads (coverage and filters), https://api.liquidagent.ai/v1/leads/count (how many match and the exact price), and sample=1 for 3 free leads.
- **security**: OPTIONAL PAID (quick $0.01, full $0.05 USDC via x402, on Base or Arc): WEBSITE WATCHER, security intelligence for autonomous agents. POST https://api.liquidagent.ai/v1/link/check/agent {url, quick} returns a fixed-schema assessment: verdict (safe / suspicious / dangerous / unknown), score 0-100, action (allow / review / block / retry), one-sentence summary, top findings, category scores and facts. Quick ($0.01): lookalike/typosquat detection, in-house IOC list, page content and brand checks, page-script malware patterns. Full ($0.05): DNS and SSL, domain age (direct WHOIS), brand impersonation (titles, logos, favicons, login/wallet intent, multi-brand pages), wallet address extraction, redirect chain, forms and JS behavior. No payment returns HTTP 402 — sign an EIP-3009 USDC authorization and send it in the X-PAYMENT header. Repeat scans within 1 hour return the cached result free. Unknown stays unknown: a paid scan never implies a security guarantee. MALWARE SCANNER ($0.05 per scan, USDC via x402, on Base or Arc): static PolinRider / Contagious Interview malware scan before installing, building, or running code. POST https://api.liquidagent.ai/v1/malware/scan {filename, content} scans one file; POST https://api.liquidagent.ai/v1/malware/scan-batch {files} scans up to 100 files (2 MB each, 10 MB total); POST https://api.liquidagent.ai/v1/malware/scan-repo {repoUrl} scans a public GitHub repo (working tree + history). All return verdict (clean / suspicious / dangerous), score 0-100, action (allow / review / block), summary, top findings and facts. The scanner runs on an isolated VPS; the API fronts it. API DOCTOR (diagnose $0.50, test-spec $2.00, audit $5.00 USDC via x402, on Base, Polygon or Arc): 'This API is broken for me — tell me exactly what is wrong and give me a request that works.' POST /v1/api/diagnose {url, method, headers, query, body, docsUrl|spec} calls the endpoint live and returns verdict (working / working_but_slow / broken), failure class (auth, not_found, wrong_method, bad_request, server_error, timeout, schema_mismatch, ...), auth diagnostics, schema validation against the declared spec, deterministic corrections, and a working example request (curl + JSON). POST /v1/api/test-spec {specUrl|spec, samples} validates the OpenAPI spec and probes every endpoint. POST /v1/api/audit {specUrl|spec, samples} adds auth diagnostics, full schema validation, and a corrected request per endpoint. Public endpoints only in v1: no credentials are accepted, sent, stored, or logged.
- **web**: OPTIONAL PAID (USDC via x402, on Base, Polygon or Arc): WEB & CHAIN. GET https://api.liquidagent.ai/v1/search?q=<query> ($0.005 per search) returns ranked web results with LLM-ready excerpts. GET https://api.liquidagent.ai/v1/extract?url=<https://...> ($0.002 per page) turns any public web page into clean Markdown. GET https://api.liquidagent.ai/v1/rpc?op=<block|balance|tx>&chain=<base|arc> ($0.002 flat per read) reads the latest block, a native or ERC-20 balance (?op=balance&address=0x...&token=0x... for ERC-20, omit token for native), or a transaction's details (?op=tx&hash=0x...) on Base or Arc — no key, no account. Chain them: search, extract, then POST /v1/link/check/agent to scan what you found.
- **polymarket**: OPTIONAL PAID ($0.004 USDC via x402): POLYMARKET PRICE TO BEAT. GET https://api.liquidagent.ai/v1/polymarket/<asset>-<5m|15m> (btc, eth, sol, xrp) returns the official price to beat for the live Up/Down window, live Chainlink price and distance, seconds left, token ids and market prices. Polymarket's public API only publishes it after the window closes. ?start=<unix> for a past window's official outcome. Index: https://api.liquidagent.ai/v1/polymarket
- **bridge**: OPTIONAL PAID (one x402 signature, 1% fee plus Circle's network fee, all in the quote): LIQUID BRIDGE, the one-signature USDC bridge for x402 agents. Move USDC from Base to 16 chains or from Arc to Base: GET https://api.liquidagent.ai/v1/bridge?from=base&to=<chain>&amount=1 where chain is arc, arbitrum, optimism, polygon, avalanche, unichain, linea, world, sonic, monad, sei, ink, hyperevm, xdc, plume or codex (pay on Base; about $1.035 to receive $1 on Arc, about $1.07 to $1.13 elsewhere), or ?from=arc&to=base (pay on Arc). The 402 is the exact price; sign one EIP-3009 payment to the payTo and repeat the call; you receive exactly the amount at your own address in about 20 s. Add ref=<your address> to earn 20% of the fee, on-chain. Guide: https://api.liquidagent.ai/v1/bridge/guide
- **gas**: OPTIONAL PAID (from $0.03 USDC via x402): GAS SPONSOR. If your wallet holds USDC but no ETH, you can still transact on Base or Polygon (add chainId: 137 for Polygon), and on Solana via POST /v1/gas/solana. Standard ERC-4337 paymaster (ERC-7677 pm_getPaymasterStubData / pm_getPaymasterData at POST https://api.liquidagent.ai/v1/gas for EntryPoint v0.8) — point any smart-wallet SDK at it; the price comes back inside the JSON-RPC response as error {code:402,data:<x402 PaymentRequired>}, pay with your usual x402 signature in params[3].context.x402. Public bundlers only relay staked paymasters and this one is not staked yet, so POST the signed operation back to the same URL and we submit it (no bundler needed). Plain-EOA agents: POST https://api.liquidagent.ai/v1/gas {sender, calls} -> 402 (the quote) -> pay and repeat the call -> sign the returned typed data (and EIP-7702 authorization if given) -> POST the signed operation back to the same URL; we submit, our deposit pays the gas. Any other EntryPoint v0.8 account can bring its own operation the same way: POST {userOperation} unsigned -> 402 -> pay -> sign -> POST back; we dry-run it and submit, no bundler or stake needed. Price = max($0.03, 1.3× the op's gas cap); the cap is signed so we can never charge more. Read GET https://api.liquidagent.ai/v1/gas.
