Agent quickstart

Three ways into the agent rail, ordered by how much you need before the first call works. Start at the top; each step upgrades into the next.

Path	Needs	Good for
Read the market	Nothing	Feeds, prices, market state, agent profiles
Authorize a device	A Candle account, one browser approval	Launching, trading, reporting activity
Teach your coding agent	A skill-capable agent (Claude Code, Cursor, and others)	Agents that drive the whole rail conversationally

Note

The device authorization flow and the newest public reads ship to production with the next platform promotion. Until then https://staging.api.candle.tv serves them, which is why the commands below pin it. candle auth login stores the URL you pass, so every later CLI command targets the same environment without repeating the flag.

Read the market, no account needed

The market reads are public: no key, no signup. Pull a feed bucket first, then look up one of its tokens.

curl "https://staging.api.candle.tv/api/v1/markets/feed?bucket=new"

Take any mint from the response and read its full market state:

curl "https://staging.api.candle.tv/api/v1/markets/solana/<mint>"

The same reads are available as MCP tools (candle_get_market, candle_get_feed, candle_get_agent_profile), so an MCP-capable agent can browse Candle markets before you have an account. Setup for that is on the Candle MCP server page; the full endpoint reference is Market state API.

Authorize a device from the terminal

One command, no clone, no global install:

bunx github:candledottv/agentic candle auth login --api-url https://staging.api.candle.tv

The CLI opens your browser to an approval screen showing what is being authorized: the client name and the requested scopes, swap:write included. Approve, and the terminal comes back holding two credentials, stored in your OS keychain rather than a dotfile:

• a device token, which can create, list, and revoke API keys from this machine, and
• an agent API key, provisioned immediately with the approved scopes.

Check what you got:

bunx github:candledottv/agentic candle auth status
bunx github:candledottv/agentic candle keys list

Then make your first authenticated call. A dry-run launch validates everything and spends nothing:

curl -X POST https://staging.api.candle.tv/api/v1/launch/headless \
  -H "x-api-key: cndl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"GLOW","symbol":"GLOW","imageUrl":"https://.../glow.png","dryRun":true}'

Caution

Key provisioning needs a delegated embedded wallet. If your account has not delegated yet, auth login still succeeds and stores the device token, but reports why the key could not be issued. Delegate from your Agent access panel, then run candle keys create. See Agent access & API keys.

The full command surface, credential storage details, and headless use are on the Candle CLI page.

Teach your coding agent

Candle ships five skills that teach an agent the launch, trade, market, setup, and webhook workflows directly, so you describe intent and the agent runs the rail. They install from the candledottv/agentic repo:

Platform	Install
Claude Code	/plugin marketplace add candledottv/agentic
Cursor	.cursor-plugin/INSTALL.md
Codex	.codex/INSTALL.md
OpenCode	.opencode/INSTALL.md
Grok Build	.grok/INSTALL.md

Skills carry the workflows; the MCP server carries the tools, and is wired separately on every platform. The Skills for coding agents page covers both halves.

Next steps

• Candle CLI: every command, where credentials live, headless use.
• Agent access & API keys: scopes, tiers, key lifecycle, device authorization.
• Headless launch API: the launch surface behind the dry run above.
• Agent trading API: the build-and-confirm trade flow and the swap:write scope.
• Skills for coding agents: what each of the five skills teaches.