xAPI

xapi CLI Skill

Use the xapi CLI to access real-time external data and services. xapi is an agent-friendly CLI — all output is JSON by default, making it easy to parse and chain.

Installation

xapi is available via npx (no install needed):

npx xapi-to 

Setup

Before calling any action, you need an API key:

# Register a new account (apiKey is saved automatically)
npx xapi-to register
Or set an existing key
npx xapi-to config set apiKey=
Verify connectivity
npx xapi-to config health

The API key is stored at ~/.xapi/config.json. You can also set it via XAPI_API_KEY env var.

Two types of actions

xapi offers two types of actions under a unified interface:

1. Capabilities (--source capability) — Built-in actions with known IDs (Twitter, crypto, AI, web search, news) 2. APIs (--source api) — Third-party API proxies, discovered via list, search, or services

All commands work with both types. Use --source capability or --source api to filter.

Workflow: Always GET before CALL

Critical rule: Before calling any action, always use get to understand the required parameters.

# 1. Find the right action
npx xapi-to search "twitter"
npx xapi-to search "token price" --source api
2. Read its schema to learn required parameters
npx xapi-to get twitter.tweet_detail
3. Call with correct parameters
npx xapi-to call twitter.tweet_detail --input '{"tweet_id":"1234567890"}'

Built-in Capabilities — Quick Reference

Always use --input with JSON for passing parameters.

Twitter / X

# Get user profile
npx xapi-to call twitter.user_by_screen_name --input '{"screen_name":"elonmusk"}'
Get user's tweets
npx xapi-to call twitter.user_tweets --input '{"user_id":"44196397","count":10}'
Get tweet details and replies
npx xapi-to call twitter.tweet_detail --input '{"tweet_id":"1234567890"}'
Get user's media posts
npx xapi-to call twitter.user_media --input '{"user_id":"44196397"}'
Get followers / following
npx xapi-to call twitter.followers --input '{"user_id":"44196397"}'
npx xapi-to call twitter.following --input '{"user_id":"44196397"}'
Search tweets
npx xapi-to call twitter.search_timeline --input '{"raw_query":"bitcoin","count":20}'
Get retweeters of a tweet
npx xapi-to call twitter.retweeters --input '{"tweet_id":"1234567890"}'
Batch get user profiles by usernames
npx xapi-to call twitter.user_by_screen_names --input '{"screen_names":["elonmusk","GlacierLuo"]}'

Note: Twitter user_id is a numeric ID. To get it, first call twitter.user_by_screen_name with the username, then extract user_id from the response.

Crypto

# Get token price and 24h change
npx xapi-to call crypto.token.price --input '{"token":"BTC","chain":"bsc"}'
Get token metadata
npx xapi-to call crypto.token.metadata --input '{"token":"ETH","chain":"eth"}'

Web & News Search

# Web search
npx xapi-to call web.search --input '{"q":"latest AI news"}'
Realtime web search with time filter
npx xapi-to call web.search.realtime --input '{"q":"breaking news","timeRange":"day"}'
Latest news
npx xapi-to call news.search.latest --input '{"q":"crypto regulation"}'

AI Text Processing

# Fast chat completion
npx xapi-to call ai.text.chat.fast --input '{"messages":[{"role":"user","content":"Explain quantum computing in one sentence"}]}'
Reasoning chat (more thorough)
npx xapi-to call ai.text.chat.reasoning --input '{"messages":[{"role":"user","content":"Analyze the pros and cons of microservices"}]}'
Summarize text
npx xapi-to call ai.text.summarize --input '{"text":""}'
Rewrite text
npx xapi-to call ai.text.rewrite --input '{"text":"","mode":"formalize"}'
Generate embeddings
npx xapi-to call ai.embedding.generate --input '{"input":"hello world"}'

Discovering Actions

# List all actions
npx xapi-to list
npx xapi-to list --source capability              # only built-in capabilities
npx xapi-to list --source api                     # only third-party APIs
npx xapi-to list --category Social --page-size 10 # filter by category
npx xapi-to list --service-id               # filter by specific service
Search by keyword
npx xapi-to search "twitter"
npx xapi-to search "token price" --source api
List all categories
npx xapi-to categories
npx xapi-to categories --source capability
List all services (supports --category, --page, --page-size)
npx xapi-to services
npx xapi-to services --category Social
Get action schema (shows required parameters)
npx xapi-to get twitter.tweet_detail
Some API actions have multiple HTTP methods on the same path
get returns an array when multiple methods exist
npx xapi-to get x-official.2_tweets
Filter by specific HTTP method
npx xapi-to get x-official.2_tweets --method POST
Call an action
npx xapi-to call twitter.tweet_detail --input '{"tweet_id":"1234567890"}'
Override HTTP method via --method flag (useful for multi-method endpoints)
npx xapi-to call x-official.2_tweets --method POST --input '{"body":{"text":"Hello!"}}'

Input Format

Always use --input with a JSON object to pass parameters:

# Simple parameters (capability-type actions)
npx xapi-to call twitter.user_by_screen_name --input '{"screen_name":"elonmusk"}'
Nested objects (API-type actions with pathParams/params/body)
npx xapi-to call serper.search --input '{"body":{"q":"hello world"}}'
When an action has multiple HTTP methods (e.g. GET and POST on /2/tweets),
use --method flag to specify which endpoint to call (defaults to GET)
npx xapi-to call x-official.2_tweets --method POST --input '{"body":{"text":"Hello world!"}}'
Alternatively, "method" inside --input also works (--method flag takes precedence)
npx xapi-to call x-official.2_tweets --input '{"method":"POST","body":{"text":"Hello world!"}}'

This ensures correct types (strings, numbers, booleans) are preserved.

OAuth (Twitter Write Access)

Some actions (e.g. posting tweets via x-official.2_tweets with POST) require OAuth authorization. Use oauth commands to bind your Twitter account to your API key.

# List available OAuth providers
npx xapi-to oauth providers
Bind Twitter OAuth to your API key (opens browser for authorization)
npx xapi-to oauth bind --provider twitter
Check current OAuth bindings
npx xapi-to oauth status
Remove an OAuth binding (get binding-id from oauth status)
npx xapi-to oauth unbind 

Agent workflow: If call fails with an OAuth/authorization error, run oauth status to check bindings, then oauth bind if needed.

Account Management

# Check balance
npx xapi-to balance
Top up account
npx xapi-to topup --method stripe --amount 10
npx xapi-to topup --method x402

Available API Services

Beyond built-in capabilities, xapi proxies several third-party API services including:

Use npx xapi-to services --format table to see the latest list.

Error Handling

Tips

Security

Before calling any action, you need an API key:

# Register a new account (apiKey is saved automatically)
npx xapi-to register
Or set an existing key
npx xapi-to config set apiKey=
Verify connectivity
npx xapi-to config health

The API key is stored at ~/.xapi/config.json. You can also set it via XAPI_API_KEY env var.