Configuration

The Bloque SDK is configured when you instantiate it. This page covers all available configuration options and their usage.

Basic Configuration

import { SDK } from '@bloque/sdk';

const sdk = new SDK({
  auth: { type: 'apiKey', apiKey: process.env.BLOQUE_API_KEY },
  origin: 'your-origin',
  mode: 'production'
});

BloqueSDKConfig Reference

The SDK accepts a configuration object of type BloqueSDKConfig with the following options:

Authentication (`auth`)

auth

AuthStrategy

required

Authentication strategy used by the SDK.

Show properties

type

'apiKey' | 'jwt'

required

Authentication type.

apiKey: Backend platforms (node, bun, deno)
jwt: Frontend platforms (browser, react-native)

apiKey

string

Private API key (required when type is 'apiKey')

const sdk = new SDK({
  auth: {
    type: 'apiKey',
    apiKey: process.env.BLOQUE_API_KEY
  },
  origin: 'your-origin'
});

Origin (`origin`)

origin

string

Origin identifier for scoping requests and operations to a specific origin within the Bloque platform.

Required for API key authentication
Optional for JWT authentication (resolved during authenticate())

const sdk = new SDK({
  auth: { type: 'apiKey', apiKey: 'key_...' },
  origin: 'my-app' // Required for apiKey auth
});

Platform (`platform`)

platform

Platform

default:"node"

Platform where the SDK is executed. Determines runtime environment and capabilities.Options: 'node' | 'bun' | 'deno' | 'browser' | 'react-native'

const sdk = new SDK({
  platform: 'browser',
  auth: { type: 'jwt' }
});

See Platform Support for detailed information about each platform.

Environment Mode (`mode`)

mode

'production' | 'sandbox'

default:"production"

SDK operation mode.

production: Live endpoints and real data
sandbox: Isolated endpoints and mock data for testing

Note: Cannot be used with custom baseUrl

const sdk = new SDK({
  mode: 'production',
  auth: { type: 'apiKey', apiKey: 'key_...' },
  origin: 'my-app'
});

Base URL (`baseUrl`)

baseUrl

string

Custom base URL for the SDK API endpoints.

Use for self-hosted or custom Bloque instances
Cannot be specified with mode
Overrides default production/sandbox URLs

const sdk = new SDK({
  baseUrl: 'https://api.custom-bloque.com',
  auth: { type: 'apiKey', apiKey: 'key_...' },
  origin: 'my-app'
});

Token Storage (`tokenStorage`)

tokenStorage

TokenStorage

JWT token storage strategy for client-side platforms.

Browser: Optional (uses httpOnly cookies with credentials: 'include')
React Native: Required for JWT auth
Backend platforms: Not used

TokenStorage Interface:

interface TokenStorage {
  get(): string | null;
  set(token: string): void;
  clear(): void;
}

Browser (localStorage)
React Native (AsyncStorage)
In-Memory

const sdk = new SDK({
  platform: 'browser',
  auth: { type: 'jwt' },
  tokenStorage: {
    get: () => localStorage.getItem('bloque_token'),
    set: (token) => localStorage.setItem('bloque_token', token),
    clear: () => localStorage.removeItem('bloque_token')
  }
});

localStorage is vulnerable to XSS attacks. Use httpOnly cookies for production.

import AsyncStorage from '@react-native-async-storage/async-storage';

const sdk = new SDK({
  platform: 'react-native',
  auth: { type: 'jwt' },
  tokenStorage: {
    get: () => AsyncStorage.getItem('bloque_token'),
    set: (token) => AsyncStorage.setItem('bloque_token', token),
    clear: () => AsyncStorage.removeItem('bloque_token')
  }
});

let token: string | null = null;

const sdk = new SDK({
  platform: 'browser',
  auth: { type: 'jwt' },
  tokenStorage: {
    get: () => token,
    set: (t) => { token = t; },
    clear: () => { token = null; }
  }
});

Most secure against XSS, but token is lost on page refresh.

Timeout (`timeout`)

timeout

number

default:30000

Default timeout for HTTP requests in milliseconds.

When exceeded, throws BloqueTimeoutError
Can be overridden per-request using RequestOptions.timeout
Set to 0 to disable timeouts globally (not recommended)

const sdk = new SDK({
  auth: { type: 'apiKey', apiKey: 'key_...' },
  origin: 'my-app',
  timeout: 60000 // 60 seconds
});

Retry Configuration (`retry`)

retry

object

Automatic retry configuration for failed requests.

Show properties

enabled

boolean

default:true

Enable automatic retries

maxRetries

number

default:3

Maximum number of retry attempts

initialDelay

number

default:1000

Initial delay in milliseconds before first retry. Uses exponential backoff: delay * (2 ^ attempt)

maxDelay

number

default:30000

Maximum delay in milliseconds between retries

The SDK automatically retries:

429 Too Many Requests (respects Retry-After header)
503 Service Unavailable
Network errors (timeouts, connection failures)

const sdk = new SDK({
  auth: { type: 'apiKey', apiKey: 'key_...' },
  origin: 'my-app',
  // retry is enabled by default with these values:
  retry: {
    enabled: true,
    maxRetries: 3,
    initialDelay: 1000,
    maxDelay: 30000
  }
});

Configuration Examples

Production Backend Service

Node.js API

import { SDK } from '@bloque/sdk';

const sdk = new SDK({
  auth: {
    type: 'apiKey',
    apiKey: process.env.BLOQUE_API_KEY
  },
  origin: process.env.BLOQUE_ORIGIN,
  mode: 'production',
  timeout: 30000,
  retry: {
    enabled: true,
    maxRetries: 3
  }
});

Frontend Web Application

Browser with httpOnly Cookies

import { SDK } from '@bloque/sdk';

const sdk = new SDK({
  platform: 'browser',
  auth: { type: 'jwt' },
  origin: 'my-web-app',
  mode: 'production'
  // tokenStorage not needed - uses httpOnly cookies
});

Mobile Application

React Native

import { SDK } from '@bloque/sdk';
import AsyncStorage from '@react-native-async-storage/async-storage';

const sdk = new SDK({
  platform: 'react-native',
  auth: { type: 'jwt' },
  origin: 'my-mobile-app',
  mode: 'production',
  tokenStorage: {
    get: () => AsyncStorage.getItem('bloque_token'),
    set: (token) => AsyncStorage.setItem('bloque_token', token),
    clear: () => AsyncStorage.removeItem('bloque_token')
  },
  timeout: 45000 // Mobile networks may be slower
});

Development/Testing

Sandbox Mode

import { SDK } from '@bloque/sdk';

const sdk = new SDK({
  auth: {
    type: 'apiKey',
    apiKey: process.env.BLOQUE_TEST_API_KEY
  },
  origin: 'test-origin',
  mode: 'sandbox',
  timeout: 60000, // Longer timeout for debugging
  retry: {
    enabled: false // Disable retries to see errors immediately
  }
});

Configuration Validation

The SDK validates configuration at initialization and throws BloqueConfigError for invalid configurations:

Invalid Configurations

// Error: Cannot specify both mode and baseUrl
const sdk = new SDK({
  mode: 'production',
  baseUrl: 'https://custom.com', // ❌
  auth: { type: 'apiKey', apiKey: 'key_...' }
});

// Error: JWT auth required for browser platform
const sdk = new SDK({
  platform: 'browser',
  auth: { type: 'apiKey', apiKey: 'key_...' } // ❌
});

// Error: tokenStorage required for react-native with JWT
const sdk = new SDK({
  platform: 'react-native',
  auth: { type: 'jwt' }
  // ❌ Missing tokenStorage
});

TypeScript Types

The configuration is fully typed. Import types for better IDE support:

import type { BloqueSDKConfig, Platform, Mode, TokenStorage } from '@bloque/sdk-core';

const config: BloqueSDKConfig = {
  auth: { type: 'apiKey', apiKey: 'key_...' },
  origin: 'my-app',
  platform: 'node',
  mode: 'production'
};

Next Steps

Platform Support

Learn about platform-specific features

Error Handling

Handle configuration and runtime errors

Authentication

Connect and authenticate users

URNs

Understand Bloque’s URN system

Get Started

Core Concepts

Accounts

Swap & Exchange

Identity & Compliance

Organizations

Guides

Basic Configuration

BloqueSDKConfig Reference

Authentication (`auth`)

Origin (`origin`)

Platform (`platform`)

Environment Mode (`mode`)

Base URL (`baseUrl`)

Token Storage (`tokenStorage`)

Timeout (`timeout`)

Retry Configuration (`retry`)

Configuration Examples

Production Backend Service

Frontend Web Application

Mobile Application

Development/Testing

Configuration Validation

TypeScript Types

Next Steps

Platform Support

Error Handling

Authentication

URNs

Build docs developers (and LLMs) love

Get Started

Core Concepts

Accounts

Swap & Exchange

Identity & Compliance

Organizations

Guides

​Basic Configuration

​BloqueSDKConfig Reference

​Authentication (auth)

​Origin (origin)

​Platform (platform)

​Environment Mode (mode)

​Base URL (baseUrl)

​Token Storage (tokenStorage)

​Timeout (timeout)

​Retry Configuration (retry)

​Configuration Examples

​Production Backend Service

​Frontend Web Application

​Mobile Application

​Development/Testing

​Configuration Validation

​TypeScript Types

​Next Steps

Platform Support

Error Handling

Authentication

URNs

Build docs developers (and LLMs) love

Basic Configuration

BloqueSDKConfig Reference

Authentication (`auth`)

Origin (`origin`)

Platform (`platform`)

Environment Mode (`mode`)

Base URL (`baseUrl`)

Token Storage (`tokenStorage`)

Timeout (`timeout`)

Retry Configuration (`retry`)

Configuration Examples

Production Backend Service

Frontend Web Application

Mobile Application

Development/Testing

Configuration Validation

TypeScript Types

Next Steps