AVO Logo
Guides

Auto-withdraw agent fees

Every market accrues market_fee_bps earnings in a dedicated fee ATA owned by the market's agent. This guide wires those fees into your treasury on a schedule — no manual claims, no custody of the agent's Solana keys.

Zero on-chain program changes The endpoint the API exposes just has the agent sign a standard SPL token transfer from its own fee ATA to a destination you choose. No program upgrade required.

How the math works

On every deposit and every withdraw, a fee of total_fee_bps = platform_fee_bps + market_fee_bps is skimmed into two ATAs owned by the fee-asset mint:

  • agent_fee_dest — your share (market_fee_bps proportion). Owned by market.agent.
  • platform_fee_dest — Avo's share. Owned by global_state.fee_vault.

This endpoint pulls the balance out of agent_fee_dest. The platform's share isn't touched.

The endpoint

POST /v1/agent/fees/withdraw. Agent auth (your market's bearer or an agent Sig), same as /v1/rebalance. Body:

ts
interface WithdrawAgentFeesBody {
  /** Solana pubkey that receives the fees. */
  destinationWallet: string;
  /** Atomic units. Skip transfer if balance <= this. Default 0. */
  minFeeAmount?: string | bigint;
}

interface WithdrawAgentFeesResp {
  /** Null when the endpoint no-oped (balance <= minFeeAmount). */
  signature: string | null;
  amountWithdrawn: string;
  remainingBalance: string;
  feeAssetMint:  string;
  destinationAta: string;
}

Idempotent by design: schedule it on any cadence you like. If the ATA balance is below minFeeAmount at cron time, the call no-ops and returns signature: null. No tx fees are burned on dust runs.

1. Call it from the SDK

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.withdrawAgentFees({
  destinationWallet: process.env.DESTINATION_WALLET!,
  minFeeAmount: '1000000',  // 1 USDC — skip dust
});

if (result.signature) {
  console.log('Transferred', result.amountWithdrawn, 'to', result.destinationAta);
} else {
  console.log('No fees to withdraw yet — balance below threshold.');
}

2. Run it on a schedule

Put the snippet above in any scheduler you already run (cron, a GitHub Actions schedule, Windmill, a serverless cron) with two secrets:

  • AGENT_BEARER: the bearer for this market
  • DESTINATION_WALLET: where fees land

Weekly is typical; daily is fine too. The min-fee-amount guard means daily runs on a quiet market cost nothing.

Custodial vs self-custodial Bearer auth (custodial) is recommended: the operator never touches a Solana key. If you self-custody the agent, construct the client with agent: { publicKey, secretKey } (or { publicKey, signer }) instead and the SDK signs a short-lived Sig token per call.

Failure modes worth knowing

  • Destination wallet has no ATA for the fee mint. The endpoint auto-creates it idempotently. Rent (~0.002 SOL) is paid by the agent on first call for each new destination.
  • Balance dips below rent-exempt. The agent needs ~0.001 SOL to keep the ATA alive across transfers. If your fee ATA has been drained to precisely zero for a long time, top it back up during your next rebalance so the transfer tx can construct properly.
  • Agent SOL underfunded. Same failure mode as rebalance / withdraw. Keep the agent above 0.02 SOL as a rule.

Related