Documentation

Three ways to connect

Local MCP for IDE agents, REST API with x402 micropayments for developers, 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

xbird auto-generates a wallet at ~/.config/xbird/wallet.json. Send ~$0.01 USDC on Base — enough for hundreds of API calls.

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 + price
Client
3Client
Sign payment
USDC
4xbird
Verify + execute
Twitter
5xbird
Return result
Client
Fully automatic with @x402/fetch. Sub-second latency.
Endpoints9 routes
GET/api/search?q=...&count=...$0.005
Search tweets
GET/api/tweet/:id$0.001
Get tweet by ID
GET/api/user/:handle$0.001
Get user profile
GET/api/user/:id/tweets$0.01
Get user's tweets
POST/api/tweet$0.01
Post a new tweet
POST/api/tweet/:id/reply$0.01
Reply to a tweet
POST/api/tweet/:id/like$0.01
Like a tweet
POST/api/tweet/:id/retweet$0.01
Retweet
POST/api/media/upload$0.05
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.