Skip to main content
Overview WaaS APIs are designed for server‑to‑server usage and never exposed directly to end users. Authentication follows three core principles:
  • Server‑only credentials (no client‑side API keys)
  • Short‑lived, request‑bound tokens
  • Wallet‑level authorization for sensitive operations This ensures that:
  • API key leakage does not imply asset loss
  • Wallet operations are cryptographically bound to intent
  • All write actions are auditable and policy‑controlled

​
Authentication Model

WaaS uses a multi‑layer authentication model:
Wallet Auth Tokens are required only for wallet write operations (e.g. signing, transfers).

​
Project API Key

​
What it is

A Project API Key uniquely identifies your WaaS project and acts as the root credential for issuing request tokens.

​
Usage rules

  • Server‑side only
  • Never embedded in frontend, mobile apps, or client SDKs
  • Can be restricted by IP, environment, and policy

​
What it can do

✅ Read wallet metadata
✅ List addresses and balances
✅ Mint short‑lived Access Tokens
🚫 Cannot sign transactions
🚫 Cannot access wallet secrets

​
Access Token (JWT)

Access Tokens are short‑lived JWTs used to authenticate individual API requests.

​
Why JWT

  • Stateless verification
  • High performance at the gateway layer
  • Request‑level binding

​
Request binding

Each Access Token is bound to:
  • HTTP Method
  • Host
  • Path
If any of these differ, the request will be rejected.

​
Example payload

{
  "iss": "waas",
  "sub": "project_123",
  "exp": 1700000000,
  "nbf": 1699999880,
  "uri": "POST waas.chainstream.io/v1/wallets"
}

​
Wallet Auth Token

Wallet Auth Tokens provide wallet‑level authorization and are required for all state‑changing wallet operations.

​
When it is required

  • Signing transactions
  • Transferring assets
  • Approvals and delegations
  • Any operation that changes on‑chain state

​
Wallet Secret

Each wallet has a Wallet Secret:
  • Generated inside WaaS Secure Execution Environment (SEE)
  • Never exported or exposed
  • Used only to issue Wallet Auth Tokens
Think of this as the wallet’s root authorization key.

​
Request body binding

The Wallet Auth Token includes a hash of the canonical request body. If the body is modified (even whitespace), validation will fail.

​
Making an Authenticated Request

​
Example: Sign a transaction

POST /v1/wallets/{wallet_id}/sign-transaction
Authorization: Bearer <access_token>
X-Wallet-Auth: <wallet_auth_token>
Content-Type: application/json

{
  "chain": "ethereum",
  "tx": {
    "to": "0x...",
    "value": "1000000000000000000"
  }
}

​
Validation flow

  1. API Gateway validates Access Token
  2. Wallet Service validates Wallet Auth Token
  3. Policy Engine evaluates permissions
  4. Secure Execution Environment performs signing

​
Error Responses

All authentication errors follow a consistent format: 
{
  "error": {
    "code": "AUTH_INVALID_TOKEN",
    "message": "Access token expired"
  }
}
Common error codes:
  • AUTH_TOKEN_EXPIRED
  • AUTH_TOKEN_MISMATCH
  • WALLET_AUTH_REQUIRED
  • WALLET_AUTH_INVALID

​
Security Best Practices

  • Rotate Project API Keys regularly
  • Issue Access Tokens per request
  • Never reuse Wallet Auth Tokens
  • Log and audit all wallet write operations
  • Isolate token generation into a dedicated auth service

​
Summary

  • WaaS APIs are server‑only
  • Authentication is multi‑layered and request‑bound
  • Wallet operations require explicit wallet authorization This model is designed for:
  • WaaS platforms
  • Agentic wallets
  • Automated trading systems
  • Enterprise custody and compliance workflows Secure by design. Minimal by default.