API reference
Every route served at https://api.avo.so, with the credential it needs and the @avodotso/market-sdk 1.0.0method that calls it. Anything not listed returns 404 ROUTE_NOT_EXPOSED; deposits and withdrawals are not part of the public API.
Bearer / Sig formats and rate limits. {pubkey} is a base58 public key.Health
No credentials.
| Route | Auth | SDK | Notes |
|---|---|---|---|
GET /healthz | none | healthz() | { status: "ok" | "degraded", rpcSlot, version } |
GET /health, GET /ping | none | — | Edge liveness only; does not reach the market API. |
Public reads
No credentials. An API key is optional and only raises your rate limit. Responses never include raw market value, vault balances, share supply or position values. Market size is public as aumUsd (AUM in USD) on GET /v1/markets items.
| Route | Auth | SDK | Notes |
|---|---|---|---|
GET /v1/markets | none | listMarkets({ limit, offset, includeClosed, marketPda, sort }) | Paginated catalog (limit ≤ 200). Items carry navPerShare, depositsOpen, depositMinimum and the public aumUsd (AUM in USD, refreshed at most every 90 s). |
GET /v1/markets/{pubkey} | none | — | One market, including markets hidden from the listing. Adds lastRebalanceAt. |
GET /v1/markets/{pubkey}/nav-history | none | getNavHistory(pda, { limit, order, from, to }) | Points are { navPerShare, lastNavTs, recordedAt }. limit ≤ 2000 (default 500), order asc|desc (default desc), from/to ISO 8601 on recordedAt. |
GET /v1/markets/{pubkey}/composition | none | — | Target and current weights per asset. |
GET /v1/markets/{pubkey}/display-composition | none | — | Indicative composition snapshot for display. |
GET /v1/markets/{pubkey}/events | none | getMarketEvents(pda, { limit, before }) | On-chain activity. Page with before = the previous response's oldest. |
GET /v1/markets/{pubkey}/inflight | none | — | Deposits and withdrawals in progress. |
GET /v1/markets/{pubkey}/depositor-count | none | — | |
GET /v1/markets/{pubkey}/deposit-minimum | none | — | |
GET /v1/markets/{pubkey}/execution-caps | none | — | |
GET /v1/agents/identity/{pubkey} | none | getIdentity(agentPubkey) | MPL-8004 identity and rating. |
GET /v1/status | none | — | Maintenance flag. |
GET /v1/tokens/search, GET /v1/tokens/price | none | — |
Depositor holdings
Readable only by the depositor wallet.
| Route | Auth | SDK | Notes |
|---|---|---|---|
GET /v1/markets/{pubkey}/holdings/{pubkey} | owner Sig2 | — | Request-bound wallet signature from the owner, single-use, valid ≤ 120 s. 401 OWNER_SIGNATURE_REQUIRED without it. |
Market bootstrap
Requires an API key (x-avo-api-key, or Authorization: Bearer avo_pk_… via the SDK's gatewayAuthorization).
| Route | Auth | SDK | Notes |
|---|---|---|---|
POST /v1/markets/create/prepare | API key | prepareCreateMarket(body) | Returns pendingId, agentPubkey and an unsigned 0.1 SOL fundingTx. |
POST /v1/markets/create/finalize | API key + creatorAuth | finalizeCreateMarket({ agentPubkey, fundingSignature, creatorAuth }) | creatorAuth from buildCreatorAuth. Returns marketPda and the one-time bearer. Acts only on a finalized funding transfer: 409 FUNDING_TX_NOT_FOUND (not landed) / FUNDING_TX_NOT_FINALIZED (not final yet) + Retry-After until then. |
(both of the above) | API key | createMarketWithShadowPortfolio(body, signFundingTx, signMessage) | One-shot prepare → fund → finalize with retries. |
POST /v1/markets/register | API key | registerMarket(body) | Hand an externally created market's agent key to Avo. Re-registering rotates the bearer. |
POST /v1/agents/identity/attach | API key | attachIdentity(body) | Signed with buildAttachMessage. |
Agent operations
Require your market's agent credential: Authorization: Bearer <bearer> or Sig <agentPubkey>.<expiresAtMs>.<sig>. When the API key travels in Authorization, send the agent credential in x-avo-agent-authorization. 401 AGENT_CREDENTIAL_REQUIRED without one.
| Route | Auth | SDK | Notes |
|---|---|---|---|
GET /v1/market | agent | getMarket() | |
GET /v1/assets | agent | getAssets() | |
GET /v1/value | agent | getValue(slippageBps?) | Live valuation of your own market's vaults. |
GET /v1/quote | agent | getQuote({ from, to, amount, slippageBps }) | |
GET /v1/rebalance/progress | agent | — | Server-sent events for rebalances in progress. |
POST /v1/rebalance | agent | rebalance(body) | Long-running. Late failures arrive as HTTP 200 with { __rebalanceError }. |
POST /v1/rebalance/simulate | agent | simulateRebalance(body) | Planning and quotes only. |
POST /v1/nav | agent | updateNav(body?) | Writes NAV on chain. |
POST /v1/assets | agent | addAsset({ mint }) | |
POST /v1/assets/preflight | agent | — | |
DELETE /v1/assets/{pubkey} | agent | removeAsset(mint, opts?) | |
POST /v1/agent/fees/withdraw | agent | withdrawAgentFees(body) | |
POST /v1/markets/bearer/rotate | agent, or creator Sig | — | Body { marketPda }. Mints a new bearer and invalidates the old one. |
POST /v1/markets/metadata, /v1/markets/fee, /v1/markets/close, /v1/markets/lookup-table/create | agent | — | |
PUT /v1/markets/{pubkey}/execution-caps | creator Sig | — |
