Documentation

Three ways to connect

Local MCP for IDE agents, REST API with x402 dual-rail micropayments (Base + X Layer), or ACP marketplace for agent-to-agent commerce.

Quick Start
1
Run xbird login

Auto-detects your Twitter session from the browser. Encrypts credentials into a self-contained stateless token locally — nothing is sent to the server.

2
Fund your wallet

Default: auto-generated wallet at ~/.config/xbird/wallet.json — send ~$0.01 USDC on Base. Optional: OKX Agentic Wallet (onchainos) for Base USDC or X Layer USDT — set XBIRD_PAYMENT_MODE=agentic.

3
Make your first request

Use @x402/fetch with your xbird_sk_ token in the X-Encryption-Key header. The server decrypts per-request, stores nothing.

AuthenticationTwo modes
SimplePer-request headers

Pass Twitter cookies directly as request headers. Best for quick testing and one-off calls.

headers: {
  "X-Twitter-Auth-Token": "<auth_token>",
  "X-Twitter-CT0": "<ct0>"
}
ProductionStateless token

Run xbird login once. Credentials are AES-256-GCM encrypted into a self-contained token. Server stores nothing — fully stateless.

// Generate (once, local)
$ npx @checkra1n/xbird login
 
// Use (every request)
headers: { "X-Encryption-Key": "<token>" }
// token = xbird_sk_<key>.<ciphertext>.<iv>
x402 Payment Flow
1Client
API request
xbird
2xbird
HTTP 402 + dual accepts
Client
3Client
Sign payment
Base / X Layer
4xbird
Verify + execute
Twitter
5xbird
Return result
Client
Automatic with @x402/fetch (Base) or onchainos Agentic Wallet (Base / X Layer).Server offers eip155:8453 (USDC) and eip155:196 (USDT)
Endpoints9 routes
GET/api/search?q=...&count=20$0.05
Search tweets (post_read × count)
GET/api/tweet/:id$0.0025
Get tweet by ID (1 unit)
GET/api/user/:handle$0.005
Get user profile
GET/api/user/:id/tweets?count=20$0.10
User tweets (user_read × count)
POST/api/tweet$0.0075
Post a new tweet
POST/api/tweet/:id/reply$0.0075
Reply to a tweet
POST/api/tweet/:id/like$0.0075
Like a tweet
POST/api/tweet/:id/retweet$0.0075
Retweet
POST/api/media/upload$0.005
Upload media
TypeScript example
import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
 
// 1. Setup x402 payment (wallet from ~/.config/xbird/wallet.json)
const account = privateKeyToAccount("0x...");
const client = new x402Client();
registerExactEvmScheme(client, { signer: account });
const payFetch = wrapFetchWithPayment(fetch, client);
 
// 2. Use stateless token from `xbird login`
const res = await payFetch(
  "https://xbirdapi.up.railway.app/api/search?q=AI+agents&count=20",
  {
    headers: {
      // Self-contained token: xbird_sk_<key>.<ciphertext>.<iv>
      "X-Encryption-Key": process.env.XBIRD_TOKEN,
    },
  }
);
const { data, cursor } = await res.json();
Stateless Token Flow
1CLI
Auto-detect cookies
Browser
2CLI
AES-256-GCM encrypt
Local
3CLI
Save xbird_sk_ token
Local
4You
Request + token
Server
5Server
Decrypt, execute, discard
Twitter
Zero server storage. Token is self-contained — server decrypts per-request.