{"openapi":"3.1.0","info":{"title":"Liquid Agent — Buy & Invest in Tokenized Stocks On-Chain","version":"1.0.0","description":"Part of Liquid Agent, the money layer for humans and their agents: one USDC balance for yield, payments, and tokenized stocks, for people through the app and for agents over x402. This API lets you buy and invest in tokenized US stocks and ETFs on-chain from $1: NVIDIA, Apple, Meta and Alphabet. Mint your own vault holding a band-rebalanced stock basket, equal-weight or your custom portfolio, and rebalance or cash out any block. Self-priced NAV (no oracle), in-kind exit, no brokerage account, no project token. Reads are free; transactions return unsigned calldata the agent signs and broadcasts with its own gas.","contact":{"name":"Liquid Agent","url":"https://api.liquidagent.ai","email":"liquidagentai@gmail.com"},"x-guidance":"Liquid Agent is the money layer for humans and their agents: one USDC balance for yield, payments, and tokenized stocks, for people through the app and for agents over x402. This API is the agent-facing tokenized-stock index. It lets an agent mint its OWN vault holding a band-rebalanced basket of Coinbase's tokenized NVDA/META/AAPL/GOOGL on Base (eip155:8453). Reads are FREE; every POST returns an UNSIGNED {to,data,value,chainId} that YOU sign and broadcast with your own gas (the server never signs). Amounts are USDC-6 (2000000 = $2). weightsBps are basis points summing to 10000. FLOW: 1) GET /v1/basket — discover constituents + live prices + fees. 2) GET /v1/quote?usdc=<amount6> — preview shares + mint fee. 3) POST /v1/create-vault — unsigned createVault(); sign+broadcast (you become the sole strategist, the protocol Safe owns it for fees). 4) GET /v1/balance/<your-address> — your new vault address. 5) POST /v1/set-weights {vault,weightsBps:[4]} — optional custom allocation. 6) POST /v1/buy {vault,usdc,permit:true,owner} — EIP-712 permit to sign off-chain, then re-POST with permit:{deadline,signature} for ONE unsigned depositWithPermit tx (no approve; omit permit for legacy approve+deposit). 7) POST /v1/rebalance {vault} — move to your target. 8) GET /v1/vault/<vault> — NAV + weights (self-priced TWAP, no oracle). 9) POST /v1/redeem {vault,shares,inKind?} — exit to USDC or raw tokens (un-trappable, any block). REUSE: create-vault is a ONE-TIME step. To add funds later do NOT create again — GET /v1/balance/<you>, take vaults[0].vault, and POST /v1/buy into that same vault (each buy mints more shares). create-vault always makes a brand-new separate vault. Contracts: factory 0x1B205660780CbC57849019Df2BA64B719b00AEA8, USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913. Broadcast over any Base RPC (e.g. an x402 RPC); deposits swap precompile tokens so pass an explicit gas limit ~3,000,000."},"servers":[{"url":"https://api.liquidagent.ai"}],"externalDocs":{"description":"Open-source code examples (JavaScript/viem, Python/web3, curl) + README for the full create/buy/rebalance/exit flow.","url":"https://github.com/LiquidAgent/liquidagentx402"},"components":{"securitySchemes":{"siwx":{"type":"apiKey","in":"header","name":"SIGN-IN-WITH-X","description":"Sign-In with X wallet identity (EIP-4361). Optional; no payment."},"x402":{"type":"http","scheme":"x402","description":"Pay-per-call via x402 (exact scheme, EIP-3009 USDC on Base eip155:8453). Sign a USDC authorization; no account, no key held by the server."}}},"paths":{"/v1/guide":{"get":{"operationId":"get_v1_guide","summary":"START HERE. Plain-English guide: how to open your account, buy the tokenized-stock index from $1, check it, rebalance, and cash out. One call explains every other endpoint.","tags":["Liquid Agent"],"description":"START HERE. Plain-English guide: how to open your account, buy the tokenized-stock index from $1, check it, rebalance, and cash out. One call explains every other endpoint. Returns: {service,what,howItWorks,steps:[{step,do,call,why}],amounts,signing,network,fees,fullSpec}. Free (optional SIWX wallet identity, no payment). New here? Read GET /v1/guide first.","security":[{"siwx":[]}],"responses":{"200":{"description":"{service,what,howItWorks,steps:[{step,do,call,why}],amounts,signing,network,fees,fullSpec}","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/v1/basket":{"get":{"operationId":"get_v1_basket","summary":"Discover the tokenized stock index: invest in NVIDIA, Apple, Meta and Alphabet, with live prices and fees.","tags":["Liquid Agent"],"description":"Discover the tokenized stock index: invest in NVIDIA, Apple, Meta and Alphabet, with live prices and fees. Returns: {protocol,chainId,factory,usdc,feeSink,constituents:[{symbol,address,decimals,priceUsd}],fees,minDepositUsdc,flow}. Free (optional SIWX wallet identity, no payment). New here? Read GET /v1/guide first.","security":[{"siwx":[]}],"responses":{"200":{"description":"{protocol,chainId,factory,usdc,feeSink,constituents:[{symbol,address,decimals,priceUsd}],fees,minDepositUsdc,flow}","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/v1/vault/{address}":{"get":{"operationId":"get_v1_vault_address","summary":"Check a vault: its value (NAV), holdings, current vs target weights, and whether it needs rebalancing.","tags":["Liquid Agent"],"description":"Check a vault: its value (NAV), holdings, current vs target weights, and whether it needs rebalancing. Input: path: vault address. Returns: {vault,strategist,owner,navUsdc,nav,weightsBps[4],rebalanceNeeded,rebalanceBandBps,maxTvlUsdc,mintFeeBps}. Free (optional SIWX wallet identity, no payment). New here? Read GET /v1/guide first.","security":[{"siwx":[]}],"parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}}],"responses":{"200":{"description":"{vault,strategist,owner,navUsdc,nav,weightsBps[4],rebalanceNeeded,rebalanceBandBps,maxTvlUsdc,mintFeeBps}","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/v1/balance/{agent}":{"get":{"operationId":"get_v1_balance_agent","summary":"List what an address owns: every vault it holds, its shares, and current USD value.","tags":["Liquid Agent"],"description":"List what an address owns: every vault it holds, its shares, and current USD value. Input: path: agent address. Returns: {agent,vaultCount,vaults:[{vault,shares,valueUsdc,value}]}. Free (optional SIWX wallet identity, no payment). New here? Read GET /v1/guide first.","security":[{"siwx":[]}],"parameters":[{"name":"agent","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}}],"responses":{"200":{"description":"{agent,vaultCount,vaults:[{vault,shares,valueUsdc,value}]}","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/v1/quote":{"get":{"operationId":"get_v1_quote","summary":"Preview a purchase before you buy: shares you would receive and the fee, for a given USDC amount.","tags":["Liquid Agent"],"description":"Preview a purchase before you buy: shares you would receive and the fee, for a given USDC amount. Input: query: usdc=<amount USDC-6>. Returns: {usdcIn,mintFeeUsdc,netUsdc}. Free (optional SIWX wallet identity, no payment). New here? Read GET /v1/guide first.","security":[{"siwx":[]}],"parameters":[{"name":"usdc","in":"query","required":true,"schema":{"type":"string"},"description":"amount in USDC-6 (2000000 = $2)"}],"responses":{"200":{"description":"{usdcIn,mintFeeUsdc,netUsdc}","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/v1/create-vault":{"post":{"operationId":"post_v1_create-vault","summary":"Open your own vault (you control it, no one else). Returns a transaction for you to sign.","tags":["Liquid Agent"],"description":"Open your own vault (you control it, no one else). Returns a transaction for you to sign. Input: {} (empty body). Returns: unsigned {to,data,value,chainId} for createVault(). Free (optional SIWX wallet identity, no payment). New here? Read GET /v1/guide first.","security":[{"siwx":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"unsigned {to,data,value,chainId} for createVault()","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/v1/set-weights":{"post":{"operationId":"post_v1_set-weights","summary":"Set your custom stock allocation (default is equal weight). Returns a transaction for you to sign.","tags":["Liquid Agent"],"description":"Set your custom stock allocation (default is equal weight). Returns a transaction for you to sign. Input: {vault:address, weightsBps:[4 ints, sum 10000]}. Returns: unsigned {to,data,value,chainId} for setTargetWeights(uint16[]). Free (optional SIWX wallet identity, no payment). New here? Read GET /v1/guide first.","security":[{"siwx":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"unsigned {to,data,value,chainId} for setTargetWeights(uint16[])","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/v1/buy":{"post":{"operationId":"post_v1_buy","summary":"Buy tokenized stocks: invest USDC into your vault from $1. One tx via EIP-2612 permit (no approve), or legacy approve + deposit. Own NVIDIA, Apple, Meta and Alphabet on-chain.","tags":["Liquid Agent"],"description":"Buy tokenized stocks: invest USDC into your vault from $1. One tx via EIP-2612 permit (no approve), or legacy approve + deposit. Own NVIDIA, Apple, Meta and Alphabet on-chain. Input: {vault:address, usdc:string(USDC-6), minShares?:string, permit?:true|{deadline,signature}, owner?:address}. Returns: permit:true -> {typedData} to sign; permit:{deadline,signature} -> ONE unsigned depositWithPermit tx; no permit -> {steps:[approve,deposit]}. Free (optional SIWX wallet identity, no payment). New here? Read GET /v1/guide first.","security":[{"siwx":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"permit:true -> {typedData} to sign; permit:{deadline,signature} -> ONE unsigned depositWithPermit tx; no permit -> {steps:[approve,deposit]}","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/v1/redeem":{"post":{"operationId":"post_v1_redeem","summary":"SELL / cash out: redeem your basket shares to USDC, or take the raw stock tokens in-kind (un-trappable, any block). Anyone holding these shares can sell this way — no vault needed. Returns a transaction for you to sign.","tags":["Liquid Agent"],"description":"SELL / cash out: redeem your basket shares to USDC, or take the raw stock tokens in-kind (un-trappable, any block). Anyone holding these shares can sell this way — no vault needed. Returns a transaction for you to sign. Input: {vault:address, shares:string, minUsdcOut?:string, inKind?:bool}. Returns: unsigned {to,data,value,chainId} for redeem() (USDC) or redeemInKind() (raw tokens). Free (optional SIWX wallet identity, no payment). New here? Read GET /v1/guide first.","security":[{"siwx":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"unsigned {to,data,value,chainId} for redeem() (USDC) or redeemInKind() (raw tokens)","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/v1/rebalance":{"post":{"operationId":"post_v1_rebalance","summary":"Rebalance your vault back to its target weights. Returns a transaction for you to sign.","tags":["Liquid Agent"],"description":"Rebalance your vault back to its target weights. Returns a transaction for you to sign. Input: {vault:address}. Returns: unsigned {to,data,value,chainId} for rebalance(). Free (optional SIWX wallet identity, no payment). New here? Read GET /v1/guide first.","security":[{"siwx":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"unsigned {to,data,value,chainId} for rebalance()","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/v1/send":{"post":{"operationId":"post_v1_send","summary":"Send your basket to anyone: transfer your tokenized-stock shares (LQMAG4) to any wallet — gift or hand off to another agent, no vault needed on their end. The recipient can then hold it, SELL it (redeem to USDC or in-kind), or forward it. Returns a transaction for you to sign.","tags":["Liquid Agent"],"description":"Send your basket to anyone: transfer your tokenized-stock shares (LQMAG4) to any wallet — gift or hand off to another agent, no vault needed on their end. The recipient can then hold it, SELL it (redeem to USDC or in-kind), or forward it. Returns a transaction for you to sign. Input: {vault:address, to:address, shares:string}. Returns: unsigned {to,data,value,chainId} for transfer(to,shares). Free (optional SIWX wallet identity, no payment). New here? Read GET /v1/guide first.","security":[{"siwx":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"unsigned {to,data,value,chainId} for transfer(to,shares)","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/v1/signals":{"get":{"operationId":"getV1Signals","summary":"Basket signals: the whole basket's rebalancing signal in one call — returns, volatility, RSI, trend, relative strength, correlation, plus an inverse-volatility target-weight signal.","tags":["Liquid Agent"],"description":"PAID: $0.04 USDC per call via x402 (exact scheme, EIP-3009, Base eip155:8453). Quantitative signals for the tokenized NVDA/META/AAPL/GOOGL basket so an agent can decide weights in one call instead of visiting four sites, then execute via the free /v1/set-weights + /v1/rebalance. Aggregated data, not investment advice.","security":[{"x402":[]}],"parameters":[{"name":"vault","in":"query","required":false,"schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"description":"Optional. Your vault address. If provided, the response adds that vault's current weights and their drift vs the suggested (inverse-vol) weights, so you know exactly what to change."}],"x-payment":{"price":"0.04","currency":"USDC","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0x487b28A4FbbA8Cf46eb6E1d72e6959202Bb75e90","scheme":"exact"},"x-payment-info":{"protocols":[{"x402":{"scheme":"exact","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0x487b28A4FbbA8Cf46eb6E1d72e6959202Bb75e90"}}],"price":{"mode":"fixed","currency":"USD","amount":"0.04"}},"responses":{"200":{"description":"basket signals","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"x402 payment required (returns the payment challenge)","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/publish":{"post":{"operationId":"postV1Publish","summary":"Publish a live, shareable portfolio page for a vault (24h keep-alive).","tags":["Liquid Agent"],"description":"PAID: $0.25 USDC flat per publish via x402 (exact scheme, EIP-3009, Base eip155:8453). Mints or extends a shareable page at /v/<slug> showing the vault's holdings, allocation, live prices and signals for 24 hours; re-publish to keep it alive. Returns {viewUrl, slug, expiresAt}; your user opens the viewUrl with no wallet.","security":[{"x402":[]}],"x-payment":{"price":"0.25","currency":"USDC","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0x487b28A4FbbA8Cf46eb6E1d72e6959202Bb75e90","scheme":"exact"},"x-payment-info":{"protocols":[{"x402":{"scheme":"exact","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0x487b28A4FbbA8Cf46eb6E1d72e6959202Bb75e90"}}],"price":{"mode":"fixed","currency":"USD","amount":"0.25"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["vault"],"properties":{"vault":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"The vault to publish a page for."},"label":{"type":"string","description":"Optional page title, e.g. the user's name."},"brand":{"type":"object","description":"Optional agent branding {name,color,iconUrl}."}}}}}},"responses":{"200":{"description":"{viewUrl, slug, expiresAt}","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"x402 payment required (returns the payment challenge)","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}