Configuration

Complete reference for configuring the BWS X SDK.

XTwitterClient Constructor

Creates a new instance of the X/Twitter SDK client.

Description

The XTwitterClient constructor initializes the SDK with your configuration. It supports both environment variables and programmatic configuration. The SDK automatically loads configuration from environment variables if no config object is provided.

Parameters

Parameter	Type	Required	Description
config	XTwitterConfig	No	Configuration object. If omitted, loads from environment variables

XTwitterConfig Interface

Property	Type	Required	Default	Description
api	APIConfig	No	-	Twitter API configuration for posting and fallback
crawler	CrawlerConfig	No	-	Crawler configuration for cost-optimized scraping
proxy	ProxyConfig	No	-	Proxy configuration (Oxylabs, BrightData, custom)
mode	'api' | 'crawler' | 'hybrid'	No	'hybrid'	Operating mode
preferredMode	'api' | 'crawler'	No	'crawler'	Preferred mode for hybrid
fallbackOnRateLimit	boolean	No	true	Auto-fallback when rate limited
kolCriteria	KOLCriteriaConfig	No	-	KOL identification criteria
claude	ClaudeConfig	No	-	Claude AI configuration for KOL evaluation
logging	LoggingConfig	No	-	Logging configuration
retry	RetryConfig	No	-	Retry configuration
webhook	WebhookConfig	No	-	Webhook notification configuration

APIConfig Interface

Property	Type	Required	Description
accounts	APIAccount[]	Yes	Array of API account configurations
multiAccount	boolean	No	Enable multi-account rotation (default: false)
searchAccounts	APIAccount[]	No	Separate accounts for search operations

APIAccount Interface

Property	Type	Required	Description
name	string	Yes	Account identifier (e.g., 'main', 'search1')
apiKey	string	No*	Twitter API Key (Consumer Key)
apiSecret	string	No*	Twitter API Secret (Consumer Secret)
accessToken	string	No*	Twitter Access Token
accessSecret	string	No*	Twitter Access Secret
bearerToken	string	No*	Bearer Token (alternative to OAuth)
country	string	No	Country code for geo-targeted proxy

* Either OAuth credentials (apiKey + apiSecret + accessToken + accessSecret) OR bearerToken required

CrawlerConfig Interface

Property	Type	Required	Description
accounts	CrawlerAccount[]	Yes	Array of crawler account configurations
rotation	object	No	Account rotation settings
rotation.cooldownMinutes	number	No	Cooldown between uses (default: 15)
rotation.maxUsesPerHour	number	No	Max uses per hour per account (default: 20)

CrawlerAccount Interface

Property	Type	Required	Description
id	string	Yes	Account identifier
username	string	Yes	X/Twitter username (e.g., '@myaccount')
cookies	CrawlerCookies	Yes	Authentication cookies
cookies.auth_token	string	Yes	X auth_token cookie
cookies.ct0	string	Yes	X ct0 (CSRF token) cookie
cookies.guest_id	string	No	X guest_id cookie (optional)
country	string	No	Country code for geo-targeted proxy
status	'active' | 'suspended' | 'inactive'	No	Account status (default: 'active')

ProxyConfig Interface

Property	Type	Required	Description
enabled	boolean	No	Enable proxy (default: false, auto-enabled in CI/CD)
provider	'oxylabs' | 'brightdata' | 'custom'	No	Proxy provider (default: 'oxylabs')
host	string	No	Proxy host (default: 'pr.oxylabs.io')
port	number	No	Proxy port (default: 7777)
username	string	Yes*	Proxy username
password	string	Yes*	Proxy password
country	string	No	Default country code (default: 'us')
stickySession	boolean	No	Use sticky sessions (default: true)

* Required if enabled is true

WebhookConfig Interface

Property	Type	Required	Description
enabled	boolean	Yes	Enable webhook notifications
url	string	No*	Webhook endpoint URL
secret	string	No*	Secret key for HMAC signature verification
headers	Record<string, string>	No	Custom HTTP headers
events	WebhookEventType[]	No	Event types to send (default: all)
retries	object	No	Retry configuration
rateLimit	object	No	Rate limiting configuration
dedupe	object	No	Deduplication configuration
debug	boolean	No	Enable debug logging (default: false)

* Required if enabled is true

Returns

Type	Description
XTwitterClient	Initialized SDK client instance

Examples

Basic Usage (Environment Variables)

import { XTwitterClient } from '@blockchain-web-services/bws-x-sdk-node';

// Loads configuration from environment variables
const client = new XTwitterClient();

Programmatic Configuration

import { XTwitterClient } from '@blockchain-web-services/bws-x-sdk-node';

const client = new XTwitterClient({
  mode: 'hybrid',
  preferredMode: 'crawler',

  // API configuration (for posting and fallback)
  api: {
    accounts: [{
      name: 'main',
      apiKey: process.env.TWITTER_API_KEY!,
      apiSecret: process.env.TWITTER_API_SECRET!,
      accessToken: process.env.TWITTER_ACCESS_TOKEN!,
      accessSecret: process.env.TWITTER_ACCESS_SECRET!,
    }]
  },

  // Crawler configuration (primary for reading)
  crawler: {
    accounts: [{
      id: 'account1',
      username: '@mycrawleraccount',
      cookies: {
        auth_token: process.env.X_AUTH_TOKEN!,
        ct0: process.env.X_CT0!,
      }
    }],
    rotation: {
      cooldownMinutes: 15,
      maxUsesPerHour: 20,
    }
  },

  // Optional: Proxy configuration
  proxy: {
    enabled: true,
    provider: 'oxylabs',
    username: process.env.PROXY_USERNAME!,
    password: process.env.PROXY_PASSWORD!,
    country: 'us',
  },

  // Optional: Webhook notifications
  webhook: {
    enabled: true,
    url: process.env.WEBHOOK_URL!,
    secret: process.env.WEBHOOK_SECRET!,
    events: ['account_failure', 'api_rate_limit'],
  },

  // Optional: Logging
  logging: {
    level: 'info',
    silent: false,
  },
});

Environment Variables Configuration

Create a .env file:

# Operating Mode
SDK_OPTIONS='{"mode":"hybrid","preferredMode":"crawler"}'

# API Accounts
TWITTER_ACCOUNTS='[{
  "name": "main",
  "apiKey": "your-api-key",
  "apiSecret": "your-api-secret",
  "accessToken": "your-access-token",
  "accessSecret": "your-access-secret"
}]'

# Crawler Accounts
X_ACCOUNTS='[{
  "id": "account1",
  "username": "@mycrawleraccount",
  "cookies": {
    "auth_token": "your-auth-token",
    "ct0": "your-ct0-token"
  }
}]'

# Proxy Configuration
PROXY_CONFIG='{"enabled":true,"provider":"oxylabs","username":"user","password":"pass"}'

# Webhook Configuration
WEBHOOK_CONFIG='{"enabled":true,"url":"https://your-webhook.com","secret":"your-secret"}'

# Claude AI (for KOL evaluation)
ANTHROPIC_API_KEY=your-anthropic-api-key

Then simply:

import { XTwitterClient } from '@blockchain-web-services/bws-x-sdk-node';
import 'dotenv/config';

// Auto-loads from .env
const client = new XTwitterClient();

API-Only Mode

const client = new XTwitterClient({
  mode: 'api',
  api: {
    accounts: [{
      name: 'main',
      bearerToken: process.env.TWITTER_BEARER_TOKEN!,
    }]
  }
});

Crawler-Only Mode

const client = new XTwitterClient({
  mode: 'crawler',
  crawler: {
    accounts: [
      {
        id: 'account1',
        username: '@account1',
        cookies: { auth_token: '...', ct0: '...' }
      },
      {
        id: 'account2',
        username: '@account2',
        cookies: { auth_token: '...', ct0: '...' }
      }
    ],
    rotation: {
      cooldownMinutes: 10,
      maxUsesPerHour: 30,
    }
  },
  proxy: {
    enabled: true,
    provider: 'oxylabs',
    username: process.env.PROXY_USERNAME!,
    password: process.env.PROXY_PASSWORD!,
  }
});

Configuration Priority

The SDK loads configuration in the following priority order:

1. Constructor parameter - Highest priority
2. Environment variables - Loaded if no constructor parameter
3. Default values - Used for optional parameters

Environment Variable Format

All environment variables use JSON format:

• SDK_OPTIONS - General SDK options
• TWITTER_ACCOUNTS - API accounts array
• X_ACCOUNTS - Crawler accounts array
• PROXY_CONFIG - Proxy configuration
• WEBHOOK_CONFIG - Webhook configuration
• ANTHROPIC_API_KEY - Claude AI API key (plain string)

Best Practices

1. Use Environment Variables - Keep credentials out of code
2. Enable Webhooks - Monitor failures and rate limits in production
3. Configure Multiple Accounts - Improve reliability with account rotation
4. Use Hybrid Mode - Balance cost and reliability
5. Enable Proxy - Required for web scraping in production
6. Set Appropriate Cooldowns - Avoid rate limits with proper rotation

Related

• Operating Modes - Understanding different modes
• Proxy Configuration - Detailed proxy setup
• Webhook Notifications - Setting up webhooks
• Account Rotation - Managing multiple accounts