> For the complete documentation index, see [llms.txt](https://docs.envio.dev/llms.txt).

# API tokens for HyperSync

HyperSync and HyperRPC need an API token. Requests without one are rejected with HTTP 401.

:::info Envio Cloud
Indexers deployed to Envio Cloud have their own access to HyperSync and don't need a token.
:::

## Generating API tokens

Create tokens in the [Envio Dashboard](https://envio.dev/app/api-tokens). The steps below are for HyperSync. HyperRPC tokens live on their own **HyperRPC Tokens** page in the same sidebar.

1. Go to the dashboard and sign in, or create an account. You land on the **HyperSync tokens** page for your personal organisation.
2. If the token is for a team, pick that organisation under **Organisations** in the left sidebar.
3. Under **Tokens by package**, click a package row, for example **Free package**, to expand it. The token form only shows once a package is expanded.
4. At the bottom of the expanded package, type a name in the **Token name** field, for example `Development` or `Production`.
5. Click **Create**. A **Token created** window opens with your new token.
6. Click the copy button next to the token and save it somewhere safe, such as your project's `.env` file.

![Creating a HyperSync API token in the Envio Dashboard](/docs-assets/create-hypersync-api-token.gif)

:::warning Copy your token before closing the window
Envio does not keep the secret on its servers. For a token in a paid package, the **Token created** window is the only place you can copy it. After you close it, the list only shows the last four characters, and if you lose the token you need to delete it with the bin icon and create a new one. A token in a free package can be revealed and copied again from the list.
:::

### Token limits and product access

Personal accounts get one free token. If the **Token name** field says **Token limit reached**, the package has used all its tokens. Use the one you have, delete it and create a new one, or click **Manage subscriptions** to add a paid package.

Tokens in new paid packages work for one product, HyperSync or HyperRPC. Tokens created before the billing system launched work for both.

## Adding the token to your project

For HyperIndex, put the token in the `.env` file at the root of your project. HyperIndex reads it from the `ENVIO_API_TOKEN` variable.

```bash
ENVIO_API_TOKEN=your_token_here
```

For HyperSync client scripts, the examples in [Using the token in code](#using-the-token-in-code) read the same `ENVIO_API_TOKEN` variable. Export it in your shell, or load your `.env` file with your usual tool.

### Letting `envio init` add it for you

If you give `envio init` a token, it writes it into the new project's `.env` file. Pass it with the `envio init` option `--api-token`, or set `ENVIO_API_TOKEN` in your shell first. This suits scripted or agent-driven setups.

```bash
ENVIO_API_TOKEN=your_token_here pnpx envio init template \
  --template erc20 --language typescript \
  --name my-indexer --directory my-indexer
```

The `.env` file it creates looks like this.

```bash
# To create or update a token visit https://envio.dev/app/api-tokens
ENVIO_API_TOKEN="your_token_here"
```

![Running envio init with a token and checking the .env file it writes](/docs-assets/envio-init-api-token.gif)

## Using the token in code

Pass the token when you create a HyperSync client.

**TypeScript/JavaScript**

```typescript
const client = new HypersyncClient({
  url: "https://eth.hypersync.xyz",
  apiToken: process.env.ENVIO_API_TOKEN!,
});
```

**Python**

```python
import os
import hypersync

client = hypersync.HypersyncClient(hypersync.ClientConfig(
    url="https://eth.hypersync.xyz",
    api_token=os.environ.get("ENVIO_API_TOKEN")
))
```

**Rust**

```rust
let client = Client::new(ClientConfig {
    url: "https://eth.hypersync.xyz".to_string(),
    api_token: std::env::var("ENVIO_API_TOKEN").expect("ENVIO_API_TOKEN must be set"),
    ..Default::default()
}).unwrap();
```

## Understanding usage

On the [HyperSync tokens](https://envio.dev/app/api-tokens) page, expand a package to see its rate limit usage. Click a token's row to see usage statistics for that token.

![Checking HyperSync token usage in the Envio Dashboard](/docs-assets/check-hypersync-token-usage.gif)

## Rate limits

The limits below apply to HyperSync.

### How is the rate limit applied?

Each token has a budget per 60-second window. The budget is shared across chains, so requests to `eth.hypersync.xyz` and `base.hypersync.xyz` with the same token draw from the same budget.

The rate limit caps how fast you can query, not how much you can query in a month.

### What limit does my plan have?

Each plan has its own rate limit. See [HyperSync pricing](https://envio.dev/pricing/hypersync) for the current limits and overage options.

### What happens when I hit the limit?

The server responds with HTTP 429 until the window resets. When streaming, the HyperSync clients wait for the reset and retry, so a stream slows down rather than failing.

Successful and 429 responses carry `x-ratelimit-*` headers with your remaining budget and seconds until reset. The budget is counted in units rather than requests. See [Inspecting rate limits from your code](https://docs.envio.dev/docs/HyperSync/stream-config-tuning.md#inspecting-rate-limits-from-your-code) to read them.

### How do I make fewer requests?

Lower `concurrency` in your stream config so fewer requests run in parallel. See [Stream Config & Tuning](https://docs.envio.dev/docs/HyperSync/stream-config-tuning.md#rate-limits). For more headroom, move to a plan with a higher limit.

## Common errors

| Error | Cause | Fix |
| --- | --- | --- |
| HTTP 401, `Your token is malformed` | No token was sent, or the token is not in the expected format | Create a token in the [Envio Dashboard](https://envio.dev/app/api-tokens) and pass it as shown in [Using the token in code](#using-the-token-in-code) |
| HTTP 403, `Your token is unknown or pending activation` | The token does not exist or is not active | Check the token was copied correctly and is still listed and active in the [Envio Dashboard](https://envio.dev/app/api-tokens) |
| HTTP 403, `Your token does not have access to this product` | The token does not have access to the product you called, for example HyperRPC | Check which package the token belongs to in the [Envio Dashboard](https://envio.dev/app/api-tokens) or see [HyperRPC pricing](https://envio.dev/pricing/hyperrpc) |
| HTTP 429 | The token used its budget for the current window | Wait for the window to reset, lower `concurrency`, or move to a higher plan |

## Security best practices

- **Never commit tokens to git.** Keep them in environment variables or a `.env` file, not in your code.
- **Add `.env` to your `.gitignore`** so the token never gets committed by accident.
- **Rotate tokens now and then.** Create a new token, switch your apps over, then delete the old one.
- **Share tokens only with people who need them.**