# Helius Authentication — Agent Guide

> Authentication metadata for agents calling the Helius API. Every Helius endpoint authenticates with a long-lived API key passed as the `api-key` query string parameter — there is no OAuth flow, no ID-JAG identity assertion, and no bearer-token exchange.

This document follows the section structure of the WorkOS [`auth.md`](https://workos.com/auth-md) draft (Discover → Pick a method → Register → Claim → Use → Errors → Revocation) so agent-auth scanners find the expected anchors. Where the spec assumes OAuth primitives (Protected Resource Metadata, Authorization Server metadata, dynamic client registration), each section explains the Helius equivalent — usually a CLI command or a dashboard URL.

---

## 1. Discover

There is no `/.well-known/oauth-protected-resource` or `/.well-known/oauth-authorization-server` at `helius.dev`, because Helius is not an OAuth resource server. The agent-readable discovery surfaces are:

| Surface | URL | Purpose |
|---------|-----|---------|
| Root `llms.txt` | https://www.helius.dev/llms.txt | Phonebook of agent surfaces |
| AGENTS.md | https://www.helius.dev/AGENTS.md | Agent onboarding doc |
| API catalog (RFC 9727) | https://www.helius.dev/.well-known/api-catalog | Linkset of API surfaces |
| Agent card (A2A) | https://www.helius.dev/.well-known/agent-card.json | A2A protocol manifest |
| MCP server card | https://www.helius.dev/.well-known/mcp/server-card.json | MCP tool inventory |
| OpenAPI catalog | https://www.helius.dev/openapi.json | Merged OpenAPI spec |
| Signup spec (JSON) | https://www.helius.dev/api/agents.json | Machine-readable signup flow |
| Signup spec (Markdown) | https://www.helius.dev/api/agents.md | Same flow, human-readable |
| CLI reference | https://www.helius.dev/cli.md | helius-cli command catalog |

### 1a. Protected Resource Metadata (equivalent)

Helius does not publish RFC 9728 PRM. The equivalent metadata an agent needs before calling a Helius endpoint is summarized below and detailed in the [OpenAPI catalog](https://www.helius.dev/openapi.json) and the [API catalog linkset](https://www.helius.dev/.well-known/api-catalog):

- **Resource:** Helius RPC and Enhanced APIs
- **Auth scheme:** API key, query parameter (`?api-key=YOUR_KEY`)
- **Bearer token support:** None — do not send `Authorization: Bearer`
- **Networks:** Solana mainnet (`https://mainnet.helius-rpc.com`), devnet (`https://devnet.helius-rpc.com`)
- **Token formats accepted:** API key only

### 1b. Authorization Server Metadata (equivalent)

There is no authorization server. Credential issuance happens at one of two endpoints:

- **Human signup:** https://dashboard.helius.dev/signup (web UI, email + wallet)
- **Agent signup:** `helius signup --json` from the [Helius CLI](https://www.helius.dev/cli.md) — pays 1 USDC on Solana mainnet, returns an API key in stdout JSON

Both flows mint the same credential type (an API key string). There is no token endpoint, no introspection endpoint, no JWKS, and no ID-JAG identity assertion exchange.

---

## 2. Pick a method

Agents have one credential type and two acquisition paths:

### `agent_auth` methods

| Method | When to use | Cost | Time |
|--------|-------------|------|------|
| `cli_signup` | Autonomous agent with a funded Solana wallet | 1 USDC + ~0.001 SOL | ~30 seconds |
| `dashboard_signup` | Human-operated agent; or no wallet available | Free tier available | Manual (browser) |
| `existing_key` | Agent inherits a key from its operator | N/A | N/A |

The `cli_signup` path is the canonical autonomous flow. It does not require browser-based consent, OAuth redirect URIs, PKCE, or device-code polling. The wallet signature on the 1 USDC payment is the consent.

---

## 3. Register

WorkOS `register_uri`: the URL where an agent registers and receives a credential.

**`register_uri`:** https://dashboard.helius.dev/signup (human)
**`register_uri` (programmatic):** invoke `helius signup --json` locally — the CLI is the registration client; it does not POST to a discoverable HTTP endpoint. Source: https://github.com/helius-labs/core-ai/tree/main/helius-cli

### Prerequisites

1. Node.js 18+ (for the programmatic path)
2. A Solana wallet funded with:
   - 1 USDC on Solana mainnet (token mint `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`)
   - ~0.001 SOL for transaction fees

### Programmatic registration flow

```bash
npm install -g helius-cli
helius keygen                 # creates ~/.helius-cli/keypair.json
helius login --json           # authenticates the keypair
# (fund the wallet with 1 USDC + ~0.001 SOL)
helius signup --json
```

Full registration spec, error codes, and retry strategy: https://www.helius.dev/api/agents.md

---

## 4. Claim ceremony

WorkOS `claim_uri`: where the agent picks up the issued credential.

**`claim_uri`:** https://dashboard.helius.dev/api-keys

For the CLI path there is no separate claim step — `helius signup --json` returns the API key in its stdout JSON response on exit code 0:

```json
{
  "status": "SUCCESS",
  "apiKey": "your-api-key-here",
  "projectId": "project-uuid",
  "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
}
```

If the wallet already has a Helius account, the same command returns `"status": "EXISTING_PROJECT"` with the existing API key (no duplicate payment). The flow is idempotent.

There is no `identity_assertion` exchange and no ID-JAG token. The API key string itself is the credential.

---

## 5. Use the credential

The API key is passed as a query string parameter on every request. **Do not** send it as a `Bearer` token in the `Authorization` header — Helius endpoints do not parse that header and will return 401.

### Solana RPC + DAS

```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: `{"jsonrpc":"2.0","result":"ok","id":1}`

### Sender (transaction submission)

```
http://slc-sender.helius-rpc.com/?api-key=YOUR_API_KEY
```

Sender has 7 regional HTTP endpoints (`slc-`, `ewr-`, `lon-`, `fra-`, `ams-`, `sg-`, `tyo-`) plus a global HTTPS endpoint at `https://sender.helius-rpc.com` for frontend use. Regional endpoints are HTTP-only by design — TLS is skipped to minimize latency for backend-to-backend submission. See https://www.helius.dev/sender.

### LaserStream (gRPC streaming)

LaserStream uses the same API key, passed as gRPC metadata. Exact header name, endpoint hosts, and the 9-region footprint are documented at https://www.helius.dev/laserstream.

### Webhooks

The webhooks API is hosted on a separate origin and uses the same API key in the query string:

```
https://api.helius.xyz/v0/webhooks?api-key=YOUR_API_KEY
```

Full per-endpoint reference: https://www.helius.dev/openapi.json and https://www.helius.dev/AGENTS.md

---

## 6. Errors

Helius does not emit OAuth-style `WWW-Authenticate: Bearer error="invalid_token"` challenges. Authentication failures surface as HTTP status codes with JSON-RPC error bodies (for RPC) or plain JSON (for Enhanced APIs).

### HTTP status codes

| Status | Meaning | Action |
|--------|---------|--------|
| 200 | OK | Process response |
| 401 | Missing or invalid `api-key` query parameter | Verify the key and that it's passed as `?api-key=...`, not in a header |
| 403 | Key valid but blocked (suspended, plan limit) | Check https://dashboard.helius.dev for account status |
| 429 | Rate limit exceeded | Back off; see plan limits at https://www.helius.dev/pricing.md |
| 5xx | Transient upstream error | Retry with exponential backoff |

### CLI signup exit codes

The `helius signup --json` command surfaces credential-acquisition errors via exit code. The full table lives at https://www.helius.dev/api/agents.md. Highlights:

| Exit code | Error | Action |
|-----------|-------|--------|
| 0 | Success | Extract `apiKey` from stdout JSON |
| 10 | Not logged in | Run `helius login` |
| 11 | Keypair not found | Run `helius keygen` |
| 20 | Insufficient SOL | Fund wallet with ~0.001 SOL |
| 21 | Insufficient USDC | Fund wallet with 1 USDC |
| 22 | Payment failed | Retry or check Solana network status |

### Error response shape (CLI)

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

---

## 7. Revocation

WorkOS `revocation_uri`: where a credential is revoked.

**`revocation_uri`:** https://dashboard.helius.dev/api-keys

API keys are managed in the dashboard. To revoke:

1. Sign in at https://dashboard.helius.dev
2. Open the API Keys panel
3. Delete or rotate the key

There is no public HTTP revocation endpoint and no programmatic CLI revocation command today. Rotation is a delete-then-create operation in the dashboard. Compromised keys should be rotated immediately; in-flight requests continue to authenticate until the key is deleted.

### Key lifetime

API keys are long-lived and do not expire on a schedule. They remain valid until:
- The owner deletes them in the dashboard, or
- The associated project is suspended for plan or abuse reasons

There are no refresh tokens, no rotation cadence, and no short-lived bearer tokens issued from the API key.

---

## Spec mismatch — what Helius does *not* implement

For transparency, the following WorkOS `auth.md` / OAuth concepts have no Helius equivalent:

- `WWW-Authenticate: Bearer ...` challenge headers
- Protected Resource Metadata (RFC 9728)
- Authorization Server Metadata (RFC 8414)
- Dynamic Client Registration (RFC 7591)
- ID-JAG identity assertion JWTs
- PKCE / device-code / authorization-code flows
- Token introspection / revocation HTTP endpoints
- JWKS endpoint or signing-key rotation

If a future agent-auth spec converges on something Helius can implement cleanly on top of API keys, this document will be updated.

---

## References

- WorkOS `auth.md` spec: https://github.com/workos/auth.md
- Helius agent surfaces index: https://www.helius.dev/llms.txt
- Programmatic signup spec: https://www.helius.dev/api/agents.md, https://www.helius.dev/api/agents.json
- API catalog (linkset): https://www.helius.dev/.well-known/api-catalog
- OpenAPI catalog: https://www.helius.dev/openapi.json
- Pricing and rate limits: https://www.helius.dev/pricing.md
- Dashboard: https://dashboard.helius.dev