Fee economics
The most a subscriber can pay in success fees is 30% of new profit (your 22% maximum plus EchoZero’s 8%).
How the success fee works
EchoZero tracks a high-water mark (HWM) for every subscriber on every agent they follow. The HWM is the subscriber’s best cumulative realized profit on that agent, net of venue costs, adjusted for their deposits and withdrawals.- A fee accrues only when realized profit moves above the HWM, and only on the amount above it.
- No fee is charged on losses or on principal, and none is charged while the subscriber is below their previous peak. Recovering a drawdown is free.
- Accrued fees are settled weekly from the subscriber’s balance. If a balance cannot cover the fee at settlement, the rest stays owed and is collected at a later settlement (catch-up).
- Fees also settle immediately when a subscriber withdraws, unsubscribes, or reduces their allocation to the agent.
Worked example: success fee
YourmarketplaceSuccessFeePercent is 15%. A subscriber’s realized profit on your agent reaches $2,000**, and their previous high-water mark was **$0.
- Fee base: $2,000 - $0 = $2,000 of new profit
- Your creator fee: $2,000 × 15% = **$300**
- EchoZero platform fee: $2,000 × 8% = **$160**
- The subscriber pays **$460** at the next weekly settlement. Their HWM is now $2,000.
Accrued but unsettled fees are visible in your earnings totals but are not claimable until they have been collected at settlement.
Worked example: subscription
You setmarketplaceMonthlyPrice: 29. Ten subscribers pay for one month.
- Gross: $290
- Platform fee (20%): $58
- Your share: $232, claimable as USDC
Monetization models
Set these on agent create or update (POST /api/v1/agents, PATCH /api/v1/agents/{id}):
marketplaceSuccessFeePercent defaults to 20 when you do not send it. You can also set the percentage with feeConfiguration.feePercentage.
The request fields are prefixed with
marketplace. When you read an agent back, or browse public agents, the same values are returned as pricingModel, monthlyPrice and successFeePercent. Sending the read names on create or update does not set the price.Getting paid
Every payout lands as USDC in your EchoZero wallet. You claim it; nothing moves automatically.
Each weekly settlement also records a payout snapshot (gross, platform fee, net) that you can read from payout history.
Key endpoints
Earnings summary
totals,byAgent: success-fee totals, including fees accrued but not yet settledbyPeriod: weekly payout snapshotsfromTrading.claimableUsd: success fees collected and ready to claimfromSubscriptions.claimableUsd: subscription earnings ready to claimtotalClaimableUsd: both combinedlifetimeClaimedUsd,fromInstantClaims: what you have already claimed
totalClaimable field is a deprecated alias of totalClaimableUsd.
Payout history
data.items plus data.pagination. See API conventions.
Claim success fees
GET /api/v1/developers/earnings for what is still claimable.
Returns 404 if the agent is not found or not owned by the caller.
Claim subscription earnings
GET /earnings first to check fromSubscriptions.claimableUsd.
Typical workflow
1
Register as a developer
Complete developer registration in the Dev Portal or via
POST /api/developers/register. That route has no /v1 and needs an authenticated user or API key.2
Price your agent
Set
marketplacePricingModel, and marketplaceSuccessFeePercent (0-22) and/or marketplaceMonthlyPrice, when you create or update the agent.3
Request a listing
Send
isPublic: true to ask for a marketplace listing. Staff review it. See Agent lifecycle.4
Monitor earnings
Poll
GET /v1/developers/earnings for claimable balances and GET /v1/developers/payouts for weekly settlement history.5
Claim balances
- Success fees:
POST /claims/agents/{agentId}orPOST /claims/all - Subscriptions:
POST /claim-subscription-earnings
Dashboard analytics
Additional developer dashboard routes (subscribers, performance, signal history) are under the Developer dashboard tag in the API Reference. These complement earnings data for operational monitoring.Related guides
- Sandbox testing - test signal flows without affecting live subscribers
- Signal envelope - how signals become executable trades
- Error codes - handling 400/404 claim errors and rate limits