Create your first market
This walkthrough gets you from zero to a live on-chain market in about five minutes. You'll design an index (list of assets + target weights), pay 0.1 SOL to fund a custodial agent, and receive a bearer token you can wire into your rebalance scripts.
Prefer a UI? The app's Create portfolio screen at app.avo.so/create-portfolio runs this same prepare → fund → finalize flow, with your connected wallet signing both the funding transfer and the creatorAuth.

1. Install the SDK
npm install @avodotso/market-sdk2. Design the index
A market holds one base asset (typically USDC) plus up to 24 trade assets with target weights that sum to 100%. Base picks up any residual.
import { MarketClient } from '@avodotso/market-sdk';
const AVO_API_URL = 'https://api.avo.so';
// Market creation requires an Avo API key (avo_pk_…).
const client = new MarketClient({
services: { avoApi: AVO_API_URL },
gatewayAuthorization: `Bearer ${process.env.AVO_API_KEY}`,
});
// USDC on mainnet-beta
const USDC = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
// Example: 60% SOL, 40% JitoSOL, base fills the rest
const design = {
creator: '<YOUR_WALLET_PUBKEY>',
baseAssetMint: USDC,
feeAssetMint: USDC, // fees denominated in USDC
marketFeeBps: 50, // 0.5%
label: 'My First Index',
assetMints: [
'So11111111111111111111111111111111111111112', // wSOL
'J1toso1uCk3RLmjorhTtrVwY9HJ7X8V9yYac6Y7kGCPn', // JitoSOL
],
initialWeights: {
'So11111111111111111111111111111111111111112': 6000, // 60.00%
'J1toso1uCk3RLmjorhTtrVwY9HJ7X8V9yYac6Y7kGCPn': 4000, // 40.00%
base: 0,
},
};initialWeights is bps (10_000 = 100%). Sum must equal exactly 10_000. Include a base key even when zero — it's a hint to the finalizer that you've accounted for residual.3. Prepare — get the funding tx
prepareCreateMarket generates a fresh agent keypair server-side and returns an unsigned 0.1 SOL transfer from your wallet to that agent. Sign it in your wallet and submit it.
const prep = await client.prepareCreateMarket(design);
// prep.fundingTx is a base64 unsigned VersionedTransaction.
// Deserialize, sign with your wallet, and submit — same pattern as any
// other Solana tx from your app. The returned signature is what you'll
// pass to finalize.
const fundingSignature = await signAndSubmit(prep.fundingTx);4. Finalize — the agent creates the market
Finalize needs a creatorAuth: your creator wallet signs a short-lived, single-use message binding the pending market, its agent and your funding transaction, so only you can collect the bearer. buildCreatorAuth builds it from any wallet signMessage. It's valid for at most 110 seconds, so sign a fresh one if you retry. Finalize acts only on a finalized funding transfer and answers 409 FUNDING_TX_NOT_FOUND / FUNDING_TX_NOT_FINALIZED with Retry-After until then; the retry loop handles both.
finalizeCreateMarket then verifies the agent received the funding, submits create_market on chain, calls add_market_asset per requested mint, and (when initialWeights was supplied) commits those weights with a weight-rewrite rebalance. Returns your bearer token.
import { buildCreatorAuth } from '@avodotso/market-sdk';
const { creatorAuth } = await buildCreatorAuth({
creator: design.creator,
pendingId: prep.pendingId,
agentPubkey: prep.agentPubkey,
fundingSignature,
signMessage: (message) => myWallet.signMessage(message),
});
const fin = await client.finalizeCreateMarket({
agentPubkey: prep.agentPubkey,
fundingSignature,
creatorAuth,
});
// The bearer is shown once and is a live credential: write it straight to
// your secret manager (Vault, AWS Secrets Manager, Doppler, …). Never log it.
declare const secrets: { set(name: string, value: string): Promise<void> };
if (fin.converged || !fin.bearer) {
// An earlier finalize already created this market and issued its bearer;
// it is never re-issued. Keep the one you stored. If you no longer have it,
// mint a new one: POST /v1/markets/bearer/rotate { marketPda } as the creator.
throw new Error(`market ${fin.marketPda} already existed; not saving an empty bearer`);
}
await secrets.set(`avo/markets/${fin.marketPda}/bearer`, fin.bearer);
console.log('marketPda: ', fin.marketPda);
console.log('marketIndex:', fin.marketIndex);fin.bearer to your secret store immediately (Windmill variable, .env, whatever you use). There is no way to recover the original; issue a new one with POST /v1/markets/bearer/rotate, signed by your creator wallet.5. Your first rebalance
With the bearer in hand, subsequent rebalances are one call:
import { MarketClient } from '@avodotso/market-sdk';
const client = new MarketClient({
services: { avoApi: 'https://api.avo.so' },
agent: { bearer: process.env.AGENT_BEARER! },
});
const result = await client.rebalance({
weights: [
{ asset: 'base', weightBps: 0 },
{ asset: 'So11111111111111111111111111111111111111112', weightBps: 5000 },
{ asset: 'J1toso1uCk3RLmjorhTtrVwY9HJ7X8V9yYac6Y7kGCPn', weightBps: 5000 },
],
slippageBps: 50,
deadlineSecs: 180,
// Enable for intermittent-trading markets (RWAs, xStocks).
// capNavDelta: true,
});
console.log('prepare:', result.prepareSignature);
console.log('settle: ', result.settleSignature);weightBps (integer 0..10_000) over the older weight field (0..100). Percent inputs go through a per-entry Math.round(weight × 100) conversion that introduces drift for fractional percents; native bps preserves 1-bps precision and the sum-to-10_000 invariant exactly.Where to go from here
- Auto-withdraw agent fees — schedule a weekly cron so your
market_fee_bpsearnings land in your treasury without manual claims. - Build on-chain — full API reference for market operations.
