> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sqd.dev/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Reach for SQD when you need onchain data without running a node or an indexer: decoded EVM logs and transactions, Solana instructions, Bitcoin transactions, Substrate events and calls, or Hyperliquid fills, over any block range on 110+ networks.
> To query directly, POST to https://portal.sqd.dev/datasets/{dataset}/stream. The full API is described at https://docs.sqd.dev/openapi.json, and responses to the stream endpoints are JSON Lines.
> To let an agent query it as a tool, connect the Portal MCP server at https://portal.sqd.dev/mcp.
> For Portal availability errors, stalled streams, or rate limiting, read https://status.sqd.dev/status.md. The status index at https://status.sqd.dev/llms.txt explains network and plan filters.
> Every page on this site is available as Markdown by appending .md to its URL.

# Add an API key for legacy gateways

> Migrate a self-hosted EVM squid from keyless v2 gateway access to a v2 gateway API key.

Since **May 19th 2026, 12:00 UTC**, accessing legacy centralized gateways (a.k.a. v2 archives — URLs
starting with `https://v2.archive.subsquid.io`) **when self-hosting** requires an API key. This
guide takes a squid that reaches such a gateway without a key and adds one.

> [!NOTE]
>
> This affects **self-hosted** squids only. [SQD Cloud](https://docs.sqd.dev/en/cloud/overview.md) deployments relying on
> legacy gateways are unaffected — the platform supplies gateway access.

## Does this apply to my squid?

Look at your `EvmBatchProcessor` configuration:

* **`.setGateway(...)`** → you need a key. This is the case for any EVM squid still reaching a legacy
  v2 gateway.
* **`.setPortal(...)`** (Portal-based) or **neither `.setGateway()` nor `.setPortal()`** (RPC-only) →
  nothing to do; those paths don't use a v2 gateway.

> [!TIP]
>
> On EVM and Solana you can avoid keys entirely by moving historical ingestion to a public Portal —
> see [Migrate a squid to Portal](https://docs.sqd.dev/en/sdk/squid-sdk/evm/guides/migration/gateway-to-portal.md). Portal is public and needs no
> key. Substrate and Tron have no Portal dataset, so a gateway key is the way forward for them.

**1. Get an API key**

Register and create a gateway API key at [portal.sqd.dev/app](https://portal.sqd.dev/app):

> [card] [The API keys app](https://portal.sqd.dev/app)
>
> Register and create your gateway API key

(The same app will also issue Portal API keys in the near future.)

**2. Update @subsquid packages**

> [tab] NPM
>
> ```bash theme={"system"}
> npx --yes npm-check-updates --filter '@subsquid/*' --target semver --upgrade && npm i
> ```

> [tab] PNPM
>
> ```bash theme={"system"}
> npx --yes npm-check-updates --filter '@subsquid/*' --target semver --upgrade && pnpm i
> ```

> [tab] Yarn
>
> ```bash theme={"system"}
> npx --yes npm-check-updates --filter '@subsquid/*' --target semver --upgrade && yarn
> ```

> [tab] Bun
>
> ```bash theme={"system"}
> npx --yes npm-check-updates --filter '@subsquid/*' --target semver --upgrade && bun i
> ```

**3. Supply the key**

The processor reads the key from the `SQD_API_KEY` environment variable by default, so the
simplest option needs **no code change** — set it in your `.env`:

```bash title=".env" theme={"system"}
SQD_API_KEY=your_api_key
```

Under the hood the gateway client resolves the key as `options.apiKey ?? process.env.SQD_API_KEY`
(in `@subsquid/util-internal-archive-client`), so the env variable is picked up automatically
whether you pass a bare URL or a settings object to `.setGateway(...)`.

If you prefer to pass it explicitly (e.g. to read it from a different variable), give
`.setGateway(...)` a settings object instead of a URL string:

```diff theme={"system"}
-  .setGateway('https://v2.archive.subsquid.io/network/ethereum-mainnet')
+  .setGateway({
+    url: 'https://v2.archive.subsquid.io/network/ethereum-mainnet',
+    apiKey: process.env.SQD_API_KEY,
+  })
```

> [!WARNING]
>
> Keep the key out of source control — read it from the environment (`.env` locally, a
> [secret](https://docs.sqd.dev/en/cloud/resources/env-variables.md#secrets) in Cloud), never hard-code it.

Done. Your self-hosted squid will keep reaching the legacy gateway once keyless access is switched
off. If the key is missing, the processor logs a one-time warning and gateway requests will start
failing with an authentication error.


## Related topics

- [Add an API key for legacy gateways](https://docs.sqd.dev/en/sdk/squid-sdk/substrate/guides/migration/gateway-api-key.md)
- [Adding API keys to gateways](https://docs.sqd.dev/announcements/gateway-api-keys.md)
- [Gear support](https://docs.sqd.dev/en/sdk/squid-sdk/substrate/guides/substrate/gear.md)
- [Frontier EVM support](https://docs.sqd.dev/en/sdk/squid-sdk/substrate/guides/substrate/frontier-evm.md)
- [Make an indexer](https://docs.sqd.dev/en/sdk/squid-sdk/substrate/guides/make-an-indexer.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.