BWS X SDK

Appearance

Cookie Setup Guide ​

Quick Start ​

Extract X/Twitter cookies for the BWS X SDK in just a few minutes:

bash
npx bws-x-setup-cookies

What This Tool Does ​

The Cookie Extraction Tool automates the process of obtaining X/Twitter authentication cookies needed for crawler mode. It:

  1. ✅ Opens X/Twitter in a real browser
  2. ✅ Waits for you to login
  3. ✅ Automatically extracts required cookies (auth_token, ct0, guest_id)
  4. ✅ Validates that cookies work
  5. ✅ Warns about expiration
  6. ✅ Supports multiple accounts
  7. ✅ Saves to .env file
  8. ✅ Exports to multiple formats (JSON, YAML, TypeScript)

Requirements ​

  • Node.js 18+
  • Playwright (already included in dependencies)
  • An X/Twitter account

Features ​

🔐 Automated Extraction ​

No manual copy-paste from DevTools. The tool extracts cookies automatically.

Tests cookies immediately after extraction to ensure they work:

  • Attempts to load your profile
  • Checks for authentication
  • Warns if validation fails

⏰ Expiration Warnings ​

X/Twitter auth tokens typically last 30 days. The tool:

  • Calculates expiration date
  • Warns if cookies are about to expire
  • Shows days remaining

👥 Multi-Account Support ​

Set up multiple accounts in one session:

  • Add as many accounts as needed
  • Each gets validated separately
  • All saved together

📤 Multiple Export Formats ​

Choose how to save your configuration:

.env Format (Default) ​

bash
X_ACCOUNTS=[{"id":"main","username":"@myuser","cookies":{"auth_token":"...","ct0":"..."}}]

JSON Format ​

json
{
  "extractedAt": "2025-12-18T17:00:00.000Z",
  "accounts": [
    {
      "id": "main",
      "username": "@myuser",
      "cookies": {
        "auth_token": "...",
        "ct0": "..."
      },
      "country": "us",
      "extractedAt": "2025-12-18T17:00:00.000Z",
      "expiresAt": "2026-01-17T17:00:00.000Z",
      "validated": true
    }
  ]
}

YAML Format ​

yaml
# X/Twitter Accounts
# Extracted: 2025-12-18T17:00:00.000Z

accounts:
  - id: "main"
    username: "@myuser"
    country: "us"
    cookies:
      auth_token: "..."
      ct0: "..."
    extractedAt: "2025-12-18T17:00:00.000Z"
    expiresAt: "2026-01-17T17:00:00.000Z"
    validated: true

TypeScript Format ​

typescript
/**
 * X/Twitter Account Configuration
 * Generated: 2025-12-18T17:00:00.000Z
 */

export interface CookieData {
  auth_token: string;
  ct0: string;
  guest_id?: string;
}

export interface AccountConfig {
  id: string;
  username: string;
  cookies: CookieData;
  country?: string;
}

export const accounts: AccountConfig[] = [
  {
    id: "main",
    username: "@myuser",
    cookies: {
      auth_token: "...",
      ct0: "..."
    },
    country: "us"
  }
];

Step-by-Step Usage ​

1. Run the Tool ​

bash
npx bws-x-setup-cookies

2. Follow the Prompts ​

The tool will guide you through:

╔═══════════════════════════════════════════════════════════╗
║                                                           ║
║        🍪  X/Twitter Cookie Extraction Tool  🍪         ║
║                                                           ║
║                  BWS X SDK v1.4.0                         ║
║                                                           ║
╚═══════════════════════════════════════════════════════════╝

ℹ️  This tool will:
  1. Open X/Twitter in a real browser
  2. Wait for you to login
  3. Automatically extract required cookies
  4. Validate that cookies work
  5. Check expiration and warn if needed
  6. Save to your .env file

⚠️  SECURITY WARNING:
  - Cookies provide full access to your X/Twitter account
  - Never share your .env file
  - Rotate cookies every 2-3 weeks
  - Use separate accounts for testing

Ready to begin? (Y/n):

3. Enter Account Details ​

═══════════════════════════════════════════════════════════
  NEW ACCOUNT SETUP
═══════════════════════════════════════════════════════════

Enter account ID (e.g., "main", "account1"): main
Enter X username (e.g., "@myusername"): @myuser
Enter country code for proxy (e.g., "us", "uk") or press Enter to skip: us

4. Login in the Browser ​

A browser window will open. Simply login to X/Twitter as you normally would.

ℹ️  Opening X/Twitter login page...

✋ Please login to X/Twitter in the opened browser...
⏳ Waiting for login to complete (timeout: 5 minutes)...

5. Automatic Extraction & Validation ​

Once logged in, the tool automatically:

  • Extracts cookies
  • Validates them
  • Checks expiration
✅ Login detected!

ℹ️  Extracting cookies...
✅ Cookies extracted successfully!

ℹ️  Validating cookies...
✅ Cookies validated successfully!

═══════════════════════════════════════════════════════════
  ACCOUNT SUMMARY
═══════════════════════════════════════════════════════════

  Account ID:  main
  Username:    @myuser
  Country:     us
  Validated:   ✅ Yes

  Cookies:
    auth_token:  abc123xyz456...
    ct0:         def789uvw012...

─────────────────────────────────────────────────────────
  EXPIRATION INFO
─────────────────────────────────────────────────────────
ℹ️  Cookies expire in approximately 30 days
ℹ️  Extracted: 12/18/2025, 5:00:00 PM
ℹ️  Expires: 1/17/2026, 5:00:00 PM

6. Add More Accounts (Optional) ​

Add another account? (y/N): y

Repeat the process for additional accounts.

7. Export Configuration ​

═══════════════════════════════════════════════════════════
  EXPORT OPTIONS
═══════════════════════════════════════════════════════════

Export to .env file? (Y/n): y
✅ Saved to /path/to/project/.env

Export to JSON file? (y/N): n
Export to YAML file? (y/N): n
Export to TypeScript file? (y/N): n

8. Done! ​

═══════════════════════════════════════════════════════════
  SETUP COMPLETE
═══════════════════════════════════════════════════════════

✅ Successfully configured 1 account(s):
  • main (@myuser) - ✅ Validated

ℹ️  Next steps:
  1. Test your setup: npm run test:integration
  2. Read the docs: https://blockchain-web-services.github.io/bws-x-sdk-node/
  3. Start coding with the SDK!

⚠️  Security reminders:
  • Never commit .env to git (already in .gitignore)
  • Rotate cookies every 2-3 weeks
  • Monitor account activity for suspicious logins
  • Use separate accounts for development and production

Troubleshooting ​

Browser Doesn't Open ​

Problem: Browser window doesn't appear

Solution:

  1. Make sure Playwright is installed: npm install
  2. Try running with: PWDEBUG=1 npx bws-x-setup-cookies
  3. Check for port conflicts (close other browsers)

Login Timeout ​

Problem: "Timeout waiting for login"

Solution:

  1. Login faster (5-minute timeout)
  2. Disable 2FA temporarily (or be ready to enter code quickly)
  3. Use a strong internet connection

Cookies Not Extracted ​

Problem: "Failed to extract required cookies"

Solution:

  1. Make sure you're fully logged in (see home timeline)
  2. Wait a few seconds after login before the tool checks
  3. Try logging out and back in
  4. Clear browser cache/cookies and try again

Validation Fails ​

Problem: "Validation failed: Redirected to login page"

Solution:

  1. Your account might be locked or suspended
  2. 2FA might have invalidated the session
  3. Try extracting cookies again
  4. Check if you can access X/Twitter normally in a regular browser

Cookies Expire Quickly ​

Problem: Cookies expire in less than 30 days

Solutions:

  1. This is normal if cookies were already old when extracted
  2. Always extract fresh cookies (login and extract immediately)
  3. Extract cookies from a browser session that hasn't been used in a while
  4. Some accounts have shorter session timeouts (business/developer accounts)

Security Best Practices ​

✅ DO ​

  • ✅ Use the tool to extract fresh cookies regularly (every 2-3 weeks)
  • ✅ Keep .env file in .gitignore (already configured)
  • ✅ Use separate X accounts for development and production
  • ✅ Monitor your X account for suspicious activity
  • ✅ Store exported JSON/YAML files securely (they contain credentials)
  • ✅ Use environment variables in production (not .env files)

❌ DON'T ​

  • ❌ Never commit .env to git
  • ❌ Never share your .env file
  • ❌ Never use production credentials in development
  • ❌ Never share exported JSON/YAML/TS files publicly
  • ❌ Never extract cookies on shared/public computers
  • ❌ Never use the same cookies on multiple machines simultaneously

Advanced Usage ​

Batch Setup with Multiple Accounts ​

Set up multiple accounts in one session:

bash
npx bws-x-setup-cookies
# Add first account
# When prompted "Add another account?", press Y
# Add second account
# Repeat as needed

All accounts will be saved together:

bash
X_ACCOUNTS=[
  {"id":"account1","username":"@user1","cookies":{...}},
  {"id":"account2","username":"@user2","cookies":{...}},
  {"id":"account3","username":"@user3","cookies":{...}}
]

Export to Multiple Formats ​

Export the same configuration to different formats for different use cases:

  1. .env - For local development with SDK
  2. JSON - For backup or sharing with team
  3. YAML - For configuration management
  4. TypeScript - For type-safe configuration in TS projects

Using Country-Specific Proxies ​

When prompted for country code, specify the proxy location:

Enter country code for proxy (e.g., "us", "uk") or press Enter to skip: us

This is useful when:

  • Using geo-targeted proxies (Oxylabs, BrightData)
  • Avoiding rate limits by distributing requests geographically
  • Testing from different regions

Programmatic Usage (Advanced) ​

Import and use the TypeScript export in your code:

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

const client = new XTwitterClient({
  crawler: {
    accounts: accounts
  }
});

X/Twitter auth tokens typically last 30 days. To maintain uninterrupted access:

Rotation Schedule ​

  1. Week 1-3: Use current cookies
  2. Week 4: Extract new cookies (before expiration)
  3. Week 5: Old cookies expire

Automation ​

Set a calendar reminder to run the tool every 3 weeks:

bash
# Every 3 weeks
npx bws-x-setup-cookies

Monitoring ​

The tool shows expiration info each time you run it:

ℹ️  Cookies expire in approximately 7 days
⚠️  Consider rotating cookies soon.

Integration with CI/CD ​

GitHub Actions ​

Store cookies as secrets and use in workflows:

  1. Extract cookies locally:

    bash
    npx bws-x-setup-cookies
# Export to JSON

  2. Add to GitHub Secrets:

    • Go to Repository → Settings → Secrets → Actions
    • Add secret: X_ACCOUNTS with the JSON value

  3. Use in workflow:

    yaml
    jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Setup cookies
        run: echo "X_ACCOUNTS=${{ secrets.X_ACCOUNTS }}" >> $GITHUB_ENV

Docker ​

Mount .env file when running containers:

bash
docker run -v $(pwd)/.env:/app/.env my-app

Or use environment variables:

bash
docker run -e X_ACCOUNTS="$X_ACCOUNTS" my-app

FAQ ​

Q: How often should I rotate cookies? ​

A: Every 2-3 weeks is recommended. The tool calculates expiration (typically 30 days) and warns when rotation is needed.

Q: Can I use the same cookies on multiple machines? ​

A: Not recommended. X/Twitter may flag this as suspicious activity and lock your account. Use separate accounts or extract fresh cookies for each machine.

Q: What happens if cookies expire? ​

A: API calls will fail with authentication errors. Simply run the tool again to extract fresh cookies.

Q: Is this safe? ​

A: Yes. The tool runs locally on your machine, no data is sent to external servers. However, treat your .env file like a password - never share it.

Q: Can I extract cookies manually instead? ​

A: Yes, but it's tedious. See Manual Cookie Extraction if needed.

Q: Does this work with 2FA enabled? ​

A: Yes, but you need to enter the 2FA code when logging in (within the 5-minute timeout).

Q: Can I extract cookies for multiple accounts at once? ​

A: Yes! The tool has a multi-account wizard. Just answer "y" when asked "Add another account?"

Next Steps ​

After extracting cookies:

  1. Test your setup:

    bash
    npm run test:integration

  2. Read the documentation:

  3. Start building:

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

const client = new XTwitterClient(); // Auto-loads from .env
const tweet = await client.getTweet('1234567890');

Support ​

Happy Crawling! 🚀

Released under the MIT License.

Copyright © 2024-present Blockchain Web Services