Getting Started

This guide walks you through installing the SDK, obtaining an API key, and making your first request.

Prerequisites

• Node.js 18+ (uses native fetch)
• A DobProtocol account at home.dobprotocol.com
• For pool creation: a Stellar wallet (Freighter, Albedo, xBull, or Lobstr)

Installation

npm install @dobprotocol/sdk

The package has zero runtime dependencies and works in both Node.js and browsers.

Get an API Key

SDK API keys allow your application to access DobProtocol from any domain.

1. Log in at home.dobprotocol.com
2. Go to Settings > SDK Keys
3. Click Create Key
4. Set a label, allowed domains, and scopes:
   • read -- Query pools, metrics, marketplace data
   • write -- Create pools, manage widgets, execute actions
5. Copy the key (starts with dob_sdk_). It's shown only once.

caution

Store your API key securely. Never expose it in client-side code that's committed to public repositories.

Domain Restrictions

Each key can be restricted to specific domains. Requests from unauthorized domains are rejected with 403 DOMAIN_NOT_ALLOWED.

Wildcard subdomains are supported:

• mysite.com -- Matches only mysite.com
• *.mysite.com -- Matches app.mysite.com, staging.mysite.com, etc.
• Empty list -- Allows all domains (not recommended for production)

Initialize the Client

import { DobProtocolClient } from '@dobprotocol/sdk';

const dob = new DobProtocolClient({
  apiKey: 'dob_sdk_...',     // Your SDK API key
  network: 'mainnet',        // 'testnet' or 'mainnet'
});

Configuration Options

Option	Type	Default	Description
apiKey	string	--	SDK API key for cross-origin access
network	'testnet' | 'mainnet'	'testnet'	Stellar network
baseUrl	string	'https://home.dobprotocol.com'	Backend API URL
token	string	--	Pre-existing JWT token
onTokenExpired	() => void	--	Callback when JWT expires

Your First Request

// No authentication needed for read operations
const pools = await dob.pools.getPublicPools({ limit: 5 });

for (const pool of pools) {
  console.log(`${pool.name} (${pool.ticker}) - APR: ${pool.estimated_apr}%`);
}

Authenticate with a Wallet

For write operations (creating pools, managing widgets), you need wallet authentication:

// 1. Get a challenge message
const { message } = await dob.auth.getNonce('GBDM6KRX...');

// 2. Sign with your wallet (Freighter example)
import { signMessage } from '@stellar/freighter-api';
const signature = await signMessage(message);

// 3. Sign in (token stored internally)
await dob.auth.signIn({
  wallet: 'GBDM6KRX...',
  signature,
  provider: 'freighter',
});

// Now you can use authenticated endpoints
const widget = await dob.widgets.create({
  name: 'My Widget',
  pool_address: 'CDXYZ...',
});

Network Configuration

The SDK provides network constants for wallet signing:

dob.networkId;         // 9 (testnet) or 10 (mainnet)
dob.networkPassphrase; // Network passphrase for transaction signing
dob.isAuthenticated;   // Whether a JWT token is set
dob.hasApiKey;         // Whether an API key is configured

Network Passphrases

Network	Passphrase
Testnet	Test SDF Network ; September 2015
Mainnet	Public Global Stellar Network ; September 2015

Error Handling

The SDK throws typed errors you can catch:

import {
  DobProtocolError,
  AuthenticationError,
  NotFoundError,
  TransactionError,
  ValidationError,
} from '@dobprotocol/sdk';

try {
  const pool = await dob.pools.getPool('invalid-address');
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log('Pool not found');
  } else if (err instanceof AuthenticationError) {
    console.log('Need to sign in first');
  }
}

Error Class	HTTP Status	When
AuthenticationError	401	Missing/expired token or API key
ValidationError	400	Invalid input parameters
NotFoundError	404	Resource doesn't exist
TransactionError	--	Stellar transaction failed or signing rejected
DobProtocolError	Any	Base class for all SDK errors

Rate Limits

SDK API keys are rate-limited to 120 requests per minute. The SDK returns rate limit headers:

Header	Description
X-RateLimit-Limit	Maximum requests per minute
X-RateLimit-Remaining	Requests remaining in current window
Retry-After	Seconds to wait (only on 429)

Next Steps

• SDK Reference -- Complete API documentation
• Examples -- Common integration patterns