# Helius API Key Signup - Agent Instructions

> Machine-readable instructions for AI agents to obtain a Helius API key via CLI.

## Quick Reference

| Requirement | Value |
|-------------|-------|
| Cost | 1 USDC (mainnet) |
| Transaction Fee | ~0.001 SOL |
| Network | Solana Mainnet |
| CLI Install | `npm install -g helius-cli` |
| Output Format | JSON (use `--json` flag) |

## Prerequisites

1. Node.js 18+ installed
2. A funded Solana wallet with:
   - **1 USDC** (mainnet) - for signup payment
   - **~0.001 SOL** - for transaction fees

## Complete Flow

### Step 1: Install CLI

```bash
npm install -g helius-cli
```

### Step 2: Generate Keypair

```bash
helius keygen
```

**Output:** Creates keypair at `~/.helius-cli/keypair.json`

**Returns:** Wallet address to fund

### Step 3: Fund Wallet

Send to the wallet address from Step 2:
- 1 USDC (token: `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`)
- ~0.001 SOL

### Step 4: Signup and Get API Key

```bash
helius signup --json
```

**Success Response (exit code 0):**
```json
{
  "status": "SUCCESS",
  "wallet": "YourWalletAddress...",
  "projectId": "project-uuid",
  "projectName": "Project Name",
  "apiKey": "your-api-key-here",
  "endpoints": {
    "mainnet": "https://mainnet.helius-rpc.com/?api-key=your-api-key-here",
    "devnet": "https://devnet.helius-rpc.com/?api-key=your-api-key-here"
  },
  "credits": 1000000,
  "transaction": "transaction-signature"
}
```

**Extract API key:** `response.apiKey`

**Extract RPC URL:** `response.endpoints.mainnet` or `response.endpoints.devnet`

## Error Handling

All errors return JSON with `--json` flag and specific exit codes.

### Exit Codes

| Code | Meaning | Action |
|------|---------|--------|
| 0 | Success | Extract `apiKey` from response |
| 1 | General error | Check message, retry with backoff |
| 10 | Not logged in | Run `helius login` first |
| 11 | Keypair not found | Run `helius keygen` first |
| 12 | Auth failed | Check keypair validity |
| 20 | Insufficient SOL | Fund wallet with ~0.001 SOL |
| 21 | Insufficient USDC | Fund wallet with 1 USDC |
| 22 | Payment failed | Retry or check network status |
| 30 | No projects | Run `helius signup` first |
| 31 | Project not found | Check project ID |
| 40 | API error | Retry with exponential backoff |
| 41 | No API keys | Create one with `helius apikeys create` |

### Error Response Format

```json
{
  "error": "INSUFFICIENT_USDC",
  "message": "Insufficient USDC",
  "have": 0.5,
  "need": 1,
  "fundAddress": "YourWalletAddress..."
}
```

## Existing Account Flow

If the wallet already has a Helius account, `signup` returns existing project (no payment required):

```json
{
  "status": "EXISTING_PROJECT",
  "wallet": "YourWalletAddress...",
  "projectId": "existing-project-uuid",
  "projectName": "Existing Project",
  "apiKey": "existing-api-key",
  "endpoints": {
    "mainnet": "https://mainnet.helius-rpc.com/?api-key=existing-api-key",
    "devnet": "https://devnet.helius-rpc.com/?api-key=existing-api-key"
  },
  "credits": 950000
}
```

## Alternative: Login with Existing Wallet

If you have a funded wallet that already has a Helius account:

```bash
helius login --keypair /path/to/keypair.json --json
```

Then retrieve API key:

```bash
helius apikeys --json
```

## Command Reference

| Command | Purpose | JSON Output |
|---------|---------|-------------|
| `helius keygen` | Generate new keypair | Address printed to stdout |
| `helius keygen -o <path>` | Generate keypair at custom path | Address printed to stdout |
| `helius signup --json` | Create account + get API key | Full project response |
| `helius signup -k <path> --json` | Signup with custom keypair | Full project response |
| `helius login --json` | Auth with default keypair | Auth confirmation |
| `helius login -k <path> --json` | Auth with custom keypair | Auth confirmation |
| `helius projects --json` | List all projects | Project array |
| `helius project [id] --json` | Get project details | Full project object |
| `helius apikeys --json` | List API keys | Key array |
| `helius apikeys create --json` | Create new API key | New key object |
| `helius rpc --json` | Get RPC endpoints | Endpoint URLs |
| `helius usage --json` | Check credit usage | Usage stats |

## Agent Implementation Pseudocode

```
1. CHECK if helius-cli installed
   - Run: `helius --version`
   - If fails: run `npm install -g helius-cli`

2. CHECK if keypair exists at ~/.helius-cli/keypair.json
   - If not: run `helius keygen`, capture wallet address from output

3. CHECK wallet balances (via Solana RPC or external service)
   - SOL balance: getBalance RPC call
   - USDC balance: getTokenAccountsByOwner for mint EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
   - If SOL < 0.001: fund wallet, wait for confirmation
   - If USDC < 1: fund wallet, wait for confirmation

4. RUN `helius signup --json`
   - Parse JSON response from stdout
   - Check exit code:
     - 0: Success - extract apiKey
     - 20: Need SOL - return to step 3
     - 21: Need USDC - return to step 3
     - 11: Need keypair - return to step 2
     - Other: Log error, retry with backoff

5. STORE for future use:
   - apiKey: response.apiKey
   - projectId: response.projectId
   - rpcMainnet: response.endpoints.mainnet
   - rpcDevnet: response.endpoints.devnet

6. VERIFY API key works:
   - POST to RPC endpoint with getHealth method
   - Expected: {"jsonrpc":"2.0","result":"ok","id":1}
```

## Solana Token Addresses

| Token | Mainnet Address |
|-------|-----------------|
| USDC | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` |
| SOL | Native (no token address) |

**Helius Treasury (payment recipient):** `CEs84tEowsXpH8u4VBf8rJSVgSRypFMfXw9CpGRtQgb6`

## Rate Limits and Credits

- **Initial Credits:** 1,000,000 credits on signup
- **Credit Check:** Use `helius usage --json` to monitor remaining credits
- **Rate Limits:** Vary by plan, check Helius documentation

## Retry Strategy

For transient failures (network issues, API errors):

```
maxRetries = 3
baseDelay = 2000ms

for attempt in 1..maxRetries:
    result = execute_command()
    if result.exitCode == 0:
        return result
    if result.exitCode in [20, 21, 11]:  # Funding/setup issues
        return result  # Don't retry, needs user action
    delay = baseDelay * (2 ^ attempt)
    sleep(delay)
```

## Important Notes

- **Network:** All payments are on Solana **mainnet** (not devnet)
- **Idempotent:** Running signup with an existing account returns existing project (no duplicate payment)
- **Config Location:** JWT stored at `~/.helius-cli/config.json`
- **Keypair Format:** Solana CLI format (64-byte JSON array)
- **Default Keypair:** `~/.helius-cli/keypair.json`

## Testing Your API Key

```bash
curl "https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"getHealth"}'
```

Expected response: `{"jsonrpc":"2.0","result":"ok","id":1}`

## What is Helius?

Helius is the leading RPC and API provider for the Solana blockchain. The API key obtained through this CLI provides access to:

- **RPC Endpoints:** High-performance Solana RPC for mainnet and devnet
- **Enhanced APIs:** NFT metadata, transaction history, webhooks
- **DAS API:** Digital Asset Standard API for compressed NFTs

Documentation: https://docs.helius.dev