AVO Logo
Guides

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.

What you'll need A Solana wallet with ≥ 0.15 SOL on the target cluster (0.1 funds the agent + ~0.05 for tx fees). No agent keypair required — the API custodies it for you.

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.

Avo app: Create Portfolio, step 1 (basics and market settings)

1. Install the SDK

bash
npm install @avodotso/market-sdk

2. 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.

ts
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,
  },
};
Weights sum to 10_000 basis points Every value in 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.

ts
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.

ts
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);
The bearer is shown once Copy 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:

ts
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);
Precision — bps vs percent Prefer 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