# Liquid Agent — Tokenized Stock Index

> An agent-native, on-chain index of Coinbase's tokenized US stocks (NVDAc, METAc, AAPLc, GOOGLc) on Base. An AI agent mints its own ERC-4626 vault, buys a band-rebalanced stock basket from $1, sets custom weights, rebalances, and exits in-kind or to USDC any block. No oracle (self-priced TWAP NAV), no project token, fully self-custodial. Reads are free; every transaction is returned as UNSIGNED calldata the agent signs and broadcasts with its own gas. The server holds no key.

Base mainnet (chainId 8453). Auth is x402 / SIWX per request; discovery is permissionless, no API key, no account, no allowlist.

## Start here
- [Agent guide](https://api.liquidagent.ai/v1/guide): plain-English walkthrough of the whole lifecycle (create, buy, rebalance, exit).
- [Code examples (GitHub)](https://github.com/LiquidAgent/liquidagentx402): open-source, runnable code for the full create/buy/rebalance/exit flow — JavaScript (viem), Python (web3), and curl — plus README, OpenAPI, and this llms.txt.
- [OpenAPI 3.1 spec](https://api.liquidagent.ai/openapi.json): full machine-readable API.
- [x402 discovery manifest](https://api.liquidagent.ai/.well-known/x402): embedded agent playbook + resource catalog.
- [Agent card (A2A)](https://api.liquidagent.ai/.well-known/agent-card.json): agent-to-agent capability card.

## How to use it (create, buy, rebalance, exit)
1. GET https://api.liquidagent.ai/v1/basket - discover the 4 stocks, live prices, and fees (free).
2. GET https://api.liquidagent.ai/v1/quote?usdc=2000000 - preview shares + the 0.20% fee (optional; 2000000 = $2.00, USDC-6).
3. POST https://api.liquidagent.ai/v1/create-vault - SIGN + BROADCAST the returned unsigned tx; opens your vault (ONE time; you become the sole strategist).
4. GET https://api.liquidagent.ai/v1/balance/<your-address> - vaults[0].vault is your vault address.
5. POST https://api.liquidagent.ai/v1/set-weights {vault, weightsBps:[4 ints summing to 10000]} - SIGN + BROADCAST (optional; default is equal-weight).
6. POST https://api.liquidagent.ai/v1/buy {vault, usdc, permit:true, owner} - sign the returned EIP-712 permit OFF-CHAIN, re-POST with permit:{deadline,signature}, SIGN + BROADCAST the single depositWithPermit tx (from $1, NO approve). Buy into the SAME vault anytime; no need to create again.
7. GET https://api.liquidagent.ai/v1/vault/<vault> - check NAV, weights, and whether it needs rebalancing (free).
8. POST https://api.liquidagent.ai/v1/rebalance {vault} - SIGN + BROADCAST (optional; moves the vault back to target).
9. POST https://api.liquidagent.ai/v1/redeem {vault, shares, inKind?} - SIGN + BROADCAST; SELL / cash out to USDC (inKind:false) or take raw stock tokens (inKind:true, un-trappable), any block. This is how anyone holding shares sells — no vault needed.
10. POST https://api.liquidagent.ai/v1/send {vault, to, shares} - SIGN + BROADCAST; send your basket shares to any wallet (gift or hand off to another agent). The recipient needs no vault and can hold, sell, or forward them; irreversible once sent.

Signing: WRITE endpoints return an UNSIGNED {to,data,value,chainId}. Sign it with your own wallet and broadcast via eth_sendRawTransaction to any Base RPC. If gas estimation fails (deposit/rebalance/redeem swap B20 precompiles), pass gas ~3,000,000. Amounts are USDC-6 (1000000 = $1.00); weightsBps sum to 10000. The server holds no key. Full step-by-step with example requests + responses: https://api.liquidagent.ai/v1/guide

## Read endpoints (free)
- [GET https://api.liquidagent.ai/v1/basket](https://api.liquidagent.ai/v1/basket): the 4 constituents with live prices, factory, fees, and the flow.
- GET https://api.liquidagent.ai/v1/vault/{address}: a vault's NAV, current vs target weights, rebalance status.
- GET https://api.liquidagent.ai/v1/balance/{agent}: an agent's vaults, shares, and USD value.
- GET https://api.liquidagent.ai/v1/quote?usdc=<amount6>: preview shares + fee before buying (2000000 = $2).

## Transact endpoints (return unsigned calldata to sign + broadcast)
- POST https://api.liquidagent.ai/v1/create-vault: mint your own vault (one time; reuse it after).
- POST https://api.liquidagent.ai/v1/set-weights: set a custom allocation (bps, sum 10000).
- POST https://api.liquidagent.ai/v1/buy: buy the basket from $1 - one tx via EIP-2612 permit (no approve), or legacy approve + deposit.
- POST https://api.liquidagent.ai/v1/rebalance: move your vault to its target weights.
- POST https://api.liquidagent.ai/v1/redeem: SELL / cash out to USDC, or take raw pro-rata stock tokens in-kind (un-trappable). Anyone holding shares can sell this way — no vault needed.
- POST https://api.liquidagent.ai/v1/send: send your basket shares to any wallet (gift/hand off to another agent). Recipient needs no vault; they can hold, sell, or forward them.

## Paid endpoints (x402)
- GET https://api.liquidagent.ai/v1/signals ($0.04 USDC/call): the whole basket's rebalancing signal in ONE call so you don't hit four sites — per-stock returns, annualized 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> for current-vs-suggested drift.
- POST https://api.liquidagent.ai/v1/publish ($0.25 USDC flat): publish a live, shareable portfolio page for a vault at https://api.liquidagent.ai/v/<slug> for 24h (holdings, allocation, live prices, signals). Return the viewUrl to your user; they open it with no wallet, no login. Re-publish to keep it alive.
- POST https://api.liquidagent.ai/v1/gas (from $0.03 USDC per operation): GAS SPONSOR — an ERC-4337 paymaster (EntryPoint v0.8 on Base and Polygon; chainId: 137 for Polygon) paid over x402 in USDC on Base or Polygon. SOLANA too: POST https://api.liquidagent.ai/v1/gas/solana {transaction} with our sponsor as fee payer, pay from $0.03 in Solana USDC, get it back co-signed (GET the same URL for the sponsor address and rules). Standard ERC-7677 JSON-RPC (pm_getPaymasterStubData free, pm_getPaymasterData paid; the 402 rides inside the JSON-RPC response; not staked yet, so POST the signed operation back here instead of to a public bundler). Plain EOAs: POST /v1/gas {sender, calls} -> 402 (the quote) -> pay -> sign the typed data (+ EIP-7702 authorization if given) -> POST the signed operation to the same URL. Wallet already delegated to another EIP-7702 implementation (MetaMask etc.)? Add redelegate:true to that {sender, calls} body and sign the returned authorization: it re-points the wallet to Simple7702Account in the same transaction (owner = you, reversible). Or keep your delegation: any EntryPoint v0.8 account can bring its own operation: POST {userOperation} unsigned -> 402 -> pay -> sign it your account's way -> POST back; we dry-run and submit it (no bundler, no stake). Price = max($0.03, 1.3× the op's gas cap); the signed sponsorship locks gas limits + max fee. Details: GET https://api.liquidagent.ai/v1/gas.
Pay by signing a USDC authorization (x402 exact scheme, EIP-3009 USDC on Base or Polygon); every read above stays free.

- [System status](https://api.liquidagent.ai/v1/status): self-measured uptime, schema validity, and latency.

## Contracts (Base mainnet)
- BasketVaultFactory: 0x1B205660780CbC57849019Df2BA64B719b00AEA8
- USDC: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913