liquidagentx402

# Liquid Agent — Tokenized Stock Index for AI Agents (x402 · Base)

> **Buy tokenized US stocks on-chain, from an AI agent.** Mint your own vault holding a basket of Coinbase's tokenized **NVDA, META, AAPL, GOOGL** on Base — buy from **$1**, rebalance anytime, cash out any block. No oracle, no project token, fully self-custodial. Reads are free; every transaction is returned as **unsigned calldata** your agent signs and broadcasts with its own gas. The server holds no key.

**Live API:** https://api.liquidagent.ai · **Agent guide:** https://api.liquidagent.ai/v1/guide · **Status:** https://api.liquidagent.ai/v1/status

**Also here: [Liquid Bridge](#liquid-bridge-x402--move-usdc-between-base-and-arc-in-one-signature)**, the one-signature USDC bridge for x402 agents (Base <-> Arc). Refer other agents and earn 20% of the fee.

`x402` · `AI agents` · `tokenized stocks` · `Base` · `ERC-4626` · `ERC-8004` · `agentic commerce` · `no oracle` · `self-custodial`

---

## What is this?

**Liquid Agent** is an **agent-native tokenized-stock index** on Base. An autonomous agent (or a human) can:

- **Discover** the index and live prices over plain HTTP — no API key, no account, no allowlist.
- **Mint its own vault** (ERC-4626) holding a band-rebalanced basket of Coinbase's tokenized **NVDA / META / AAPL / GOOGL**.
- **Buy from $1**, set custom weights, rebalance, and **exit any block** — to USDC, or the raw stock tokens in-kind (un-trappable).

Every **read is free**. Every **write returns an unsigned transaction** the agent signs with its own wallet and broadcasts with its own gas (or hands it to the **gas sponsor** and pays in USDC) — **the server never holds a key**, so there's no account to create and nothing to steal.

Built for the agent economy: **x402-discoverable**, an **A2A agent card**, `llms.txt` / `agents.txt`, and a permissionless **ERC-8004 on-chain identity** (agentId `74094` on Base).

## Why an agent picks this

Instead of picking four stocks, sizing each, buying them separately, and rebalancing by hand, an agent makes **one call** and owns a single auto-rebalanced share of a diversified tokenized-equity basket — self-priced (no oracle), redeemable any block, with no project token, all reachable over a live HTTP + x402 API.

## MCP server (remote, no install)

[![smithery badge](https://smithery.ai/badge/chris-tv1s/liquidagent)](https://smithery.ai/servers/chris-tv1s/liquidagent)

Connect any MCP client (Claude, Cursor, ChatGPT, agent frameworks) by URL: `https://api.liquidagent.ai/mcp` (Streamable HTTP, no auth). Listed in the official MCP Registry as `ai.liquidagent.api/liquid-agent` and on [Smithery](https://smithery.ai/servers/chris-tv1s/liquidagent).

```bash
claude mcp add --transport http liquid-agent https://api.liquidagent.ai/mcp
```

```json
{ "mcpServers": { "liquid-agent": { "type": "streamable-http", "url": "https://api.liquidagent.ai/mcp" } } }
```

19 tools:
- **Bridge:** `bridge_quote`, `bridge_prepare_payment`, `bridge_routes`, `bridge_status`, `bridge_referral_earnings`
- **Stocks:** `stocks_basket`, `stocks_portfolio`, `stocks_buy_quote`, `stocks_vault`, `stocks_create_vault`, `stocks_set_weights`, `stocks_buy`, `stocks_sell`, `stocks_rebalance`, `stocks_send` (write tools return an unsigned transaction you sign yourself)
- **Paid prep:** `stocks_signals_prepare` ($0.005), `stocks_publish_prepare` ($0.01)
- **Other:** `gas_sponsor_info`, `liquid_guide`

Plus 4 doc resources and 3 prompts (bridge USDC, earn referrals, buy the basket). All free. Paid actions return the exact x402 payment request; your agent pays with its own wallet. The server never signs or holds funds.

## Discovery (machine-readable, self-hosted)

| Doc | URL |
|-----|-----|
| **Agent guide (full procedure)** | https://api.liquidagent.ai/v1/guide |
| OpenAPI 3.1 | https://api.liquidagent.ai/openapi.json |
| x402 discovery manifest | https://api.liquidagent.ai/.well-known/x402 |
| x402 resource catalog | https://api.liquidagent.ai/.well-known/x402-resources |
| A2A agent card | https://api.liquidagent.ai/.well-known/agent-card.json |
| ERC-8004 registration | https://api.liquidagent.ai/.well-known/erc8004.json |
| llms.txt | https://api.liquidagent.ai/llms.txt |
| MCP server card | https://api.liquidagent.ai/.well-known/mcp/server.json |
| MCP Registry entry | [`mcp-server.json`](mcp-server.json) |

## Agent skill (OpenClaw · ClawHub · skills.sh)

A ready-made skill that teaches an agent the whole flow lives in [`skills/liquid-agent-stocks/SKILL.md`](skills/liquid-agent-stocks/SKILL.md).

```bash
clawhub install liquid-agent-stocks          # OpenClaw / ClawHub — the stock index
clawhub install liquid-gas-sponsor           # OpenClaw / ClawHub — the gas sponsor (transact with USDC only, no ETH)
npx skills add LiquidAgent/liquidagentx402   # skills.sh (any agent that reads SKILL.md): all three skills, incl. liquid-usdc-bridge
```

## Quickstart — create → buy → rebalance → exit

Reads are free. Writes return an unsigned `{to,data,value,chainId}` (or `{steps:[...]}`) that **you sign and broadcast**.

```bash
BASE=https://api.liquidagent.ai

# 1. Discover the index (free)
curl -s $BASE/v1/basket

# 2. Preview a $2 buy (free; USDC-6, so 2000000 = $2.00)
curl -s "$BASE/v1/quote?usdc=2000000"

# 3. Open your vault (ONE time) — returns an unsigned tx; sign + broadcast it
curl -s -X POST $BASE/v1/create-vault -H 'content-type: application/json' -d '{}'

# 4. Find your vault address
curl -s $BASE/v1/balance/0xYourAddress          # -> vaults[0].vault

# 5. (optional) Set custom weights — bps summing to 10000; sign + broadcast
curl -s -X POST $BASE/v1/set-weights -H 'content-type: application/json' \
  -d '{"vault":"0xYourVault","weightsBps":[4000,2000,2000,2000]}'

# 6. Buy in — ONE tx, no approve: get an EIP-2612 permit payload, sign it OFF-CHAIN,
#    then exchange the signature for a single unsigned depositWithPermit tx
curl -s -X POST $BASE/v1/buy -H 'content-type: application/json' \
  -d '{"vault":"0xYourVault","usdc":"2000000","permit":true,"owner":"0xYourAddress"}'
#    -> {typedData} ... sign with eth_signTypedData_v4, then:
curl -s -X POST $BASE/v1/buy -H 'content-type: application/json' \
  -d '{"vault":"0xYourVault","usdc":"2000000","permit":{"deadline":<from typedData>,"signature":"0x..."}}'
#    (omit `permit` entirely for the legacy approve + deposit two-step)

# 7. Check your vault (free)
curl -s $BASE/v1/vault/0xYourVault

# 8. (optional) Rebalance to target — sign + broadcast
curl -s -X POST $BASE/v1/rebalance -H 'content-type: application/json' -d '{"vault":"0xYourVault"}'

# 9. Cash out — to USDC or raw tokens; sign + broadcast
curl -s -X POST $BASE/v1/redeem -H 'content-type: application/json' \
  -d '{"vault":"0xYourVault","shares":"<amount>","inKind":false}'
```

**Signing:** every write returns an unsigned `{to,data,value,chainId}`. Sign it with your own wallet and broadcast via `eth_sendRawTransaction` to any Base RPC. `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**.

Runnable examples: [`examples/buy.js`](examples/buy.js) (viem) · [`examples/buy.py`](examples/buy.py) (Python) · [`examples/read.sh`](examples/read.sh) (curl).

## Endpoints

**Reads (free):** `GET /v1/basket` · `GET /v1/vault/{address}` · `GET /v1/balance/{agent}` · `GET /v1/quote?usdc=` · `GET /v1/guide`
**Writes (return unsigned calldata):** `POST /v1/create-vault` · `/v1/set-weights` · `/v1/buy` · `/v1/rebalance` · `/v1/redeem` *(sell / cash out)* · `/v1/send` *(transfer to any wallet)*
**Paid (x402):** `GET /v1/signals` *($0.005 — the basket's rebalancing signal in one call)* · `POST /v1/publish` *($0.01 — a live, shareable portfolio page)* · `POST /v1/gas` *(from $0.03 — the gas sponsor: transact with USDC only, no ETH)* · `GET /v1/bridge` *(1% — the one-signature USDC bridge, Base <-> Arc)*

An agent can **buy** the basket, **sell** it any block (`/v1/redeem` → USDC or the raw stocks in-kind), and **send** it to any wallet (`/v1/send`) — gift or hand a whole tokenized-stock basket to another agent in one transfer, no vault needed on their end.

Full spec in [`openapi.json`](openapi.json).

## Paid: basket signals (x402)

`GET /v1/signals` — **$0.005 USDC per call** — one call returns the whole basket's rebalancing signal, so an agent doesn't have to visit 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` → `POST /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, on Base) — any x402-aware client handles the 402 automatically:

```bash
curl -s https://api.liquidagent.ai/v1/signals            # -> 402 with the x402 payment challenge
# an x402 client (AgentCash, x402-fetch, CDP) pays the $0.005, then receives:
# { "basket":[{symbol,returns,volAnnualPct,rsi14,trend,relStrengthM1}, ...],
#   "basketStats":{ "correlation": {...} },
#   "signals":{ "riskParityWeightsBps":[...], "biasVsEqualWeightBps":[...], "momentumRankDesc":[...] } }
```

Everything else stays **free**; the paid resources are signals, publish, the gas sponsor, and the bridge below.

## Paid: gas sponsor (x402) — transact with USDC only, no ETH

Most agent wallets hold USDC and nothing else. `POST /v1/gas` is an **ERC-4337 paymaster you pay per operation in USDC over x402**: no ETH, no account, no API key. Price is `max($0.03, 1.3 × the operation's gas cap)`; the signed sponsorship locks the gas limits and max fee, so the sponsor can never charge more than it quoted. **One endpoint, the body picks the lane:**

**Smart-wallet SDKs (ERC-7677).** Point the SDK's paymaster URL at `https://api.liquidagent.ai/v1/gas`. `pm_getPaymasterStubData` is free; an unpaid `pm_getPaymasterData`