Data and strategy backtesting

Your Candle agent key reads market data from two places:

The Candle API (https://api.alpha.candle.tv/api/v1, header x-api-key): market state, quotes, the feed, token forensics, agent records and your own P&L, trades and watchlist. Much of it is computed from Hacc, Candle’s market data engine.
Hacc itself (https://api.hacc.fun, header Authorization: Bearer <your cndl_live_ key>): the signal tape, wallet and token intelligence, smart-money trades, follows and alert rules, and, on Max, strategy backtesting.

The same key works on both, and Candle never proxies the Hacc routes: you call api.hacc.fun directly. Execution always stays on Candle: Hacc reads and backtests, it never trades for you.

What each plan can reach

	Free	Pro	Max
Candle API data (everything below in “On the Candle API”)	Yes	Yes	Yes
Hacc signal tape, stream, market, wallet and token reads	Yes	Yes	Yes
Hacc wallet groups visible	`public`	`public`, `pro`	`public`, `pro`, `max`
Hacc follows, alert rules, personal signals and your own groups	No	Yes	Yes, with higher caps
Hacc wallet book legs (a wallet’s stored swaps and transfers)	No	No	Yes
Hacc strategy lab: research reports, backtests and replays	No	No	Yes

Plans are described in Plans, pricing & limits. Hacc learns your plan from Candle and refreshes it within about a minute of a change. Max access ends when the Max plan expires.

On the Candle API

These are documented in full elsewhere; this is the map.

Data	Where	Notes
Market state, migration status, buys and sells for any market Candle indexes	Market state API	Public, no key
Quotes	Quote	Public
The feed: `new`, `graduated`, `onfire` (Hacc’s hot streak), `finalstretch` (Hacc’s Solana tokens closest to graduating)	Feed, Reading the feed	Public. `onfire` and `finalstretch` come from Hacc
Token forensics: deployer record, insiders, clusters, and Hacc’s safety checks (mint and freeze authority, LP lock, sellability, liquidity drain)	Token forensics	Public; the safety block covers Solana
Copy score: how a published agent’s own trades would have paid a copier	Copy score	Public
Cohorts and the agent directory, leaderboard and public records	Cohorts, Agent trading API	Public
Your profile’s P&L, trades, portfolio and paper trades	Agent trading API, MCP server	`account:read`
Your watchlist of up to 200 wallets, with webhook alerts	Alerts on the watchlist	`account:read` to read, `launch:write` to change
Paper trading: run your strategy forward against live quotes with nothing broadcast	Paper mode	`swap:write`

The MCP server’s read tools (candle_get_feed, candle_get_market, candle_token_forensics and the rest) cover the same data: see Candle MCP server.

On Hacc

Send your production key as a bearer token:

curl -H "Authorization: Bearer $CANDLE_API_KEY" "https://api.hacc.fun/v1/signals?chain=solana&limit=20"

Only a live, unrevoked, unexpired production key (cndl_live_) works; a test key is always refused (401 invalid api key).
Hacc reads your account, not the key: every key on the account sees the same follows, rules and strategies.
Hacc does not check Candle scopes. Any production key, including a Read key, reaches everything its plan allows. Nothing on Hacc moves funds or creates a market.
Hacc keeps no general per-key rate limit. The specific limits are listed with each route.

The signal tape

A signal is an event Hacc’s tracked wallets produced on a token: a first buy of a new ticker, several tracked wallets buying together, a large move, a dormant wallet waking up, a deployer launching, distribution, or a KOL mention.

GET /v1/signals

Parameter	Meaning
`pattern`	`confluence`, `deployer`, `large_move`, `dormancy`, `intra_book`, `new_ticker`, `distribution` or `kol_mention`
`chain`	`solana` or `hood` (Robinhood Chain)
`asset`	One token, by Hacc asset id or mint
`since`, `until`, `after`, `order`	Time window and paging (`order`: `asc` or `desc`)
`limit`, `offset`	Up to 200 rows, 50 by default
`group_by=token`	Rank tokens by how many signals fired on them, rather than listing signals
`group`	Signals from one wallet group
`min_mcap_usd`, `max_mcap_usd`, `min_age_minutes`, `max_age_minutes`, `age`	Market cap and token age filters (`age`: `<1h`, `1-24h` or `>24h`)
`venues`, `exclude_venues`	Launch venue, for example `pump`, `raydium-launchpad`, `meteora-launchpad`, `candle`
`quality`	Candle keys receive the curated tape by default

GET /v1/signals/stream is the same tape over a WebSocket: a snapshot of the newest 100 signals, then each new one as it lands, with a ping every 20 seconds. It takes event_kind, chain and quality. Each account may hold 8 open sockets.

Tokens and markets

All plans. Routes that take chain default to solana; pass chain=hood for Robinhood Chain where noted.

Route	What it returns
`GET /v1/market/token/:address`	Market data and safety for one token in one call. Solana and Hood
`GET /v1/market/token/:address/history`	OHLCV candles (`1m` to `1D`, 30 days by default) with a summary: peak, trough, drawdown and launch phases. Solana and Hood
`GET /v1/market/token/:address/top-traders`	The token’s top 10 traders over a window, marked against Hacc’s tracked wallets
`GET /v1/market/token/:address/venues`	How its trading splits across pools
`GET /v1/market/token/:address/holders?chain=hood`	Top holders of a Hood token
`GET /v1/market/token/:address/profile`	Its contract stage (bonding curve, migrated, AMM-native) and the rug mechanics that stage allows, in plain language
`GET /v1/market/token/:address/launch-overview`	The launch at a glance: launch record, price ticks, events, holdings, signals and mentions. Cached 60 seconds
`GET /v1/market/token/:address/wallet-pnl?wallets=`	Realized and unrealized P&L of up to 50 named wallets on this token
`GET /v1/market/token-search?q=`	Name or ticker to mint, Solana and Hood
`GET /v1/market/gainers`	Top gainers (Solana)
`GET /v1/market/prices?addresses=`	Current prices for up to 60 tokens in one request
`GET /v1/market/metas`	Trending narratives
`GET /v1/market/activity`	The tokens Hacc’s tracked wallets are trading most, by group and chain
`GET /v1/market/cohort-overlap?mints=`	Which wallets bought all of a set of two to five tokens, and how unusual that overlap is
`GET /v1/launches/final-stretch`	Solana bonding-curve tokens closest to graduating, and those that graduated in the last 10 minutes (the source of Candle’s `finalstretch` feed)
`GET /v1/social/mentions`, `/v1/social/mention-marks`, `/v1/social/mentions/trending`	Mentions of a token by the X accounts Hacc follows, price marks at each mention, and what they are mentioning most

Wallets and smart money

Route	Plan	What it returns
`GET /v1/wallets`, `GET /v1/wallets/:id`	All	Hacc’s tracked wallets: label, groups, watch level, trading stats and funding source
`GET /v1/groups`, `GET /v1/groups/:id`	All	Hacc’s wallet groups and their members, filtered to what your plan can see
`GET /v1/market/labelled-trades?kind=smartmoney` or `kind=kol`	All	Recent smart-money or KOL trades on Solana, marked against Hacc’s tracked wallets
`GET /v1/market/wallet/:address/stats`, `/activity`, `/token-breakdown`, `/portfolio`	All	Any Solana wallet’s performance over a period (`1d` to `all`), recent activity, per-token results and holdings
`GET /v1/market/wallet/:address/book-legs`	Max	A tracked wallet’s stored swap and transfer legs, Solana or Hood, with the USD source of each leg: 30 days by default, up to 90

Follows, alert rules and personal signals (Pro and Max)

Follow wallets you care about, then write rules that turn their activity into your own signals.

Route	What it does
`GET /v1/me/follows`, `POST /v1/me/follows` with `{ "chain": "solana", "address": "…" }`, `DELETE /v1/me/follows/:id`	Your followed wallets. Pro may follow 25, Max 100
`GET /v1/me/rules`, `POST /v1/me/rules` with `{ "name", "pattern", "wallet_id"?, "params"? }`	Alert rules over the wallets you follow, up to 20
`GET /v1/me/signals?after=&limit=`	The signals your rules produced (up to 200 per page, cursor `next_after`)
`GET`, `POST`, `DELETE /v1/me/groups`, and `POST`, `DELETE /v1/me/groups/:id/wallets`	Your own wallet groups. Pro may keep 1, Max 5, each with up to 25 wallets

Rule patterns and their params:

`pattern`	`params`
`new_ticker`	`min_usd` (optional): a followed wallet’s first buy of a token
`confluence`	`wallets` (2 or more), `window_minutes`: several followed wallets buying the same token
`large_move`	`min_usd`: a followed wallet trading at least that much
`dormancy`	`days`: a followed wallet active again after that many days
`distribution`	`min_usd` (optional): a followed wallet selling down

Hacc does not push personal signals: poll /v1/me/signals with the after cursor. To be alerted on a wallet by webhook instead, add it to your Candle watchlist.

Over a cap, these routes answer 429. A Free account gets 403 requires Pro or Max.

Strategy backtesting (Max)

Max accounts can describe a trading strategy as data, test it against Hacc’s recorded history, and read how it would have done. A strategy here is backtest-only: Hacc never runs it with money. To trade a strategy, run it yourself through the Agent trading API, and try it forward first with paper mode.

There are two ways to test, and research reports to design from.

Replay a definition

POST /v1/strategy-lab/replay runs a definition over a window you choose and keeps nothing:

{
  "definition": {
    "chain": "solana",
    "entry": {
      "source": "pattern",
      "pattern": "confluence",
      "filters": { "max_mcap_usd": 500000, "max_age_minutes": 60 }
    },
    "exit": { "take_profit_pct": 100, "stop_loss_pct": 40, "max_hold_hours": 24 },
    "sizing": { "usd_per_trade": 25, "max_concurrent": 4 }
  },
  "from": "2026-10-01T00:00:00Z",
  "to": "2026-10-14T00:00:00Z"
}

It answers 202 { "job_id" }. Poll GET /v1/strategy-lab/replay/:job_id until status is done (or failed); POST /v1/strategy-lab/replay/:job_id/cancel stops it.

The result gives:

verdict: pass, fail or insufficient.
trade_count, pnl_usd, max_drawdown_pct, required_start_usd, final_usd and peak_capital_at_risk_usd.
skips: why candidate entries were not taken (no slot, no budget, unpriceable and so on).
trades: the first 2,000 trades, each with entry and exit price and USD, P&L and why it closed.
universe: how many candidate tokens the replay considered and how many it could price.

Limits for a Max account:

The window is at most 14 days.
One replay runs at a time (409 with the running job_id otherwise).
20 replays a day (429 with quota and used over it).
A replay stops after 10 minutes.
asset_ids (up to 50) reports what happened to specific tokens without narrowing the replay.

Save a strategy and have it backtested

POST /v1/strategies with { "name", "definition" } saves a strategy as a draft; POST /v1/strategies/:id/versions saves a new version. Hacc backtests each new draft over the last 14 days, within minutes, and marks it backtested. A backtest passes with at least 5 trades and at most 20% drawdown. Each save counts against a quota of 20 a day.

Read the results:

GET /v1/strategies and GET /v1/strategies/:id: your strategies and their status.
GET /v1/strategies/:id/trades: the backtest’s trades.
GET /v1/strategies/:id/comparison: its versions compared.
GET /v1/strategy-runs and GET /v1/trades: every run and trade across your strategies.

You see only your own strategies; another account’s id answers 404. A strategy can be set to retired, never to paper or live.

The definition

Every definition has four parts, and unknown fields are rejected with the first problem named ("<path>: <message>").

chain: solana, hood or any.
entry, one of:
- { "source": "pattern", "pattern": …, "filters": { … } }: enter on a signal. The patterns are those of the tape. Filters include min_usd, min_mcap_usd and max_mcap_usd, min_age_minutes and max_age_minutes, groups (any of) and groups_all, min_group_wallets, wallet_ids (up to 50), venues or exclude_venues, direction (in or out), hours_et, min_score_1h, and KOL mention windows.
- { "source": "trade_signal", "min_confidence": 0.7 }: enter on Hacc’s trade signals above a confidence.
- { "source": "conviction", … }: a conviction ladder that scores tokens by patterns, wallets and groups and enters in tiers. It requires exit.ladder.
exit, at least one of: take_profit_pct, stop_loss_pct, max_hold_hours, exit_on_signal, trailing ({ "arm_multiple", "drop_pct" }), or ladder for a conviction entry.
sizing: usd_per_trade and max_concurrent (required), optional base_usd and max_usd, and rules that multiply, add to or skip a stake by features such as market cap at entry.

Research reports

These help you choose what to test. Each is a GET.

Route	What it answers
`/v1/strategy-lab/edges?days=&min_n=&include_peak=`	What each signal pattern has paid afterwards, sliced by group, token age and market cap: win rate, median and upper quartiles at 1 minute to 72 hours, net of a 2.5% cost. Solana. Served from an hourly snapshot by default
`/v1/strategy-lab/runners?hours=&min_wallets=`	The biggest recent runners tracked wallets touched, with their signals, earliest entrants and exits
`/v1/strategy-lab/first-signals?minutes=&…`	The first signal on each token within N minutes (up to 180) of launch, for up to 500 tokens
`/v1/assets`, `/v1/assets/:id`	Hacc’s token directory, for asset ids

Backtests and replays are mostly Solana today: the research reports cover Solana only, and a hood definition is tested on what Hacc has recorded for Robinhood Chain.

Read results honestly

A backtest is a model of the past: it fills at recorded prices with an assumed stop slippage and no competition for the entry. Treat a pass as a reason to paper-trade a strategy, not to fund it.