# Xbird Rest Api

> Use when building backend services, autonomous agents, or programmatic integrations that need Twitter/X data via HTTP. Triggers: REST API, x402, USDC payment, stateless token, encrypted credentials, per-request headers, Base mainnet, micropayment.

- **Type:** Skill
- **Install:** `agentstack add skill-checkra1neth-xbird-skill-xbird-rest-api`
- **Verified:** Pending review
- **Seller:** [checkra1neth](https://agentstack.voostack.com/s/checkra1neth)
- **Installs:** 0
- **Category:** [Finance & Payments](https://agentstack.voostack.com/c/finance-and-payments)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [checkra1neth](https://github.com/checkra1neth)
- **Source:** https://github.com/checkra1neth/xbird-skill/tree/main/skills/xbird-rest-api

## Install

```sh
agentstack add skill-checkra1neth-xbird-skill-xbird-rest-api
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# xbird REST API — Twitter/X with x402 Micropayments

Pay-per-request Twitter/X API. Every call is metered via x402 (USDC on Base). Fully stateless — the server stores nothing. No database, no stored credentials.

## When to Use

- Backend services or scripts that need Twitter data via HTTP
- Autonomous agents without MCP support
- Any language/framework (not just TypeScript)
- Direct programmatic integrations

**Don't use when:** Running inside Claude Code / Cursor / Windsurf (use MCP instead), or operating on Virtuals marketplace (use ACP instead).

## Setup

```bash
# 1. Install xbird and generate a stateless token
npx @checkra1n/xbird login

# 2. Fund the wallet shown in login output with USDC on Base
```

The `login` command auto-detects your browser cookies, encrypts them into a self-contained stateless token locally, and saves it. Nothing is sent to the server.

## Authentication

**Mode 1 — Stateless token** (recommended): run `xbird login` to generate a token, then pass it via `X-Encryption-Key` header. The token is self-contained — the server decrypts per-request and stores nothing.

**Mode 2 — Per-request headers** (simplest): pass `X-Twitter-Auth-Token` + `X-Twitter-CT0` on every request.

## Complete Example

```typescript
import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const client = new x402Client();
registerExactEvmScheme(client, { signer: account });
const paymentFetch = wrapFetchWithPayment(fetch, client);

const SERVER = "https://xbirdapi.up.railway.app";

// Search with stateless token
const res = await paymentFetch(
  `${SERVER}/api/search?q=${encodeURIComponent("AI agents")}&count=10`,
  {
    headers: {
      "X-Encryption-Key": process.env.XBIRD_TOKEN!,  // from xbird login
    },
  },
);
const { data, cursor } = await res.json();
```

## Quick Reference

```
Server:   https://xbirdapi.up.railway.app
Response: { data: {...} } or { data: [...], cursor: "..." }
Error:    { error: "message" }
Undo:     POST to engage, DELETE to undo (like, retweet, bookmark)
Bulk:     Resolve handle → numeric ID via GET /api/users/:handle first
Pricing:  Read $0.001 | Search $0.005 | Bulk/Write $0.01 | Media $0.05
```

Full endpoint list: see `endpoints.md`. Payment flow details: see `x402-flow.md`.

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Payment error "invalid_payload" | Wallet address == server payTo. EIP-3009 rejects self-payment. Use a different wallet. |
| Using handle for bulk endpoints | `/api/users/:id/tweets` needs numeric ID. Call `GET /api/users/:handle` first. |
| Empty USDC balance | Fund wallet with USDC on Base mainnet (`eip155:8453`). $0.10 = hundreds of calls. |
| Sending only one credential header | Both `X-Twitter-Auth-Token` AND `X-Twitter-CT0` required, or use `X-Encryption-Key` with stateless token. |
| Invalid token format | Token must be `xbird_sk_..`. Re-run `npx @checkra1n/xbird login` to generate. |
| Rate limit 429 | Twitter rate limit. Wait 1-2 minutes, retry. |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [checkra1neth](https://github.com/checkra1neth)
- **Source:** [checkra1neth/xbird-skill](https://github.com/checkra1neth/xbird-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-checkra1neth-xbird-skill-xbird-rest-api
- Seller: https://agentstack.voostack.com/s/checkra1neth
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.