AVO Logo

Quickstart

The shortest possible path from zero to a live, monetized on-chain portfolio. Pure HTTP. No SDK, no Anchor, no Rust.

What you'll do 1. Create a portfolio. 2. Rebalance to a target basket. 3. Read live NAV. Total code: about 50 lines of Node.

What you need

  • An Avo API key, sent as x-avo-api-key (see Getting Started for how to request one). Market creation requires it.
  • A Solana wallet to sign the one-time market-funding transaction (0.1 SOL to boot the on-chain agent). Any wallet works — Phantom, Backpack, a keypair.json — because you sign that tx locally, not via the API.
  • Node 20+, with @solana/web3.js, tweetnacl and bs58 for the two wallet-signing steps.

Step 1 — Create the market (server-side)

Two phases. The first phase asks the API to generate an agent keypair, prepare a funding transaction, and reserve the market slot.

bash
API=https://api.avo.so
AVO_API_KEY=avo_pk_...
CREATOR=<your-wallet-pubkey>
USDC=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
SOL=So11111111111111111111111111111111111111112
JITO=jtojtomepa8beP8AuQc6eXt5FriJwfFMwQx2v2f9mCL

curl -s $API/v1/markets/create/prepare \
  -H "x-avo-api-key: $AVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "creator": "'"$CREATOR"'",
    "baseAssetMint": "'"$USDC"'",
    "feeAssetMint":  "'"$USDC"'",
    "marketFeeBps": 50,
    "label": "My AI basket",
    "assetMints": ["'"$SOL"'", "'"$JITO"'"],
    "initialWeights": { "base": 0, "So11111111111111111111111111111111111111112": 6000, "jtojtomepa8beP8AuQc6eXt5FriJwfFMwQx2v2f9mCL": 4000 }
  }'
# → { pendingId, agentPubkey, fundingLamports, fundingTx (base64), version, nextStep }

Step 2 — Sign the funding tx (client-side)

The fundingTx is a Solana versioned transaction (see version) that transfers 0.1 SOL from your wallet to the newly generated agent. Your wallet signs and submits it — this is the ONE step the API can't do for you.

typescript
import { Connection, Keypair, VersionedTransaction } from '@solana/web3.js';

declare const myWallet: Keypair;          // your creator wallet
declare const fundingTx: string;          // from Step 1
const conn = new Connection('https://api.mainnet-beta.solana.com', 'confirmed');
const tx = VersionedTransaction.deserialize(Buffer.from(fundingTx, 'base64'));
tx.sign([myWallet]);                       // any Keypair or wallet adapter signer
const fundingSig = await conn.sendRawTransaction(tx.serialize());
await conn.confirmTransaction(fundingSig, 'confirmed');

Step 3 — Finalize the market

Hand the API the confirmed funding signature plus a creatorAuth: a short-lived, single-use statement signed by the same creator wallet. It proves the caller who collects the bearer is the wallet that funded the agent. The API then signs create_market with the freshly-funded agent, lands your initial weights atomically, and returns your operating bearer token.

creatorAuth is <creatorPubkey>.<expiresAtMs>.<nonce>.<signatureBase58>, where the signature is an Ed25519 signMessage by the creator wallet over these lines joined by \n (no trailing newline):

avo-portfolio-api/market-finalize/v1
<creatorPubkey>
<pendingId>            ← from prepare
<agentPubkey>
<fundingSignature>
<expiresAtMs>          ← unix ms, at most 120 s ahead
<nonce>                ← 16–64 chars of [A-Za-z0-9_-], single-use

The script below builds it with tweetnacl; the SDK ships the same thing as buildCreatorAuth. Sign a fresh one for every finalize attempt.

bash
umask 077          # files created below are owner-only
set -o noclobber   # refuse to overwrite: an old response would keep its old permissions
OUT="finalize-$AGENT_PUBKEY.json"
curl -s $API/v1/markets/create/finalize \
  -H "x-avo-api-key: $AVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "agentPubkey": "'"$AGENT_PUBKEY"'",
    "fundingSignature": "'"$FUNDING_SIG"'",
    "creatorAuth": "'"$CREATOR_AUTH"'"
  }' > "$OUT"   # fails without calling the API if "$OUT" already exists: move it aside
# "$OUT" → { marketPda, marketIndex, agentPubkey, createMarketSignature, bearer, converged?, ... }
jq -r .marketPda "$OUT"
# converged: true means an earlier finalize created this market and kept its bearer;
# the empty bearer here is not a credential. Rotate with POST /v1/markets/bearer/rotate.
jq -r 'if .converged then "already created: rotate the bearer" else "move .bearer into your secret store" end' "$OUT"
Store the bearer immediately The API returns your bearer token exactly once. Save it somewhere durable (env var, secrets manager). A lost bearer can't be recovered; issue a new one with POST /v1/markets/bearer/rotate, signed by your creator wallet.
Finalize retries Finalize acts only on a finalized funding transfer. Until it has landed it answers 409 FUNDING_TX_NOT_FOUND, and while it is confirmed but not final (about 13 s) 409 FUNDING_TX_NOT_FINALIZED, both with a Retry-After header. Wait that long, sign a new creatorAuth (the nonce is single-use), and call finalize again. Retrying a finalize that already succeeded returns the same market with converged: true and an empty bearer.

Step 4 — Rebalance

Now you have marketPda + bearer. From here every operator action is a single authenticated POST.

bash
curl -s $API/v1/rebalance \
  -H "authorization: Bearer $BEARER" \
  -H "content-type: application/json" \
  -d '{
    "weights": [
      { "asset": "base", "weightBps": 2000 },
      { "asset": "So11111111111111111111111111111111111111112", "weightBps": 4000 },
      { "asset": "jtojtomepa8beP8AuQc6eXt5FriJwfFMwQx2v2f9mCL", "weightBps": 4000 }
    ],
    "slippageBps": 50
  }'

The API picks a router per leg (dflow, Jupiter or Titan), executes every leg in a single flow, and commits the new NAV. The endpoint returns per-leg outcomes so you can log or alarm on anything unusual.

Rebalance errors can arrive with HTTP 200 A rebalance can run for minutes, so the API commits 200 early and writes whitespace keepalives until it finishes. A failure after that point arrives as a 200 whose JSON body is { "__rebalanceError": { status, code, message, details } }. Always check for it. The SDK's rebalance() turns it into an AvoSdkError.

Step 5 — Read live state

Live valuation is an agent call on your own market. NAV history is public — no auth needed, perfect for a dashboard or a notification bot.

bash
# Live valuation of your market's vaults, priced via Jupiter (agent auth).
curl -s "$API/v1/value?slippageBps=50" \
  -H "authorization: Bearer $BEARER"

# Public NAV-per-share history. Params: limit (1–2000, default 500),
# order (asc|desc, default desc), from / to (ISO 8601, on recordedAt).
curl -s "$API/v1/markets/$MARKET_PDA/nav-history?limit=100&order=asc&from=2026-10-01T00:00:00Z"

Public callers get navPerShare, lastNavTs and recordedAt per point. A depositor's position (GET /v1/markets/{marketPda}/holdings/{ownerWallet}) is readable only by that wallet: the request must carry a Sig2 signature from ownerWallet, bound to that method and path, single-use, and valid for at most 120 seconds.

All together — the ~50 line version

Copy-paste starting point. Handles market creation, funding, and a first rebalance in one script.

typescript
import { Connection, Keypair, VersionedTransaction } from '@solana/web3.js';
import nacl from 'tweetnacl';
import bs58 from 'bs58';
import fs from 'node:fs';

const API = 'https://api.avo.so';
const myWallet = Keypair.fromSecretKey(new Uint8Array(JSON.parse(
  fs.readFileSync(process.env.WALLET_KEYPAIR!, 'utf8'),
)));
const conn = new Connection(process.env.RPC_URL!, 'confirmed');

const USDC = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
const SOL  = 'So11111111111111111111111111111111111111112';
const JITO = 'jtojtomepa8beP8AuQc6eXt5FriJwfFMwQx2v2f9mCL';

async function post(path: string, body: unknown, bearer?: string) {
  const res = await fetch(API + path, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      'x-avo-api-key': process.env.AVO_API_KEY!,
      ...(bearer ? { authorization: 'Bearer ' + bearer } : {}),
    },
    body: JSON.stringify(body),
  });
  if (!res.ok) {
    // Errors are { error: { code, message } } (or { code, message }), with Retry-After when retryable.
    const body = await res.json().catch(() => ({}));
    const code: string = body.error?.code ?? body.code ?? 'HTTP_' + res.status;
    throw Object.assign(new Error(path + ' → ' + res.status + ' ' + code), {
      status: res.status, code, retryAfterSecs: Number(res.headers.get('retry-after') ?? 0),
    });
  }
  const json = await res.json();
  // /v1/rebalance reports late failures inside a 200 body.
  if (json.__rebalanceError) throw new Error(path + ' → ' + JSON.stringify(json.__rebalanceError));
  return json;
}

// Creator-signed binding finalize requires (see Step 3).
function creatorAuth(pendingId: string, agentPubkey: string, fundingSignature: string) {
  const creator = myWallet.publicKey.toBase58();
  const expiresAtMs = Date.now() + 60_000;
  const nonce = Buffer.from(nacl.randomBytes(16)).toString('hex');
  const message = [
    'avo-portfolio-api/market-finalize/v1',
    creator, pendingId, agentPubkey, fundingSignature, expiresAtMs, nonce,
  ].join('\n');
  const sig = nacl.sign.detached(new TextEncoder().encode(message), myWallet.secretKey);
  return [creator, expiresAtMs, nonce, bs58.encode(sig)].join('.');
}

// 1. Prepare — API generates an agent keypair, returns an unsigned funding tx.
const prep = await post('/v1/markets/create/prepare', {
  creator: myWallet.publicKey.toBase58(),
  baseAssetMint: USDC, feeAssetMint: USDC,
  marketFeeBps: 50, label: 'My AI basket',
  assetMints: [SOL, JITO],
  initialWeights: { base: 0, [SOL]: 6000, [JITO]: 4000 },
});

// The one-time bearer goes in a new owner-only file, never into logs.
// Refuse up front if it already exists (an existing file keeps its old permissions).
const bearerFile = 'avo-bearer-' + prep.agentPubkey + '.txt';
if (fs.existsSync(bearerFile)) throw new Error(bearerFile + ' already exists; move it aside first');

// 2. Sign + submit the 0.1 SOL funding tx with your wallet.
const tx = VersionedTransaction.deserialize(Buffer.from(prep.fundingTx, 'base64'));
tx.sign([myWallet]);
const fundingSig = await conn.sendRawTransaction(tx.serialize());
await conn.confirmTransaction(fundingSig, 'confirmed');

// 3. Finalize — your wallet signs a fresh creatorAuth per attempt; the API
//    signs create_market with the funded agent. Until the funding tx is
//    finalized the API answers 409 FUNDING_TX_NOT_FOUND / FUNDING_TX_NOT_FINALIZED.
let created;
for (let attempt = 1; ; attempt++) {
  try {
    created = await post('/v1/markets/create/finalize', {
      agentPubkey: prep.agentPubkey,
      fundingSignature: fundingSig,
      creatorAuth: creatorAuth(prep.pendingId, prep.agentPubkey, fundingSig),
    });
    break;
  } catch (err) {
    const { code, retryAfterSecs } = err as { code?: string; retryAfterSecs?: number };
    if (attempt >= 6 || (code !== 'FUNDING_TX_NOT_FOUND' && code !== 'FUNDING_TX_NOT_FINALIZED')) throw err;
    await new Promise((r) => setTimeout(r, (retryAfterSecs || 5) * 1000));
  }
}
if (created.converged || !created.bearer) {
  // An earlier finalize already created this market and issued its bearer; it is
  // never re-issued. Don't overwrite what you stored. If you no longer have it,
  // rotate: POST /v1/markets/bearer/rotate { marketPda }, signed by your creator wallet.
  console.error('market ' + created.marketPda + ' already existed; bearer not re-issued (rotate it if lost)');
  process.exit(1);
}
// 'wx' creates the file or fails if it exists, so mode 0o600 always applies.
fs.writeFileSync(bearerFile, created.bearer, { mode: 0o600, flag: 'wx' });
console.log('market:', created.marketPda, '(bearer saved to ' + bearerFile + ')');

// 4. Rebalance to a new weight vector.
await post('/v1/rebalance', {
  weights: [
    { asset: 'base', weightBps: 2000 },
    { asset: SOL,  weightBps: 4000 },
    { asset: JITO, weightBps: 4000 },
  ],
  slippageBps: 50,
}, created.bearer);
console.log('rebalanced.');

Where to go next