twitsh

CLI tool for the twit.sh X/Twitter API — access Twitter/X data via x402 (Base) or MPP (Tempo) micropayments. Pay per request in USDC — no API keys, no monthly subscriptions.

All available endpoints are documented at twit.sh.

Quick start

# 1. Create your wallet
npx twitsh start

# 2. Check your mode (default: x402 on Base)
npx twitsh mode

# 3. Fund it — send USDC to the printed address on the chain for your mode
#    x402: send USDC on Base
#    mpp:  send USDC on Tempo (no gas needed on either chain)

# 4. Check your balance
npx twitsh balance

# 5. See available endpoints (URLs reflect current mode)
npx twitsh endpoints

# 6. Fetch data
npx twitsh fetch "https://x402.twit.sh/users/by/username?username=elonmusk"

Commands

| Command | Description | |---|---| | npx twitsh start | Create wallet, print address for funding | | npx twitsh balance | Show wallet address and USDC balance | | npx twitsh mode [x402\|mpp] | Show or set payment mode | | npx twitsh endpoints | List all available endpoints with descriptions and prices | | npx twitsh fetch <url> | Fetch an endpoint — payment handled automatically | | npx twitsh login | Connect your X account (required for write endpoints) | | npx twitsh logout | Disconnect your X account | | npx twitsh whoami | Show which X account is connected |

Payment modes

twitsh supports two payment protocols. Switch anytime with npx twitsh mode:

| Mode | Chain | Base URL | Fund with | |---|---|---|---| | x402 (default) | Base | https://x402.twit.sh | USDC on Base | | mpp | Tempo | https://mpp.twit.sh | USDC on Tempo |

Both modes use the same wallet address. No ETH or gas tokens needed on either chain.

npx twitsh mode x402   # switch to x402 (Base)
npx twitsh mode mpp    # switch to MPP (Tempo)

Fetching data

Always run npx twitsh endpoints first to discover available routes. The URLs in the output already reflect your current mode.

# Get a user's profile and follower count
npx twitsh fetch "https://x402.twit.sh/users/by/username?username=elonmusk"

# Search tweets
npx twitsh fetch "https://x402.twit.sh/tweets/search?words=bitcoin&since=2025-01-01"

# Get a user's tweets
npx twitsh fetch "https://x402.twit.sh/tweets/user?username=elonmusk"

Response JSON is printed to stdout. Payment confirmation goes to stderr.

Write endpoints (POST/DELETE)

Some endpoints (post tweet, like, retweet, follow) require a connected X account:

# Connect once — opens a browser, log in to x.com
npx twitsh login

# Post a tweet
npx twitsh fetch "https://x402.twit.sh/tweets" --method POST --body '{"text":"hello"}'

# Like a tweet
npx twitsh fetch "https://x402.twit.sh/tweets/like?id=1234567890" --method POST

# Unlike
npx twitsh fetch "https://x402.twit.sh/tweets/like?id=1234567890" --method DELETE

Credentials are encrypted with your wallet key and stored at ~/.twitsh/credentials.json. They are never exposed to the terminal or any AI agent — injected silently per request.

Pricing

Calls cost $0.0025–$0.01 USDC per request. No subscription, no rate limits beyond your balance.

• x402 mode: pay on Base — send USDC on Base to your wallet address
• mpp mode: pay on Tempo — send USDC on Tempo to your wallet address

Run npx twitsh balance to see your address and current network.

Storage

All data is stored in ~/.twitsh/:

| File | Contents | |---|---| | wallet.json | EVM wallet (keep the private key secret) | | config.json | Current payment mode (x402 or mpp) | | credentials.json | Encrypted X session credentials | | openapi-x402.json | Cached endpoint list for x402 mode (refreshed hourly) | | openapi-mpp.json | Cached endpoint list for MPP mode (refreshed hourly) |

For AI agents

See skill.md for instructions on how to use twitsh as an AI agent skill.