Authentication

To access Bitquery's Solana gRPC streams (CoreCast), you must authenticate every stream using an authorization token. This token is provided in your configuration file and automatically added to the gRPC metadata before starting a stream. Check the documentation to create a new token.

---

Overview

1. Generate an API token at account.bitquery.io
2. Add it to your config or environment
3. Inject it into gRPC metadata as Authorization header before each stream call

---

Quick Example

Minimal Node.js snippet: create metadata and start a stream. Use your token from config.yaml or process.env.

const grpc = require('@grpc/grpc-js');

const metadata = new grpc.Metadata();
metadata.add('authorization', process.env.BITQUERY_TOKEN || config.server.authorization);

// Use with any CoreCast stream (DexTrades, Transfers, etc.)
const stream = client.DexTrades(request, metadata);
stream.on('data', (msg) => console.log(msg));
stream.on('error', (err) => console.error(err));

No extra headers

Only the authorization header is required. No API keys or other credentials.

---

Configuration

The token is defined under the server in the config.yaml file:

server:
  address: "corecast.bitquery.io"
  authorization: "<YOUR_TOKEN>"
  insecure: false

Field	Description
address	gRPC server host: corecast.bitquery.io
authorization	Your API token (usually starts with ory_at_...)
insecure	Set true for unencrypted; prefer false (TLS)

---

How it works

At runtime, the token from config.server.authorization is injected into gRPC metadata:

const metadata = new grpc.Metadata();
metadata.add('authorization', config.server.authorization);

// Example stream
const stream = client.DexTrades(request, metadata);

This adds an authorization header to the gRPC call. No other headers or credentials are required.

---

Security

• Always keep your token secret — do not hardcode it in your codebase.
• Store it in config.yaml, an environment variable, or a secret manager.
• If insecure: true, traffic will not be encrypted. Prefer TLS (insecure: false).

---

Common Issues

When authentication fails, you'll see gRPC error code 16 with HTTP status 401 Unauthorized:

{
  "code": 16,
  "details": "Received HTTP status code 401"
}

Causes

• Incorrect token → Typo in config.yaml or copied wrong value.
• Missing token → No authorization field in config.yaml.
• Expired token → Token is no longer valid.

Debugging Methods

1. Verify token in config.yaml Ensure it looks like:

   server:
     authorization: "ory_at_xxx..."

   and not empty.

2. Check for quotes/whitespace Tokens should be a single continuous string. No extra spaces or line breaks.

3. Confirm token is active If the token expired or was revoked, generate a new one from your Bitquery account.