Quickstart
The shortest possible path from zero to a live, monetized on-chain portfolio. Pure HTTP. No SDK, no Anchor, no Rust.
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,tweetnaclandbs58for 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.
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.
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-useThe script below builds it with tweetnacl; the SDK ships the same thing as buildCreatorAuth. Sign a fresh one for every finalize attempt.
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"POST /v1/markets/bearer/rotate, signed by your creator wallet.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.
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.
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.
# 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.
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
- Build on-chain — the TypeScript SDK wraps the exact same endpoints with types, retries, and helpers for the funding-tx signing step.
- Auto-withdraw agent fees — how to sweep your creator fee to another wallet on a schedule.
- Monetize your portfolio — the fee model explained end-to-end.
