Chronos API Guide

v2.0.0 - Timeless Blockchain Transactions

Complete API reference for the Chronos Blockchain Adapter. REST API for seamless Web3 integration with JWT authentication, gasless transactions, smart accounts, and invisible blockchain UX.

Quick Start

1Register Client

Admin registers your app via POST /api/v1/auth/register with the master key.

2Get JWT Token

Exchange clientId + clientSecret for a JWT token.

3Add Headers

Include Authorization: Bearer and X-User-Id headers.

4Call APIs

Create wallets, mint tokens, transfer, check balance. All transactions are gasless.

Authentication

Authentication Flow
1

Client Registration (One-time, Admin only)

Admin calls POST /api/v1/auth/register with X-Admin-Key header to create API credentials.

2

Token Generation (On app start / token expiry)

Call POST /api/v1/auth/token with clientId and clientSecret to get a JWT.

3

API Calls (All subsequent requests)

Include Authorization: Bearer <token> and X-User-Id: <user_id> headers.

4

Token Refresh (When token expires)

On 401 with TOKEN_EXPIRED, call /api/v1/auth/token again with same credentials.

Required Headers
RequiredAuthorization

JWT Bearer token obtained from /api/v1/auth/token

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
RequiredX-User-Id

User identifier from your system (maps to a Smart Account)

X-User-Id: user_abc123
Admin OnlyX-Admin-Key

Master admin key for client management endpoints

X-Admin-Key: your_admin_master_key
Complete Authentication Example

Step 1: Register Client (Admin)

curl -X POST /api/v1/auth/register \
  -H "X-Admin-Key: your_admin_master_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My App Production",
    "scopes": ["wallet", "mint", "transfer", "claim"],
    "tier": "enterprise"
  }'

# Response:
{
  "success": true,
  "client": {
    "clientId": "client_abc123def456",
    "clientSecret": "sk_live_xxxxxxxxxx",
    "name": "My App Production",
    "scopes": ["wallet", "mint", "transfer", "claim"],
    "tier": "enterprise"
  }
}

Step 2: Get JWT Token

curl -X POST /api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "client_abc123def456",
    "clientSecret": "sk_live_xxxxxxxxxx"
  }'

# Response:
{
  "success": true,
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "scope": "wallet mint transfer claim"
}

Step 3: Make Authenticated API Call

curl -X POST /api/v1/wallet/create \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "X-User-Id: user_12345" \
  -H "Content-Type: application/json"

# Response:
{
  "success": true,
  "wallet": {
    "address": "0x1234567890abcdef...",
    "type": "smart_account"
  }
}

JWT Token Structure

Token Payload Claims

subClient ID (subject)
isschronos-adapter (issuer)
audblockchain-api (audience)
iatIssued at (Unix timestamp)
expExpires at (1 hour after iat)
jtiUnique token ID (replay prevention)
scopesPermitted API scopes
tierRate limit tier

Available Scopes

wallet

Create wallets, check balance, view transactions

mint

Check mint status, sign and execute mints

transfer

Transfer ERC-20 tokens between accounts

claim

Execute and verify token claims (payouts)

external

External sign-mint endpoint with CORS

Rate Limiting

Starter

100

requests / minute

Standard

500

requests / minute

Enterprise

2000

requests / minute

Error Codes

Authentication Errors

401
MISSING_AUTH

Authorization header not provided

401
INVALID_TOKEN

JWT signature invalid or malformed

401
TOKEN_EXPIRED

JWT has expired, refresh required

401
CLIENT_REVOKED

API client has been deactivated

401
INVALID_CREDENTIALS

Wrong clientId or clientSecret

API Errors

400
MISSING_USER_ID

X-User-Id header not provided

403
INSUFFICIENT_SCOPE

Token lacks required permission

409
RECEIPT_ALREADY_MINTED

Receipt ID already used for minting

429
RATE_LIMIT_EXCEEDED

Too many requests, slow down

500
USER_OPERATION_FAILED

Blockchain transaction failed

API Endpoints

Environment Variables

Authentication

JWT_SECRETRequired

Secret for signing JWT tokens (min 64 chars)

ADMIN_MASTER_KEYRequired

Master key for admin endpoints

CDP Platform

CDP_API_KEY_ID

CDP API key ID

CDP_API_KEY_SECRET

CDP API key secret

CDP_WALLET_SECRET

CDP wallet encryption secret

CDP_PAYMASTER_URL

Paymaster URL for gasless transactions