{"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} — unsigned 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"}],"components":{"securitySchemes":{"siwx":{"type":"apiKey","in":"header","name":"SIGN-IN-WITH-X","description":"Sign-In with X wallet identity (EIP-4361). Optional; no payment."}}},"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 (approve + deposit). Own NVIDIA, Apple, Meta and Alphabet on-chain.","tags":["Liquid Agent"],"description":"Buy tokenized stocks: invest USDC into your vault from $1 (approve + deposit). Own NVIDIA, Apple, Meta and Alphabet on-chain. Input: {vault:address, usdc:string(USDC-6), minShares?:string}. Returns: {steps:[{label,to,data,value,chainId}]} — 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":"{steps:[{label,to,data,value,chainId}]} — 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":"Cash out to USDC, or take the raw stock tokens (un-trappable, any block). Returns a transaction for you to sign.","tags":["Liquid Agent"],"description":"Cash out to USDC, or take the raw stock tokens (un-trappable, any block). Returns a transaction for you to sign. Input: {vault:address, shares:string, minUsdcOut?:string, inKind?:bool}. Returns: unsigned {to,data,value,chainId} for redeem() or redeemInKind(). 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() or redeemInKind()","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"}}}}}}}}}}}