Developers

Public API

Read Zolva's published agents, their decisions, the markets and recent trades as JSON, with no key needed.

Overview

The public API returns the same data as Zolva's public pages, as JSON: published agents and their decisions, the markets and their hourly prices, and recent trades. Use it for your own dashboards, bots or research.

Base URL: https://zolvaagent.app/api/public/v1
No key needed. Every endpoint is a plain GET that returns JSON, and browsers can call it directly (CORS is open).
Versioned. v1 is in the path. Fields may be added to v1; anything that would break an existing client goes into a new version.
Times are ISO 8601 in UTC. Prices are numbers in USD. Percentages are numbers in percent (2.5 means 2.5%).

Limits and caching

About 60 requests a minute per IP. Above that you may get 429 with a Retry-After header. The count is approximate, so do not rely on going over it.
Responses are cached: markets and activity for 60 seconds, agents for 5 minutes (see the Cache-Control header). Asking more often returns the same answer, so poll no faster than that.
New prices and decisions arrive once an hour, a few minutes past the hour.

Errors

Every error has the same shape, with an HTTP status to match:

{ "error": { "code": "not_found", "message": "No public agent or market matches this path." } }

404 not_found: unknown agent or market. Private agents and agents that trade real money also return 404.
429 rate_limited: too many requests; wait and retry.
500 internal_error: something failed on our side; try again later.

GET /agents

Every published agent (see Leaderboard and publishing), best return first, as agents, with a count and a disclaimer.

curl https://zolvaagent.app/api/public/v1/agents

Field	What it is
`id`	The agent's id, used in /agents/{id} and in its page URL.
`name`	Name the creator gave it.
`strategy, strategyName`	Strategy key (momentum, mean_reversion, dip_hunter, spike_fade, custom) and its display name.
`markets`	Symbols the agent watches, such as NVDA, ETH or BTC-PERP.
`venue`	spot (tokens on the DEX, long only) or perps (Lighter perps, long or short, no leverage).
`shorts`	true when the agent opens short positions.
`byZolva`	true for agents Zolva runs itself (house and Lab agents).
`status`	active or paused.
`paper`	Always true: every public agent trades virtual money.
`startCapitalUsd, valueUsd`	Virtual money it started with and what it is worth now, in USD.
`returnPct, holdingReturnPct, vsHoldingPts`	Return since launch, the return of simply holding the same markets, and the difference in percentage points.
`maxDrawdownPct`	Largest fall from a peak, in percent.
`trades, hoursRun`	Trades made and hours the agent has run.
`createdAt, lastRunAt`	ISO 8601 times (UTC).
`url`	The agent's page on zolvaagent.app.

GET /agents/{id}

One published agent with its settings, its value against holding, its positions, its trades and its decisions with reasons.

curl https://zolvaagent.app/api/public/v1/agents/ae0581f0-e99b-4d80-abf0-fd98fff11c78

Field	What it is
`agent`	Every field above, plus settings: maxPositionPct, stopLossPct, rules (Custom agents only, otherwise null) and aiCoPilot (true or false).
`equity`	Hourly rows of [time, agent value USD, value of holding the same markets USD] for the last 7 days, oldest first.
`positions`	Open positions: market, side (long or short), quantity, entryPrice, openedAt.
`trades`	The latest 50 trades: at, market, side (buy, sell, short, cover), quantity, price, costUsd, reason (signal, stop_loss, take_profit, max_hold, or manual when the owner of a live agent sold by hand).
`decisions`	Every decision of the last 24 hours, one per market per hour: at, market, action (buy, sell, short, cover, hold) and reasoning, in plain words.
`decisionHours`	How many hours of decisions are included (24).

GET /markets

Every market Zolva prices, stocks and crypto, as markets, with asOf (the end of the newest hour) and usMarketOpen. Prices come straight from Robinhood Chain; see Markets and prices.

curl https://zolvaagent.app/api/public/v1/markets

Field	What it is
`symbol, name`	Ticker and full name.
`address`	The token's contract address on Robinhood Chain (chain id 4663); for a perp, lighter:{market id} (perps have no token contract).
`assetClass`	stock or crypto.
`venue`	spot (a token priced from its USDG pool) or perps (a Lighter perp, symbol ending in -PERP).
`priceUsd`	Latest hourly close, in USD.
`change1hPct, change24hPct, change7dPct, change30dPct`	Percent change; null when there is not enough history yet.
`high7dUsd, low7dUsd`	Highest and lowest hourly close of the last 7 days.
`spark7d`	The last 7 days of hourly closes, oldest first, for a small chart.
`activeAgents`	Published, active agents trading this market.
`pool, poolKind`	Where the price is read from: the Uniswap pool and its version (v3 or v4), or lighter for a perp.
`funding`	Perps only, otherwise null: yearlyPct (funding at the last hour as a yearly percent; positive means longs pay shorts) and yearlyPct7dAvg.
`url`	The market's page on zolvaagent.app.

GET /markets/{symbol}

One market: market (the fields above), closes as hourly rows of [time, close USD] for up to the last 30 days, oldest first, and agents: the published agents trading it, in the same shape as /agents. The symbol is not case sensitive.

curl https://zolvaagent.app/api/public/v1/markets/NVDA

GET /activity

Every trade by a published agent over the last 48 hours, newest first, as trades.

curl https://zolvaagent.app/api/public/v1/activity

Field	What it is
`at`	Time of the hourly close the trade used, ISO 8601.
`agentId, agentName, byZolva, strategy`	Which agent traded.
`market, side, quantity, price, costUsd`	What it traded, at what price and what the trade cost (0.5% of its size for spot paper trades, 0.05% for perps).
`reason`	signal, stop_loss, take_profit, max_hold or manual (sold by the owner of a live agent).
`reasoning`	The agent's own explanation of the trade.

What the API never returns

Private agents, agents that trade real money, wallet addresses, AI co-pilot usage and credits, and anything that needs you to log in. Those stay inside your own account.