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.
# 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"| 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 |
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)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.
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 DELETECredentials 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.
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.
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) |
See skill.md for instructions on how to use twitsh as an AI agent skill.