# twitr.sh — full tool reference

> Pay-per-call X/Twitter API for AI agents. No signup, no API keys — the wallet
> is the account. Every call is paid in USDC via x402 (Base, Solana) or MPP
> (Tempo) through the HTTP 402 flow. This is the full companion to https://twitr.sh/llms.txt.

## How payment works

1. POST any tool endpoint without credentials → HTTP 402 with an x402
   `PAYMENT-REQUIRED` header AND an MPP `WWW-Authenticate: Payment` header
   carrying the exact USDC price.
2. Pay the quoted amount with either protocol (x402: Base/Solana; MPP: Tempo).
3. Retry the identical request with the payment credential → 200 + data +
   settlement receipt. x402-aware clients do all three steps automatically.
4. Volume tools REQUIRE `resultsLimit` and bill per returned item. Extractions,
   monitors, writes and draws REQUIRE an `Idempotency-Key` header — a retry
   replays the original result instead of charging twice. 4xx/5xx responses are
   never charged.

## X/Twitter Read (`x_read`)

- Endpoint: POST https://twitr.sh/api/tools/x_read · page: https://twitr.sh/tools/x_read
- Price: $0.001200–$1.200000 USD per call (exact quote in the 402 challenge)
- Category: Social · kind: read

Read live X/Twitter data: look up a single tweet or user profile, batch-read up to 100 tweets or users at once, check whether one account follows another, fetch trending topics by region, extract a long-form article, or download tweet media. Pay per call in USDC — no API key, no signup; failed calls are never charged.

Usage: resource=get-tweet|get-user (id), batch-tweets|batch-users (ids array, ≤100), check-follower (source+target usernames), trends (optional woeid/count), article (tweet id), followers-you-know (id + mandatory resultsLimit), download-media (id or ids ≤50 — returns media file URLs on THIS origin; links live 7 days). Fixed-price per call/id except followers-you-know which is per-result.

Input schema (JSON Schema):
```json
{
  "type": "object",
  "properties": {
    "resource": {
      "type": "string",
      "enum": [
        "get-tweet",
        "get-user",
        "batch-tweets",
        "batch-users",
        "check-follower",
        "trends",
        "article",
        "followers-you-know",
        "download-media"
      ],
      "description": "Which read operation to run."
    },
    "id": {
      "type": "string",
      "description": "Tweet ID, user ID, or username (depends on resource)."
    },
    "ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "batch-tweets|batch-users: up to 100 tweet IDs or user IDs/usernames."
    },
    "source": {
      "type": "string",
      "description": "check-follower: source username."
    },
    "target": {
      "type": "string",
      "description": "check-follower: target username."
    },
    "woeid": {
      "type": "integer",
      "description": "trends: region WOEID (default 1 = worldwide)."
    },
    "count": {
      "type": "integer",
      "description": "trends: number of trends to return."
    },
    "resultsLimit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10000,
      "description": "Mandatory for followers-you-know: max results, billed per result."
    }
  },
  "required": [
    "resource"
  ],
  "allOf": [
    {
      "if": {
        "properties": {
          "resource": {
            "const": "followers-you-know"
          }
        }
      },
      "then": {
        "required": [
          "resultsLimit"
        ]
      }
    }
  ]
}
```

Example request body:
```json
{
  "resource": "get-tweet",
  "id": "2079908425904042170"
}
```

Example response:
```json
{
  "items": [
    {
      "id": "2079908425904042170",
      "text": "Ship early, ship often.",
      "authorUsername": "vercel",
      "likeCount": 4210,
      "retweetCount": 512,
      "createdAt": "2026-02-24T10:05:00.000Z"
    }
  ],
  "runId": "tw_example",
  "duration": 1,
  "payment": {
    "protocol": "x402",
    "amount": "0.001200",
    "currency": "USD"
  }
}
```

## X/Twitter Search (`x_search`)

- Endpoint: POST https://twitr.sh/api/tools/x_search · page: https://twitr.sh/tools/x_search
- Price: $0.001200–$1.200000 USD per call (exact quote in the 402 challenge)
- Category: Search · kind: read

Search X/Twitter tweets with the full operator set — keyword, exact phrase, from-user, language, date range, media type, minimum likes/retweets, verified-only — or search user profiles by keyword. Billed per tweet returned against your resultsLimit cap. Built for tracking what people say about a topic, brand, or ticker in real time.

Usage: type=search-tweets (default): q required, resultsLimit MANDATORY (billed per tweet returned). Supports the full filter set: fromUser, language, sinceDate/untilDate, mediaType, minFaves, verifiedOnly, exactPhrase, excludeWords, advancedQuery, and more. type=search-users: q required; returns one results page per call — follow report.next_cursor for the next page (each page is a separate paid call).

Input schema (JSON Schema):
```json
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "search-tweets",
        "search-users"
      ],
      "description": "Search tweets (default) or users."
    },
    "q": {
      "type": "string",
      "description": "Search query (X operator syntax supported for tweets)."
    },
    "resultsLimit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10000,
      "description": "search-tweets: MANDATORY max tweets returned, billed per tweet."
    },
    "cursor": {
      "type": "string",
      "description": "search-users: pagination cursor from a previous call's report.next_cursor."
    },
    "fromUser": {
      "type": "string"
    },
    "language": {
      "type": "string"
    },
    "sinceDate": {
      "type": "string",
      "description": "YYYY-MM-DD"
    },
    "untilDate": {
      "type": "string",
      "description": "YYYY-MM-DD"
    },
    "mediaType": {
      "type": "string",
      "enum": [
        "images",
        "videos",
        "gifs",
        "media"
      ]
    },
    "minFaves": {
      "type": "integer"
    },
    "minRetweets": {
      "type": "integer"
    },
    "minReplies": {
      "type": "integer"
    },
    "verifiedOnly": {
      "type": "boolean"
    },
    "exactPhrase": {
      "type": "string"
    },
    "excludeWords": {
      "type": "string"
    },
    "advancedQuery": {
      "type": "string",
      "description": "Raw X search operator string appended to q."
    }
  },
  "required": [
    "q"
  ],
  "allOf": [
    {
      "if": {
        "properties": {
          "type": {
            "const": "search-users"
          }
        }
      },
      "then": {},
      "else": {
        "required": [
          "resultsLimit"
        ]
      }
    }
  ]
}
```

Example request body:
```json
{
  "q": "artificial intelligence",
  "type": "search-tweets",
  "resultsLimit": 50,
  "language": "en",
  "minFaves": 100
}
```

Example response:
```json
{
  "items": [
    {
      "id": "1893710452812718080",
      "text": "This is a great thread, thanks for sharing.",
      "authorUsername": "elonmusk",
      "likeCount": 1180,
      "createdAt": "2026-02-24T10:05:00.000Z"
    }
  ],
  "runId": "tw_example",
  "duration": 2,
  "payment": {
    "protocol": "x402",
    "amount": "0.060000",
    "currency": "USD"
  }
}
```

## X/Twitter Timeline (`x_timeline`)

- Endpoint: POST https://twitr.sh/api/tools/x_timeline · page: https://twitr.sh/tools/x_timeline
- Price: $0.001200–$1.200000 USD per call (exact quote in the 402 challenge)
- Category: Social · kind: read

Fetch a user's X/Twitter timeline — their tweets, replies, likes, media posts, or mentions — plus follower and following lists, and per-tweet engagement lists (who replied, quoted, retweeted, or favorited). Billed per item returned. The building block for monitoring what an account posts or ranking accounts by activity.

Usage: kind selects the timeline: user-tweets|user-replies|user-likes|user-media|user-mentions|followers|following|verified-followers (id = user) or tweet-replies|tweet-quotes|tweet-thread|tweet-favoriters|tweet-retweeters (id = tweet). resultsLimit is MANDATORY — billed per item returned. Search-operator filters (fromUser, language, mediaType, minFaves, …) apply to tweet timelines.

Input schema (JSON Schema):
```json
{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "user-tweets",
        "user-replies",
        "user-likes",
        "user-media",
        "user-mentions",
        "followers",
        "following",
        "verified-followers",
        "tweet-replies",
        "tweet-quotes",
        "tweet-thread",
        "tweet-favoriters",
        "tweet-retweeters"
      ],
      "description": "Which timeline to fetch."
    },
    "id": {
      "type": "string",
      "description": "User ID/username or tweet ID (depends on kind)."
    },
    "resultsLimit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10000,
      "description": "MANDATORY: max items returned, billed per item."
    },
    "includeReplies": {
      "type": "boolean"
    },
    "includeParentTweet": {
      "type": "boolean"
    },
    "language": {
      "type": "string"
    },
    "mediaType": {
      "type": "string",
      "enum": [
        "images",
        "videos",
        "gifs",
        "media"
      ]
    },
    "minFaves": {
      "type": "integer"
    },
    "verifiedOnly": {
      "type": "boolean"
    }
  },
  "required": [
    "kind",
    "id",
    "resultsLimit"
  ]
}
```

Example request body:
```json
{
  "kind": "user-tweets",
  "id": "elonmusk",
  "resultsLimit": 100
}
```

Example response:
```json
{
  "items": [
    {
      "id": "1893710452812718080",
      "text": "This is a great thread, thanks for sharing.",
      "authorUsername": "elonmusk",
      "likeCount": 1180,
      "createdAt": "2026-02-24T10:05:00.000Z"
    }
  ],
  "runId": "tw_example",
  "duration": 3,
  "payment": {
    "protocol": "x402",
    "amount": "0.120000",
    "currency": "USD"
  }
}
```

## X/Twitter Lists (`x_lists`)

- Endpoint: POST https://twitr.sh/api/tools/x_lists · page: https://twitr.sh/tools/x_lists
- Price: $0.001200–$1.200000 USD per call (exact quote in the 402 challenge)
- Category: Social · kind: read

Read an X/Twitter List: its combined tweet timeline, its member roster, or its followers. Billed per item returned. Useful for following a curated set of accounts as one feed.

Usage: kind=tweets|members|followers; id = list ID. resultsLimit is MANDATORY — billed per item returned. tweets supports sinceTime/untilTime and includeReplies.

Input schema (JSON Schema):
```json
{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "tweets",
        "members",
        "followers"
      ],
      "description": "What to read from the list."
    },
    "id": {
      "type": "string",
      "description": "List ID."
    },
    "resultsLimit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10000,
      "description": "MANDATORY: max items returned, billed per item."
    },
    "sinceTime": {
      "type": "string"
    },
    "untilTime": {
      "type": "string"
    },
    "includeReplies": {
      "type": "boolean"
    }
  },
  "required": [
    "kind",
    "id",
    "resultsLimit"
  ]
}
```

Example request body:
```json
{
  "kind": "tweets",
  "id": "2079908425904042170",
  "resultsLimit": 100
}
```

Example response:
```json
{
  "items": [
    {
      "id": "1893710452812718080",
      "text": "This is a great thread, thanks for sharing.",
      "authorUsername": "elonmusk",
      "likeCount": 1180,
      "createdAt": "2026-02-24T10:05:00.000Z"
    }
  ],
  "runId": "tw_example",
  "duration": 2,
  "payment": {
    "protocol": "x402",
    "amount": "0.120000",
    "currency": "USD"
  }
}
```

## X/Twitter Communities (`x_communities`)

- Endpoint: POST https://twitr.sh/api/tools/x_communities · page: https://twitr.sh/tools/x_communities
- Price: $0.001200–$1.200000 USD per call (exact quote in the 402 challenge)
- Category: Social · kind: read

Read an X/Twitter Community: profile info, member and moderator rosters, the community's tweets, or keyword search inside the community. Fixed price for info; billed per item for rosters, tweets, and search.

Usage: kind=info (fixed price) or members|moderators|tweets|search (per-item — resultsLimit MANDATORY). id = community ID. search additionally requires q.

Input schema (JSON Schema):
```json
{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "info",
        "members",
        "moderators",
        "tweets",
        "search"
      ],
      "description": "What to read."
    },
    "id": {
      "type": "string",
      "description": "Community ID."
    },
    "q": {
      "type": "string",
      "description": "search: query within the community."
    },
    "resultsLimit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10000,
      "description": "Mandatory for members/moderators/tweets/search: max items, billed per item."
    }
  },
  "required": [
    "kind",
    "id"
  ],
  "allOf": [
    {
      "if": {
        "properties": {
          "kind": {
            "const": "search"
          }
        }
      },
      "then": {
        "required": [
          "q"
        ]
      }
    }
  ]
}
```

Example request body:
```json
{
  "kind": "info",
  "id": "2079908425904042170"
}
```

Example response:
```json
{
  "items": [
    {
      "id": "2079908425904042170",
      "name": "Build in Public",
      "memberCount": 48210,
      "description": "Founders sharing progress, metrics, and lessons."
    }
  ],
  "runId": "tw_example",
  "duration": 1,
  "payment": {
    "protocol": "x402",
    "amount": "0.001200",
    "currency": "USD"
  }
}
```

## X/Twitter Bulk Export (`x_extract`)

- Endpoint: POST https://twitr.sh/api/tools/x_extract · page: https://twitr.sh/tools/x_extract
- Price: $0.001200–$60.000000 USD per call (exact quote in the 402 challenge)
- Category: Intelligence · kind: extract

Bulk-export X/Twitter data as downloadable datasets: followers, following, repliers, quoters, reposters, likers, mentions, full threads, list and community members, spaces, or people/tweet search results — 23 extractors. Runs async: you get a claim check immediately and poll a free status URL for the download link. Billed per result.

Usage: tool selects the extractor (23 options). Provide the matching target: targetTweetId (reply/repost/quote/thread/article/favoriters extractors), targetUsername (follower/following/verified/post/mention/likes/media), targetCommunityId, targetListId, targetSpaceId, or searchQuery (people_search, tweet_search_extractor). resultsLimit is MANDATORY — billed per result (article_extractor bills 5× per result). Runs ASYNC: the response is a claim check {snapshot_id, status_url}; poll status_url (free, SIWX) until status=ready for the download link. Idempotency-Key header is required so retries reuse the same job.

Input schema (JSON Schema):
```json
{
  "type": "object",
  "properties": {
    "tool": {
      "type": "string",
      "enum": [
        "follower_explorer",
        "following_explorer",
        "verified_follower_explorer",
        "post_extractor",
        "reply_extractor",
        "repost_extractor",
        "quote_extractor",
        "thread_extractor",
        "article_extractor",
        "favoriters",
        "mention_extractor",
        "user_likes",
        "user_media",
        "community_extractor",
        "community_moderator_explorer",
        "community_post_extractor",
        "community_search",
        "list_member_extractor",
        "list_post_extractor",
        "list_follower_explorer",
        "space_explorer",
        "people_search",
        "tweet_search_extractor"
      ],
      "description": "Which extractor to run."
    },
    "resultsLimit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10000,
      "description": "MANDATORY: max results extracted, billed per result."
    },
    "targetTweetId": {
      "type": "string"
    },
    "targetUsername": {
      "type": "string"
    },
    "targetCommunityId": {
      "type": "string"
    },
    "targetListId": {
      "type": "string"
    },
    "targetSpaceId": {
      "type": "string"
    },
    "searchQuery": {
      "type": "string"
    },
    "language": {
      "type": "string"
    },
    "sinceDate": {
      "type": "string"
    },
    "untilDate": {
      "type": "string"
    },
    "mediaType": {
      "type": "string",
      "enum": [
        "images",
        "videos",
        "gifs",
        "media"
      ]
    },
    "minFaves": {
      "type": "integer"
    },
    "verifiedOnly": {
      "type": "boolean"
    }
  },
  "required": [
    "tool",
    "resultsLimit"
  ]
}
```

Example request body:
```json
{
  "tool": "follower_explorer",
  "targetUsername": "elonmusk",
  "resultsLimit": 500
}
```

Example response:
```json
{
  "snapshot_id": "sd_ex_a1b2c3d4e5f67890abcdef1234567890",
  "status": "pending",
  "status_url": "/api/snapshots/sd_ex_a1b2c3d4e5f67890abcdef1234567890",
  "message": "Extraction accepted — poll status_url until status='ready' to fetch the dataset.",
  "payment": {
    "protocol": "x402",
    "amount": "0.600000",
    "currency": "USD"
  }
}
```

## X/Twitter Monitor (`x_monitor`)

- Endpoint: POST https://twitr.sh/api/tools/x_monitor · page: https://twitr.sh/tools/x_monitor
- Price: $0.026400–$4.234800 USD per call (exact quote in the 402 challenge)
- Category: Intelligence · kind: monitor

Watch an X/Twitter account or keyword query in real time: new tweets, replies, quotes, mentions, hashtags, and profile changes, delivered to your agent by free polling or HMAC-signed webhooks. Prepaid by the hour with a hard stop at expiry — no open-ended billing. The way to track a brand, competitor, or topic without re-polling paid reads.

Usage: action=create needs username (account monitor, e.g. "vercel") OR query (keyword monitor, X search syntax, ≤512 chars), optional eventTypes — 21 available: post events (tweet.new, .reply, .retweet, .quote, .media, .link, .poll, .mention, .hashtag, .longform) for any monitor, plus profile-change events (profile.avatar/banner/name/username/bio/location/url/verified/protected/pinned_tweet/unavailable.changed) for ACCOUNT monitors only; default all applicable — and hours (1–168, default 1). action=extend needs monitorId + hours; hours append to the current expiry (total prepaid window ≤ 720h). Extend at least 5 minutes BEFORE expiry — extends inside the final 5 minutes are refused (unpaid) to keep settlement from racing the expiry teardown. PREPAID: the monitor stops and is removed at expires_at unless extended — no open-ended billing; early deletion does not refund remaining hours. Idempotency-Key header REQUIRED — retries replay the original monitor instead of re-charging (on the MCP door, retries are protected by single-use payment credentials instead). Pay with USDC on Base (x402) or Tempo (MPP); Solana is not offered for monitors (stateful resources need a recoverable owner wallet). After creation: poll events at /api/monitors/{id}/events (free — SIWX sign-in with the paying wallet; do NOT poll in a tight loop) or register an HTTPS webhook once at /api/webhooks to push signed events straight to your AI agent (Claude, OpenClaw, Hermes, or any endpoint) in real time. Manage monitors at /api/monitors (SIWX).

Input schema (JSON Schema):
```json
{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "create",
        "extend"
      ],
      "description": "Create a new monitor or extend an existing one."
    },
    "type": {
      "type": "string",
      "enum": [
        "account",
        "keyword"
      ],
      "description": "Monitor kind (create). Inferred from username/query when omitted."
    },
    "username": {
      "type": "string",
      "description": "X handle to monitor, without @ (create, type=account)."
    },
    "query": {
      "type": "string",
      "maxLength": 512,
      "description": "X search query to monitor (create, type=keyword)."
    },
    "eventTypes": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "tweet.new",
          "tweet.reply",
          "tweet.retweet",
          "tweet.quote",
          "tweet.media",
          "tweet.link",
          "tweet.poll",
          "tweet.mention",
          "tweet.hashtag",
          "tweet.longform",
          "profile.avatar.changed",
          "profile.banner.changed",
          "profile.name.changed",
          "profile.username.changed",
          "profile.bio.changed",
          "profile.location.changed",
          "profile.url.changed",
          "profile.verified.changed",
          "profile.protected.changed",
          "profile.pinned_tweet.changed",
          "profile.unavailable.changed"
        ]
      },
      "description": "Event types to receive (default: all applicable). Post events (tweet.*) work for any monitor; profile-change events (profile.*.changed) apply to ACCOUNT monitors only."
    },
    "hours": {
      "type": "integer",
      "minimum": 1,
      "maximum": 168,
      "description": "Prepaid hours to purchase (default 1)."
    },
    "monitorId": {
      "type": "string",
      "description": "Monitor to extend (extend only)."
    }
  },
  "required": [
    "action"
  ]
}
```

Example request body:
```json
{
  "action": "create",
  "username": "vercel",
  "eventTypes": [
    "tweet.new"
  ],
  "hours": 24
}
```

Example response:
```json
{
  "monitor": {
    "monitor_id": "mn_a1b2c3d4e5f6g7h8",
    "type": "account",
    "target": "vercel",
    "event_types": [
      "tweet.new"
    ],
    "status": "active",
    "expires_at": 1785000000000,
    "remaining_seconds": 86400,
    "hours_purchased": 24,
    "paid_total_usd": "0.605100"
  },
  "events_url": "/api/monitors/mn_a1b2c3d4e5f6g7h8/events",
  "manage_url": "/api/monitors/mn_a1b2c3d4e5f6g7h8",
  "message": "Monitor active for 24 hours.",
  "payment": {
    "protocol": "x402",
    "amount": "0.605100",
    "currency": "USD"
  }
}
```

## X/Twitter Giveaway Draws (`x_draws`)

- Endpoint: POST https://twitr.sh/api/tools/draws · page: https://twitr.sh/tools/draws
- Price: $0.002400–$84.001200 USD per call (exact quote in the 402 challenge)
- Category: Social · kind: read

Run a provably fair giveaway on X/Twitter: pick crypto-random winners from a tweet's replies, with retweet, follow, hashtag, keyword, minimum-follower, and account-age conditions. Fixed price set upfront from your estimated entry count.

Usage: tweetUrl required. Optional: winnerCount (default 1), backupCount, uniqueAuthorsOnly, mustRetweet, mustFollowUsername, filterMinFollowers, filterAccountAgeDays, filterLanguage, requiredHashtags/Keywords/Mentions. Pricing is fixed upfront from the estimatedEntries you set (default 1000, max 10000) — set it near the tweet's reply count; that number is enforced as a hard cap. Payment settles before the draw runs, so pay only when you intend to run it; a failed draw does not auto-refund (contact support). Idempotency-Key header required — retries with the same key replay the original result instead of re-charging.

Input schema (JSON Schema):
```json
{
  "type": "object",
  "properties": {
    "tweetUrl": {
      "type": "string",
      "description": "Full tweet URL (https://x.com/user/status/ID)."
    },
    "winnerCount": {
      "type": "integer",
      "minimum": 1
    },
    "backupCount": {
      "type": "integer"
    },
    "uniqueAuthorsOnly": {
      "type": "boolean"
    },
    "mustRetweet": {
      "type": "boolean"
    },
    "mustFollowUsername": {
      "type": "string"
    },
    "filterMinFollowers": {
      "type": "integer"
    },
    "filterAccountAgeDays": {
      "type": "integer"
    },
    "filterLanguage": {
      "type": "string"
    },
    "requiredHashtags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "requiredKeywords": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "requiredMentions": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "estimatedEntries": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10000,
      "description": "Expected replies inspected — drives the fixed price (default 1000)."
    }
  },
  "required": [
    "tweetUrl"
  ]
}
```

Example request body:
```json
{
  "tweetUrl": "https://x.com/vercel/status/2079908425904042170",
  "winnerCount": 3,
  "estimatedEntries": 500
}
```

Example response:
```json
{
  "items": [
    {
      "id": "a1b2c3d4e5f67890",
      "tweetId": "2079908425904042170",
      "totalEntries": 512,
      "validEntries": 498,
      "winners": [
        {
          "username": "builders_gonna",
          "tweetId": "1893710452812718080"
        }
      ]
    }
  ],
  "runId": "tw_example",
  "duration": 6,
  "payment": {
    "protocol": "x402",
    "amount": "0.601200",
    "currency": "USD"
  }
}
```

## X/Twitter Write (`x_write`)

- Endpoint: POST https://twitr.sh/api/tools/x_write · page: https://twitr.sh/tools/x_write
- Price: $0.006000–$0.036000 USD per call (exact quote in the 402 challenge)
- Category: Social · kind: write

Act on X/Twitter through an account you connect: post a tweet, reply, like, retweet, follow or unfollow, send a DM, delete a tweet, remove a follower, or upload media. Ownership is checked server-side — an agent can only write as a handle its own wallet connected.

Usage: PREREQUISITE: connect an X account first — POST /api/x-accounts/connect (free, SIWX) with {username, email, password, and totp_secret if the account has 2FA}; finish any email code via /api/x-accounts/confirm. Then reference the linked handle in `account`. Actions: post (text) | reply (text + reply_to_tweet_id) | like|unlike|retweet|unretweet|delete_tweet (target_tweet_id) | follow|unfollow (target_user_id — the NUMERIC user id, get it from x_read get-user) | remove_follower (target_user_id of the follower) | send_dm (target_user_id + text) | upload_media (media_url → returns media_id). You can only write as a handle THIS wallet connected (checked server-side; the input account is not trusted). Payment settles before the action runs and is non-refundable; a write may return status=pending_confirmation with an actionId to poll — do NOT resend. Idempotency-Key header is required so a retry replays the original result instead of acting twice.

Input schema (JSON Schema):
```json
{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "post",
        "reply",
        "like",
        "unlike",
        "retweet",
        "unretweet",
        "follow",
        "unfollow",
        "delete_tweet",
        "send_dm",
        "remove_follower",
        "upload_media"
      ],
      "description": "Which write to perform."
    },
    "account": {
      "type": "string",
      "description": "A connected X handle owned by this wallet (no @)."
    },
    "text": {
      "type": "string",
      "description": "post|reply|send_dm: the message body."
    },
    "reply_to_tweet_id": {
      "type": "string",
      "description": "reply: the tweet being replied to."
    },
    "target_tweet_id": {
      "type": "string",
      "description": "like|unlike|retweet|unretweet|delete_tweet: the target tweet ID."
    },
    "target_user_id": {
      "type": "string",
      "description": "follow|unfollow|send_dm|remove_follower: the numeric X user id of the target (not the @handle). Get it from x_read get-user."
    },
    "media_url": {
      "type": "string",
      "description": "upload_media: public URL of the file to upload; returns a media_id."
    },
    "media_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "send_dm: optional uploaded media ids to attach."
    },
    "community_id": {
      "type": "string",
      "description": "post: optional community to post into."
    },
    "is_note_tweet": {
      "type": "boolean",
      "description": "post: long-form note tweet."
    }
  },
  "required": [
    "action",
    "account"
  ]
}
```

Example request body:
```json
{
  "action": "post",
  "account": "myhandle",
  "text": "gm from my agent"
}
```

Example response:
```json
{
  "items": [
    {
      "id": "1893710452812718080",
      "url": "https://x.com/myhandle/status/1893710452812718080"
    }
  ],
  "runId": "tw_example",
  "duration": 1,
  "payment": {
    "protocol": "x402",
    "amount": "0.036000",
    "currency": "USD"
  }
}
```

## X/Twitter Inbox (`x_inbox`)

- Endpoint: POST https://twitr.sh/api/tools/x_inbox · page: https://twitr.sh/tools/x_inbox
- Price: $0.001200–$12.000000 USD per call (exact quote in the 402 challenge)
- Category: Social · kind: write

Read a connected X/Twitter account's private surfaces: bookmarks and bookmark folders, notifications, and DM history. Billed per item returned; readable only for handles this wallet connected.

Usage: PREREQUISITE: connect an X account (see /api/x-accounts/connect). Reads act AS that account, so you can only read the inbox of a handle THIS wallet connected. action=bookmarks (optional folderId) | bookmark_folders | notifications (optional type) | dm_history (target_user_id required). bookmarks/notifications/dm_history are billed per item — set resultsLimit (1–10000). account (the connected handle) is required.

Input schema (JSON Schema):
```json
{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "bookmarks",
        "bookmark_folders",
        "notifications",
        "dm_history"
      ],
      "description": "Which inbox read to run."
    },
    "account": {
      "type": "string",
      "description": "A connected X handle owned by this wallet (no @)."
    },
    "resultsLimit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10000,
      "description": "Max items to return (billed per item); ignored for bookmark_folders."
    },
    "folderId": {
      "type": "string",
      "description": "bookmarks: optional folder to read."
    },
    "type": {
      "type": "string",
      "description": "notifications: optional filter (e.g. mentions)."
    },
    "target_user_id": {
      "type": "string",
      "description": "dm_history: the other party's user id."
    },
    "maxId": {
      "type": "string",
      "description": "dm_history: paginate before this message id."
    }
  },
  "required": [
    "action",
    "account"
  ]
}
```

Example request body:
```json
{
  "action": "bookmarks",
  "account": "myhandle",
  "resultsLimit": 50
}
```

Example response:
```json
{
  "items": [
    {
      "id": "1893710452812718080",
      "text": "saved this thread",
      "createdAt": "2026-02-24T10:05:00.000Z"
    }
  ],
  "runId": "tw_example",
  "duration": 1,
  "payment": {
    "protocol": "x402",
    "amount": "0.060000",
    "currency": "USD"
  }
}
```

## X/Twitter Profile Editor (`x_profile`)

- Endpoint: POST https://twitr.sh/api/tools/x_profile · page: https://twitr.sh/tools/x_profile
- Price: $0.012000 USD per call (exact quote in the 402 challenge)
- Category: Social · kind: write

Edit a connected X/Twitter account's profile: display name, bio, location, website link, avatar image, and banner image. Acts only on handles this wallet connected.

Usage: PREREQUISITE: connect an X account. Acts as a handle THIS wallet owns. action=update_profile (any of name, description, location, url) | set_avatar (media_url) | set_banner (media_url). account required. Payment settles before the change; Idempotency-Key required.

Input schema (JSON Schema):
```json
{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "update_profile",
        "set_avatar",
        "set_banner"
      ],
      "description": "Which profile edit to make."
    },
    "account": {
      "type": "string",
      "description": "A connected X handle owned by this wallet (no @)."
    },
    "name": {
      "type": "string",
      "description": "update_profile: new display name."
    },
    "description": {
      "type": "string",
      "description": "update_profile: new bio."
    },
    "location": {
      "type": "string",
      "description": "update_profile: new location."
    },
    "url": {
      "type": "string",
      "description": "update_profile: new website URL."
    },
    "media_url": {
      "type": "string",
      "description": "set_avatar|set_banner: public image URL."
    }
  },
  "required": [
    "action",
    "account"
  ]
}
```

Example request body:
```json
{
  "action": "update_profile",
  "account": "myhandle",
  "description": "building in public 🛠️"
}
```

Example response:
```json
{
  "items": [
    {
      "updated": true
    }
  ],
  "runId": "tw_example",
  "duration": 1,
  "payment": {
    "protocol": "x402",
    "amount": "0.012000",
    "currency": "USD"
  }
}
```

## X/Twitter Community Manager (`x_community`)

- Endpoint: POST https://twitr.sh/api/tools/x_community · page: https://twitr.sh/tools/x_community
- Price: $0.012000–$0.036000 USD per call (exact quote in the 402 challenge)
- Category: Social · kind: write

Manage X/Twitter Communities as a connected account: create a new community, join or leave an existing one, or delete a community you own.

Usage: PREREQUISITE: connect an X account. Acts as a handle THIS wallet owns. action=create (name, optional description) | join|leave (community_id) | delete (community_id + community_name confirmation). account required. Payment settles before the action; Idempotency-Key required.

Input schema (JSON Schema):
```json
{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": [
        "create",
        "join",
        "leave",
        "delete"
      ],
      "description": "Which community action."
    },
    "account": {
      "type": "string",
      "description": "A connected X handle owned by this wallet (no @)."
    },
    "name": {
      "type": "string",
      "description": "create: the community name."
    },
    "description": {
      "type": "string",
      "description": "create: optional community description."
    },
    "community_id": {
      "type": "string",
      "description": "join|leave|delete: the community ID."
    },
    "community_name": {
      "type": "string",
      "description": "delete: the community name, as confirmation."
    }
  },
  "required": [
    "action",
    "account"
  ]
}
```

Example request body:
```json
{
  "action": "join",
  "account": "myhandle",
  "community_id": "1493446837214187523"
}
```

Example response:
```json
{
  "items": [
    {
      "id": "1493446837214187523",
      "joined": true
    }
  ],
  "runId": "tw_example",
  "duration": 1,
  "payment": {
    "protocol": "x402",
    "amount": "0.012000",
    "currency": "USD"
  }
}
```

## Trend Radar (`x_radar`)

- Endpoint: POST https://twitr.sh/api/tools/radar · page: https://twitr.sh/tools/radar
- Price: $0.001000 USD per call (exact quote in the 402 challenge)
- Category: Intelligence · kind: free

Trending topics and breaking stories across tech, dev, science, business, culture, politics, and entertainment — aggregated from multiple public sources with regional and time-window filters. Flat sub-cent price per call; the cheap first stop for what is happening right now.

Usage: Optional filters: category, region, hours (lookback), limit, source. Use report.next_cursor via `after` for the next page. Flat floor price per call.

Input schema (JSON Schema):
```json
{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": [
        "general",
        "tech",
        "dev",
        "science",
        "culture",
        "politics",
        "business",
        "entertainment"
      ],
      "description": "Topic category filter."
    },
    "region": {
      "type": "string"
    },
    "hours": {
      "type": "integer"
    },
    "limit": {
      "type": "integer"
    },
    "source": {
      "type": "string",
      "enum": [
        "github",
        "google_trends",
        "hacker_news",
        "polymarket",
        "reddit",
        "trustmrr",
        "wikipedia"
      ],
      "description": "Trend source filter."
    },
    "after": {
      "type": "string",
      "description": "Pagination cursor."
    }
  }
}
```

Example request body:
```json
{
  "category": "tech",
  "hours": 24,
  "limit": 20
}
```

Example response:
```json
{
  "items": [
    {
      "title": "AI agents start paying for their own API calls",
      "category": "tech",
      "score": 982,
      "url": "https://example.com/story"
    }
  ],
  "runId": "tw_example",
  "duration": 1,
  "payment": {
    "protocol": "x402",
    "amount": "0.001000",
    "currency": "USD"
  }
}
```

## AI Tweet Composer (`x_compose`)

- Endpoint: POST https://twitr.sh/api/tools/compose · page: https://twitr.sh/tools/compose
- Price: $0.001000 USD per call (exact quote in the 402 challenge)
- Category: Creator · kind: free

Draft tweets with AI: generate variants from a topic and goal, refine an existing draft, or score a draft for likely engagement — with tone, call-to-action, and style-matching options. Flat sub-cent price per step.

Usage: step=generate (topic + goal required; optional tone/styleUsername/additionalContext/callToAction/mediaType/hasLink/hasMedia), refine (draft required), or score (draft required). Returns text variants with scores and suggestions. Flat floor price per call.

Input schema (JSON Schema):
```json
{
  "type": "object",
  "properties": {
    "step": {
      "type": "string",
      "enum": [
        "generate",
        "refine",
        "score"
      ],
      "description": "Composer step."
    },
    "topic": {
      "type": "string"
    },
    "goal": {
      "type": "string"
    },
    "draft": {
      "type": "string"
    },
    "tone": {
      "type": "string"
    },
    "styleUsername": {
      "type": "string"
    },
    "additionalContext": {
      "type": "string"
    },
    "callToAction": {
      "type": "string"
    },
    "mediaType": {
      "type": "string"
    },
    "hasLink": {
      "type": "boolean"
    },
    "hasMedia": {
      "type": "boolean"
    }
  },
  "required": [
    "step"
  ]
}
```

Example request body:
```json
{
  "step": "generate",
  "topic": "pay-per-call APIs for AI agents",
  "goal": "announce launch",
  "tone": "punchy"
}
```

Example response:
```json
{
  "items": [
    {
      "text": "Your agent can now pay for its own API calls. No signup, no keys — just a wallet.",
      "score": 87,
      "suggestions": [
        "Add a concrete number for credibility"
      ]
    }
  ],
  "runId": "tw_example",
  "duration": 2,
  "payment": {
    "protocol": "x402",
    "amount": "0.001000",
    "currency": "USD"
  }
}
```

## Other interfaces

- Service index: https://twitr.sh/llms.txt
- Agent skill: https://twitr.sh/skill.md
- OpenAPI 3.1 + payment discovery: https://twitr.sh/openapi.json
- MCP (JSON-RPC, payment-gated): POST https://twitr.sh/api/mcp
- Human docs: https://twitr.sh/docs