Authentication

Architecture

All API requests pass through a gateway that validates credentials before forwarding to backend services. The gateway delegates authentication and quota checking to an internal auth & billing service, ensuring every request is verified in a single hop. When authentication fails, the gateway returns an error directly (401 Unauthorized, or 402 Payment Required when x402 is enabled) without hitting the backend.

Three Authentication Methods

ChainStream supports three credential types, evaluated in this order:

Priority	Method	Header	Best For
1	Wallet Signature (SIWX)	`Authorization: SIWX <token>`	AI agents with on-chain wallets (x402 subscribers)
2	API Key	`X-API-KEY: <key>`	Applications, scripts, CLI, MCP Server
3	JWT Bearer Token	`Authorization: Bearer <jwt>`	Dashboard apps using OAuth 2.0 Client Credentials

If no valid credentials are found and x402 is enabled, the gateway returns HTTP 402 Payment Required with a pointer to /x402/purchase. This allows AI agents to auto-purchase a subscription.

Method 1: API Key (Recommended)

The simplest authentication method. Create an API Key in the Dashboard and pass it in the X-API-KEY header.

Get an API Key

Visit ChainStream Dashboard and login

Go to Applications

Find “Applications” in the sidebar

Create New App

Click “Create New App” to generate your API Key

Use the API Key

cURL
SDK
CLI
MCP Server

curl https://api.chainstream.io/v2/token/sol/So11111111111111111111111111111111111111112 \
  -H "X-API-KEY: your_api_key"

import { ChainStreamClient } from "@chainstream-io/sdk";

const cs = new ChainStreamClient({
  apiKey: "your_api_key",
});

const token = await cs.token.getToken("So11111111111111111111111111111111111111112", "solana");

chainstream config set --key apiKey --value your_api_key
chainstream token info --chain sol --address So11111111111111111111111111111111111111112

export CHAINSTREAM_API_KEY=your_api_key
npx @chainstream-io/mcp

How It Works

The gateway extracts the X-API-KEY header
The auth service validates the key against the database
On success, the request is forwarded with the associated organization and permission context
The key must be active and not expired

Keep your API Key secure. Never commit it to code repositories. If compromised, revoke it immediately in the Dashboard.

Method 2: JWT Bearer Token (OAuth 2.0)

For applications that use the OAuth 2.0 Client Credentials flow. Exchange your Client ID and Client Secret for a JWT access token.

Generate Access Token

cURL
JavaScript
Python

curl -X POST "https://dex.asia.auth.chainstream.io/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "https://api.dex.chainstream.io",
    "grant_type": "client_credentials"
  }'

const response = await fetch('https://dex.asia.auth.chainstream.io/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    audience: 'https://api.dex.chainstream.io',
    grant_type: 'client_credentials'
  })
});

const { access_token } = await response.json();

import requests

response = requests.post(
    'https://dex.asia.auth.chainstream.io/oauth/token',
    json={
        'client_id': 'YOUR_CLIENT_ID',
        'client_secret': 'YOUR_CLIENT_SECRET',
        'audience': 'https://api.dex.chainstream.io',
        'grant_type': 'client_credentials'
    }
)

access_token = response.json()['access_token']

Use the Token

curl https://api.chainstream.io/v2/token/sol/So11111111111111111111111111111111111111112 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

How It Works

The gateway extracts the Authorization: Bearer <jwt> header
The auth service validates the JWT signature, issuer, and audience
The client_id claim is resolved to an organization for quota tracking

Token Details

Validity: 24 hours by default
Algorithm: RS256
Issuer: https://dex.asia.auth.chainstream.io/
Audience: https://api.dex.chainstream.io

Scope Permissions

Certain endpoints require specific scopes:

Scope	Description	Applicable Endpoints
`webhook.read`	Webhook read access	Query Webhook configuration
`webhook.write`	Webhook write access	Create/modify/delete Webhooks
`kyt.read`	KYT read access	Query risk assessment results
`kyt.write`	KYT write access	Submit transactions/addresses for risk assessment

const response = await auth0Client.oauth.clientCredentialsGrant({
  audience: 'https://api.dex.chainstream.io',
  scope: 'webhook.read webhook.write kyt.read kyt.write'
});

If no scope is specified, the token can access all general API endpoints. Scope is only required for Webhook and KYT endpoints.

Method 3: Wallet Signature (SIWX)

For AI agents with on-chain wallets that have purchased a subscription via x402 payment. Uses the Sign-In with X (SIWX) standard (EIP-4361 for EVM, equivalent for Solana).

How It Works

The agent constructs a standard sign-in message with domain, address, nonce, and expiration
The agent signs the message with their wallet private key
The signed token is sent as Authorization: SIWX base64(message).signature
The auth service verifies the signature and checks for a valid x402 subscription
If a valid, non-expired subscription exists, authentication succeeds

Token Format

Authorization: SIWX base64(message).signature

The message follows the EIP-4361 format:

api.chainstream.io wants you to sign in with your Ethereum account:
0xYourWalletAddress

Sign in to ChainStream API

URI: https://api.chainstream.io
Version: 1
Chain ID: 8453
Nonce: abc123
Issued At: 2026-03-26T10:00:00Z
Expiration Time: 2026-03-27T10:00:00Z

Supported Chains

Chain	Address Format	Signature Type
EVM (Base, Ethereum)	`0x` prefixed, 40 hex chars	EIP-191 personal_sign
Solana	Base58 encoded, 32-44 chars	Ed25519

SDK Usage

const cs = new ChainStreamClient({
  auth: {
    type: "siwx",
    address: "0xYourWalletAddress",
    signMessage: async (message: string) => {
      return await wallet.signMessage(message);
    },
  },
});

SIWX authentication requires an active x402 subscription. If the subscription has expired, the request will be rejected. See x402 Payment for purchasing a subscription.

WebSocket Authentication

WebSocket connections use the same three authentication methods. The gateway:

Detects WebSocket upgrade requests
Validates credentials before allowing the handshake
Tracks the session for usage metering
Reports usage metrics (bytes transferred, duration) on disconnect

WebSocket tokens can also be passed as a query parameter:

wss://realtime-dex.chainstream.io/connection/websocket?token=YOUR_ACCESS_TOKEN

Authentication Priority

When multiple credentials are present in a single request, they are evaluated in this order:

SIWX — if Authorization header starts with SIWX and x402 is configured
API Key — if X-API-KEY header is present
JWT Bearer — if Authorization header starts with Bearer
402 Payment Required — if no credentials match and x402 is enabled

The first successful match wins. Subsequent methods are not evaluated.

API Endpoints

Service	URL
Mainnet API	`https://api.chainstream.io/`
WebSocket	`wss://realtime-dex.chainstream.io/connection/websocket`
Auth Service (OAuth)	`https://dex.asia.auth.chainstream.io/`
x402 Pricing	`https://api.chainstream.io/x402/pricing`
x402 Purchase	`https://api.chainstream.io/x402/purchase`

Choosing an Auth Method

API Key

Best for: Applications, scripts, CLI, MCP ServerSimplest setup. Create in Dashboard, pass as header. No token refresh needed.

JWT Bearer

Best for: Dashboard apps, server-to-serverStandard OAuth 2.0 flow. Supports scoped permissions. 24h token TTL.

SIWX Wallet

Best for: AI agents with on-chain walletsWallet-native auth via x402 subscription. No API key management needed.

FAQ

Which method should I use?

API Key is recommended for most use cases. It’s the simplest to set up and works with all ChainStream products (SDK, CLI, MCP Server). Use JWT if you need OAuth 2.0 integration with scoped permissions. Use SIWX if you’re building an AI agent with its own wallet and want to pay via x402.

What if the token expires?

For JWT: generate a new token using your Client ID and Client Secret. For SIWX: sign a new message with a future expiration time. API Keys do not expire unless you set an expiration date in the Dashboard.

Can I use multiple auth methods?

Only one method is evaluated per request. If you send both X-API-KEY and Authorization: Bearer, the API Key takes priority (SIWX > API Key > JWT).

What is the 402 Payment Required response?

When no valid credentials are found and x402 is enabled, the gateway returns HTTP 402 with instructions to purchase a subscription at /x402/purchase. This enables AI agents to auto-purchase access. See x402 Payment.

How do I revoke credentials?

API Key: Delete the App in the Dashboard. The key is invalidated immediately. JWT: Revoke the Client ID/Secret in the Dashboard. SIWX: The subscription expires naturally; there is no manual revocation.

Data Products

Access Methods

AI Agents

Compliance (KYT/KYA)

Tutorials

Recipes

Platform

Ecosystem

Reference

Architecture

Three Authentication Methods

Method 1: API Key (Recommended)

Get an API Key

Use the API Key

How It Works

Method 2: JWT Bearer Token (OAuth 2.0)

Generate Access Token

Use the Token

How It Works

Token Details

Scope Permissions

Method 3: Wallet Signature (SIWX)

How It Works

Token Format

Supported Chains

SDK Usage

WebSocket Authentication

Authentication Priority

API Endpoints

Choosing an Auth Method

API Key

JWT Bearer

SIWX Wallet

FAQ

Data Products

Access Methods

AI Agents

Compliance (KYT/KYA)

Tutorials

Recipes

Platform

Ecosystem

Reference

​Architecture

​Three Authentication Methods

​Method 1: API Key (Recommended)

​Get an API Key

​Use the API Key

​How It Works

​Method 2: JWT Bearer Token (OAuth 2.0)

​Generate Access Token

​Use the Token

​How It Works

​Token Details

​Scope Permissions

​Method 3: Wallet Signature (SIWX)

​How It Works

​Token Format

​Supported Chains

​SDK Usage

​WebSocket Authentication

​Authentication Priority

​API Endpoints

​Choosing an Auth Method

API Key

JWT Bearer

SIWX Wallet

​FAQ

Architecture

Three Authentication Methods

Method 1: API Key (Recommended)

Get an API Key

Use the API Key

How It Works

Method 2: JWT Bearer Token (OAuth 2.0)

Generate Access Token

Use the Token

How It Works

Token Details

Scope Permissions

Method 3: Wallet Signature (SIWX)

How It Works

Token Format

Supported Chains

SDK Usage

WebSocket Authentication

Authentication Priority

API Endpoints

Choosing an Auth Method

FAQ