{ "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Helius CLI Agent Instructions", "description": "Machine-readable instructions for AI agents to obtain a Helius API key via CLI", "version": "1.0.0", "overview": { "product": "Helius", "description": "Helius is Solana's leading infrastructure provider and developer platform. From high-performance RPC nodes and transaction sending (Sender) to gRPC streaming (LaserStream), webhooks, and digital asset APIs — Helius powers teams like Phantom, Jupiter, DFlow, Coinbase, and Bitwise.", "cli_tool": "helius-cli", "documentation": "https://www.helius.dev/docs/agents/cli", "transaction_tracker": "https://orbmarkets.io/tx/{transaction_signature}" }, "requirements": { "cost": { "amount": 1, "currency": "USDC", "network": "solana-mainnet" }, "transaction_fee": { "amount": 0.001, "currency": "SOL", "note": "approximate, for transaction fees" }, "runtime": { "node": ">=18.0.0" } }, "network_support": { "signup": { "network": "solana-mainnet", "cost": { "amount": 1, "currency": "USDC" }, "note": "Signup is mainnet-only. There is no devnet signup flow — the 1 USDC payment must be made on Solana mainnet." }, "api_key_usage": { "networks": ["mainnet-beta", "devnet"], "note": "The API key returned by `helius signup --json` works on both mainnet and devnet. The response's `endpoints` field contains pre-formatted URLs for both networks." }, "devnet_testing": { "note": "Signup requires mainnet USDC and is not available on devnet. For testing against the devnet RPC endpoint (endpoints.devnet from the signup response), agents can obtain devnet SOL through the options below. Devnet testing does not require additional Helius payment.", "helius_dashboard_faucet": { "url": "https://dashboard.helius.dev/faucet", "documentation": "https://www.helius.dev/blog/solana-faucet", "asset": "SOL", "amount_per_request": 1, "rate_limit_hours": 24, "authentication": "Paid Helius plan + dashboard login required", "access": "human_only", "note": "GUI only; not exposed as a programmatic API. Useful for human operators, not autonomous agents." }, "rpc_airdrop": { "method": "requestAirdrop", "endpoint_hint": "Use the `endpoints.devnet` URL returned by `helius signup --json`", "access": "agent", "note": "Standard Solana RPC method. Programmatic; no auth beyond the API key; rate-limited by the Solana devnet cluster." }, "third_party_faucets": [ { "name": "Solana Foundation", "url": "https://faucet.solana.com", "asset": "SOL" }, { "name": "SolFaucet (community)", "url": "https://solfaucet.com", "asset": "SOL" } ] } }, "installation": { "command": "npm install -g helius-cli", "verify": "helius --version", "expected_output_pattern": "^\\d+\\.\\d+\\.\\d+$" }, "solana_addresses": { "usdc_mint_mainnet": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "usdc_mint_devnet": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU", "helius_treasury": "CEs84tEowsXpH8u4VBf8rJSVgSRypFMfXw9CpGRtQgb6" }, "file_paths": { "default_keypair": "~/.helius-cli/keypair.json", "config": "~/.helius-cli/config.json", "keypair_format": "solana-cli-64-byte-json-array" }, "workflow": { "steps": [ { "step": 1, "name": "install_cli", "command": "npm install -g helius-cli", "check_command": "helius --version", "required": true }, { "step": 2, "name": "generate_keypair", "command": "helius keygen", "command_with_path": "helius keygen -o {custom_path}", "output_file": "~/.helius-cli/keypair.json", "output_contains": "Address:", "required": true, "skip_if": "keypair file already exists" }, { "step": 3, "name": "login", "command": "helius login --json", "command_with_keypair": "helius login -k {keypair_path} --json", "description": "Authenticate with existing wallet", "required": true, "note": "Required before signup to authenticate your wallet with Helius" }, { "step": 4, "name": "fund_wallet", "description": "Send SOL and USDC to the wallet address from step 2", "required_balances": { "sol": { "minimum": 0.001, "decimals": 9 }, "usdc": { "minimum": 1, "decimals": 6, "token_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" } }, "transaction_tracking": "https://orbmarkets.io/tx/{transaction_signature}", "required": true, "skip_if": "wallet already has sufficient balance" }, { "step": 5, "name": "signup", "command": "helius signup --json", "command_with_keypair": "helius signup -k {keypair_path} --json", "success_exit_code": 0, "output_format": "json", "extracts": ["apiKey", "endpoints.mainnet", "endpoints.devnet", "projectId"], "transaction_tracking": "https://orbmarkets.io/tx/{response.transaction}", "required": true } ] }, "commands": { "keygen": { "command": "helius keygen", "description": "Generate a new Solana keypair", "options": { "-o, --output ": "Output path for keypair (default: ~/.helius-cli/keypair.json)", "-f, --force": "Overwrite existing keypair" }, "requires_auth": false, "json_output": false }, "signup": { "command": "helius signup --json", "description": "Pay 1 USDC, create account, and get API key", "options": { "-k, --keypair ": "Path to Solana keypair file", "--json": "Output in JSON format" }, "requires_auth": false, "json_output": true, "success_response": { "status": "SUCCESS | EXISTING_PROJECT | RECOVERED", "wallet": "string", "projectId": "string", "apiKey": "string", "configPath": "string | null (path where the shared API key was written)", "endpoints": { "mainnet": "string (URL)", "devnet": "string (URL)" }, "credits": "number", "transaction": "string | null (only present for new signups — SUCCESS status)", "projects": "array (only for EXISTING_PROJECT or RECOVERED — list of {id, name})" }, "note": "Passing `--plan ` to signup triggers a separate upgrade flow with a different response shape (status: UPGRADED, includes `plan`, omits `endpoints`/`credits`/`configPath`/`projects`). Not used during agent onboarding." }, "login": { "command": "helius login --json", "description": "Authenticate with existing wallet", "options": { "-k, --keypair ": "Path to Solana keypair file", "--json": "Output in JSON format" }, "requires_auth": false, "json_output": true }, "projects": { "command": "helius projects --json", "description": "List all projects", "requires_auth": true, "json_output": true }, "project": { "command": "helius project [id] --json", "description": "Get project details", "requires_auth": true, "json_output": true }, "apikeys": { "command": "helius apikeys --json", "description": "List API keys for project", "requires_auth": true, "json_output": true, "response": { "projectId": "string", "apiKeys": [{ "keyId": "string", "keyName": "string", "createdAt": "string (ISO 8601 timestamp)" }] } }, "apikeys_create": { "command": "helius apikeys create --json", "description": "Create new API key", "requires_auth": true, "json_output": true }, "usage": { "command": "helius usage --json", "description": "Show credit usage", "requires_auth": true, "json_output": true }, "rpc": { "command": "helius rpc --json", "description": "Show RPC endpoints", "requires_auth": true, "json_output": true } }, "exit_codes": { "0": { "name": "SUCCESS", "action": "Extract apiKey from response" }, "1": { "name": "GENERAL_ERROR", "action": "Check message, retry with backoff" }, "10": { "name": "NOT_LOGGED_IN", "action": "Run helius login first" }, "11": { "name": "KEYPAIR_NOT_FOUND", "action": "Run helius keygen first" }, "12": { "name": "AUTH_FAILED", "action": "Check keypair validity" }, "20": { "name": "INSUFFICIENT_SOL", "action": "Fund wallet with ~0.001 SOL" }, "21": { "name": "INSUFFICIENT_USDC", "action": "Fund wallet with 1 USDC" }, "22": { "name": "PAYMENT_FAILED", "action": "Retry or check network status" }, "30": { "name": "NO_PROJECTS", "action": "Run helius signup first" }, "31": { "name": "PROJECT_NOT_FOUND", "action": "Verify project ID exists" }, "32": { "name": "MULTIPLE_PROJECTS", "action": "Specify project ID explicitly" }, "40": { "name": "API_ERROR", "action": "Retry with exponential backoff" }, "41": { "name": "NO_API_KEYS", "action": "Run helius apikeys create" } }, "error_response_schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error code (e.g., INSUFFICIENT_USDC)" }, "message": { "type": "string", "description": "Human-readable error message" }, "have": { "type": "number", "description": "Current balance (for balance errors)" }, "need": { "type": "number", "description": "Required balance (for balance errors)" }, "fundAddress": { "type": "string", "description": "Wallet address to fund" } }, "required": ["error", "message"] }, "success_response_schema": { "signup": { "description": "Schema for `helius signup --json` output in the agent-onboarding flow (no --plan flag). Plan upgrades return a different shape and are not covered here.", "type": "object", "properties": { "status": { "enum": ["SUCCESS", "EXISTING_PROJECT", "RECOVERED"] }, "wallet": { "type": "string" }, "projectId": { "type": "string" }, "apiKey": { "type": "string" }, "configPath": { "type": ["string", "null"], "description": "Path where the shared API key was written, or null if not saved." }, "endpoints": { "type": "object", "properties": { "mainnet": { "type": "string", "format": "uri" }, "devnet": { "type": "string", "format": "uri" } } }, "credits": { "type": "number" }, "transaction": { "type": ["string", "null"], "description": "Transaction signature. Present only for new signups (SUCCESS status); null otherwise." }, "projects": { "type": "array", "description": "Only present for EXISTING_PROJECT or RECOVERED status — list of existing projects on the account.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } }, "required": ["status", "wallet", "projectId", "apiKey", "endpoints"] } }, "retry_strategy": { "max_retries": 3, "base_delay_ms": 2000, "backoff": "exponential", "retryable_exit_codes": [1, 22, 40], "non_retryable_exit_codes": [11, 20, 21, 30, 31], "note": "Non-retryable codes require user action (funding, keypair generation)" }, "verification": { "test_api_key": { "method": "POST", "url_template": "https://mainnet.helius-rpc.com/?api-key={apiKey}", "headers": { "Content-Type": "application/json" }, "body": { "jsonrpc": "2.0", "id": 1, "method": "getHealth" }, "expected_response": { "jsonrpc": "2.0", "result": "ok", "id": 1 } } }, "rpc_endpoints": { "mainnet": "https://mainnet.helius-rpc.com/?api-key={apiKey}", "devnet": "https://devnet.helius-rpc.com/?api-key={apiKey}" }, "credits": { "initial_amount": 1000000, "check_command": "helius usage --json" }, "idempotency": { "signup": "Running signup with an existing account returns existing project without charging again", "keygen": "Will fail if keypair exists unless --force flag is used" }, "agent_pseudocode": [ "1. Verify CLI installed: run 'helius --version', if fails run 'npm install -g helius-cli'", "2. Check keypair exists at ~/.helius-cli/keypair.json, if not run 'helius keygen'", "3. Run 'helius login --json' to authenticate with Helius", "4. Check wallet balances via Solana RPC (SOL >= 0.001, USDC >= 1)", "5. If insufficient funds, initiate transfer and track at orbmarkets.io/tx/{hash}", "6. Run 'helius signup --json' and parse stdout as JSON", "7. On exit code 0: extract response.apiKey and response.endpoints", "8. On exit code 20/21: return to step 4 (funding needed)", "9. On exit code 11: return to step 2 (keygen needed)", "10. Verify API key with getHealth RPC call", "11. Store apiKey for future Solana RPC calls" ], "examples": { "shell": { "extract_api_key": "API_KEY=$(helius signup --json | jq -r '.apiKey')", "first_rpc_call": "curl -s -X POST \"https://mainnet.helius-rpc.com/?api-key=$API_KEY\" -H 'Content-Type: application/json' -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"getHealth\"}'", "devnet_first_call": "curl -s -X POST \"https://devnet.helius-rpc.com/?api-key=$API_KEY\" -H 'Content-Type: application/json' -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"getSlot\"}'", "devnet_airdrop": "curl -s -X POST \"https://devnet.helius-rpc.com/?api-key=$API_KEY\" -H 'Content-Type: application/json' -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"requestAirdrop\",\"params\":[\"\", 1000000000]}'" }, "typescript": { "extract_api_key": "import { execSync } from 'node:child_process';\nconst { apiKey, endpoints } = JSON.parse(execSync('helius signup --json', { encoding: 'utf8' }));", "first_rpc_call": "const res = await fetch(endpoints.mainnet, {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'getHealth' }),\n});\nconst data = await res.json(); // { jsonrpc: '2.0', result: 'ok', id: 1 }" }, "python": { "extract_api_key": "import json, subprocess\nresult = json.loads(subprocess.check_output(['helius', 'signup', '--json']))\napi_key, endpoints = result['apiKey'], result['endpoints']", "first_rpc_call": "import requests\nresp = requests.post(endpoints['mainnet'], json={'jsonrpc':'2.0','id':1,'method':'getHealth'}).json()\n# -> {'jsonrpc':'2.0','result':'ok','id':1}" } } }