Build your first agent

From nothing to a verified on-chain action in about five minutes. This is the happy path; every step links to the full reference when you need options.

2. Delegate the chains your agent should use

On your dashboard, authorize Candle’s signer for Solana, Hood, or both. You will see exactly what is being authorized before any prompt fires: the wallets, the scopes, the spend caps in force, and how to revoke. Delegation is revocable at any time; revoking makes the next launch or trade fail closed with DELEGATION_REVOKED, though your keys stay valid and resume if you re-approve.

Details: Wallets, delegation & custody.

3. Create a test key

Create a key with environment: "test" first (cndl_test_...). The key is shown once; store it. Keys carry scopes and per-key limits, and the dashboard always shows the limits a key actually gets right now, not just what it was issued with.

Working from a terminal instead of the dashboard? Install the Candle CLI, then one command authorizes the machine and provisions the key in the same breath, stored in your OS keychain:

Install the Candle CLI (macOS 13 or later, or Linux):

    curl -fsSL https://candle.tv/install.sh | bash

or with Homebrew:

    brew install candledottv/tap/candle

Then: candle setup

With no npm and no install.sh: bunx github:candledottv/agentic candle auth login.

To mint another key from the terminal, pick its access level: candle keys create --access read|write|withdraw. Only Withdraw can move funds out of the TEE wallet it runs. For CLI trading, give the agent its own TEE wallet by promoting a key from your vault: Custody tiers: the vault and TEE wallets.

Reference: Agent access & API keys, Candle CLI.

4. Dry-run a launch

curl -X POST https://api.alpha.candle.tv/api/v1/launch/headless/dry-run \
  -H "x-api-key: cndl_test_..." \
  -H "Content-Type: application/json" \
  -d '{"clientLaunchId":"first-dry-run-1","name":"GLOW","symbol":"GLOW","imageUrl":"https://.../glow.png","visibility":"test"}'

A test key (cndl_test_) may only launch with visibility test or hidden, and a dry run checks that too.

Or with the SDK:

import { CandleClient } from "@candledottv/agent-sdk"
const candle = new CandleClient({ apiUrl: "https://api.alpha.candle.tv", apiKey: process.env.CANDLE_API_KEY })
await candle.dryRunLaunch({ clientLaunchId: "first-dry-run-1", name: "GLOW", symbol: "GLOW", imageUrl, visibility: "test" })

Reference: Headless launch API.

5. Make it real

Switch to a production key and call /launch/headless (or launch()) instead of the dry-run route. A launch returns its result when it lands; send async: true (or call launchAsync()) to get a job to poll instead. Trades follow a build-and-confirm flow. See Agent trading API for the trade leg.

6. Confirm the result

Poll the job of an async launch, or subscribe once and let Candle tell you: Webhooks deliver signed events for the things your agent cares about. Every accepted action lands in your account’s activity, attributed to your key and verified on-chain before it counts.

Prefer MCP, or a skill-taught agent?

If your agent runs inside Claude Code, Cursor, or any MCP client, skip the HTTP layer entirely: the Candle MCP server exposes the rail as tools (run it with candle mcp, or from npm as @candledottv/mcp), and twenty-two installable skills teach the agent the workflows themselves. In Claude Code that is one line:

/plugin marketplace add candledottv/agentic

Reference: Skills for coding agents.

If your agent is a chat app with no terminal that supports remote MCP, connect Candle’s hosted server, https://mcp.candle.tv/mcp, using the linked setup instructions for your host. ChatGPT MCP apps are web-only; host account, plan and organization permissions still apply. The public tools read markets, feeds and launch forensics without a Candle account. To use your own account, add https://mcp.candle.tv/mcp/account instead: your app opens a Candle page where you choose Read or Trade and approve, with no key to paste. Trade lets the agent buy, sell, swap and launch from your embedded wallet and never transfer funds out of it; see the safety model. A platform that can send x-api-key can use an agent API key on the first address. Local stdio or CLI access requires a separate terminal-capable agent.