twitr-sh Intelligence API

openapi: 3.2.0
info:
  title: twitr.sh Intelligence API
  version: 1.0.0
  contact:
    email: support@twitr.sh
  description: 'Pay-per-call X/Twitter data API for AI agents: single-object reads, tweet/user search, timelines, lists, communities, bulk extractions (23 tools, async with downloadable datasets), real-time account/keyword monitors (prepaid hours; events via free polling or signed webhooks), giveaway draws, trend radar, and an AI tweet composer. No signup — the wallet is the account; an optional API key (Authorization: Bearer) spends a prepaid card balance instead. Payment via x402 v2 (USDC on Base/Solana) and MPP (USDC on Tempo). Per-result reads use x402 upto on Base only: the 402 quotes a maximum, empty results cost $0, and non-empty calls have a $0.0024 minimum. Volume tools bill per returned item against a mandatory resultsLimit; extractions and monitors settle before dispatch.'
  x-guidance: 'All tools are POST /api/tools/{tool} and return 402 with payment options on first call (Base upto only for per-result reads; fixed operations can offer exact x402 and MPP); pay and retry to receive data. Volume tools (x_search, x_timeline, x_lists, x_communities non-info kinds, followers-you-know) REQUIRE resultsLimit (integer 1–10000) — you are billed per returned item and the cap is enforced upstream. x_extract is async: it returns {snapshot_id, status_url}; poll GET /api/snapshots/{id} (free, SIWX) until status=ready for a download_url. x_monitor is PREPAID by the hour: it stops at expires_at unless extended — extend early, never expect refunds on deletion; events flow to GET /api/monitors/{id}/events (free, SIWX) or your registered webhook (/api/webhooks, signed with X-Twitr-Signature). draws, x_extract and x_monitor require an Idempotency-Key header. radar + compose are flat floor-priced. GET /api/snapshots and GET /api/monitors (SIWX) list the wallet''s history for free. Errors are RFC 9457 Problem bodies (components.schemas.Problem) with machine-actionable `retryable` and `hint` fields — retryable:true means retry the SAME request unchanged after a backoff; x402 reads settle after success; prepaid operations can fail after payment. Alternative to per-call payment: send `Authorization: Bearer tw_live_…` (an API key created at /dashboard) and each call is charged to that account''s prepaid USD balance at the same prices — per-result reads charge only returned records; the free SIWX endpoints accept the same key.'
servers:
- url: https://twitr.sh
tags:
- name: Intelligence
paths:
  /api/tools/x_extract:
    post:
      operationId: x_extract
      summary: X/Twitter Bulk Export
      description: '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.'
      tags:
      - Intelligence
      parameters:
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
        description: Unique key per logical action. A retry with the same key replays the original result (10-minute window) instead of acting or charging twice.
      x-guidance: '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.'
      x-ux-hints: 'Price is quoted in the 402 body — confirm with the user before signing anything above $0.10. Volume tools (search, timelines, lists, community reads) REQUIRE resultsLimit and bill per returned item; the cap is enforced upstream so you never pay for more than you asked. x_extract runs async: the 202 body carries {snapshot_id, status_url} — hand the ID to the user and poll status_url (free, SIWX) only when they ask for progress. draws + x_extract require an Idempotency-Key header; retries with the same key replay the original response for 10 min instead of re-charging. Read failures before x402 settlement are not charged. Prepaid operations can fail after payment; inspect their receipt.'
      x-payment-info:
        authMode: paid
        price:
          mode: dynamic
          currency: USD
          min: '0.002400'
          max: '60.000000'
        protocols:
        - x402:
            network: base
            asset: USDC
        - x402:
            network: solana
            asset: USDC
        - mpp:
            method: usdc
            intent: charge
            currency: USD
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tool:
                  type: string
                  description: Which extractor to run.
                  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
                resultsLimit:
                  type: integer
                  description: 'MANDATORY: max results extracted, billed per result.'
                  minimum: 1
                  maximum: 10000
                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:
              tool: follower_explorer
              targetUsername: elonmusk
              resultsLimit: 500
      responses:
        '200':
          description: Result dataset.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    description: Array of returned items. Shape varies per tool — see each tool's documentation.
                    items:
                      type: object
                  runId:
                    type: string
                    description: Run ID for debugging/audit.
                  duration:
                    type: integer
                    description: Run duration in seconds.
                required:
                - items
              example:
                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
        '202':
          description: Async extraction accepted — body carries {snapshot_id, status_url} (x_extract only).
        '400':
          description: Bad request — missing resultsLimit or Idempotency-Key where required. Body is a Problem with `retryable:false` and a `hint`; never charged.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '402':
          description: 'Payment Required. Per-result reads require x402 upto on Base: authorize the maximum and pay only for delivered records, with a $0.0024 non-empty minimum and zero for empty results. Fixed-price operations may additionally offer exact x402 and MPP.'
        '403':
          description: Acting handle not connected to this wallet — connect it via /api/x-accounts/start first; never charged.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: Unknown tool path — GET /openapi.json for the valid list; never charged.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limited — `retryable:true`; retry unchanged after the Retry-After header; never charged.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Unexpected handler error — inspect payment receipt before retrying.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Upstream provider error — `retryable:true`; inspect payment receipt before retrying; prepaid operations may already be charged.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service capacity temporarily unavailable — `retryable:true`; retry later; never charged.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /api/tools/x_monitor:
    post:
      operationId: x_monitor
      summary: X/Twitter Monitor
      description: '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.'
      tags:
      - Intelligence
      parameters:
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
        description: Unique key per logical action. A retry with the same key replays the original result (10-minute window) instead of acting or charging twice.
      x-guidance: '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).'
      x-ux-hints: 'Price is quoted in the 402 body — confirm with the user before signing anything above $0.10. Volume tools (search, timelines, lists, community reads) REQUIRE resultsLimit and bill per returned item; the cap is enforced upstream so you never pay for more than you asked. x_extract runs async: the 202 body carries {snapshot_id, status_url} — hand the ID to the user and poll status_url (free, SIWX) only when they ask for progress. draws + x_extract require an Idempotency-Key header; retries with the same key replay the original response for 10 min instead of re-charging. Read failures before x402 settlement are not charged. Prepaid operations can fail after payment; inspect their receipt.'
      x-payment-info:
        authMode: paid
        price:
          mode: dynamic
          currency: USD
          min: '0.026400'
          max: '4.234800'
        protocols:
        - x402:
            network: base
            asset: USDC
        - x402:
            network: solana
            asset: USDC
        - mpp:
            method: usdc
            intent: charge
            currency: USD
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  description: Create a new monitor or extend an existing one.
                  enum:
                  - create
                  - extend
                type:
                  type: string
                  description: Monitor kind (create). Inferred from username/query when omitted.
                  enum:
                  - account
                  - keyword
                username:
                  type: string
                  description: X handle to monitor, without @ (create, type=account).
                query:
                  type: string
                  description: X search query to monitor (create, type=keyword).
                  maxLength: 512
                eventTypes:
                  type: array
                  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.'
                  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
                hours:
                  type: integer
                  description: Prepaid hours to purchase (default 1).
                  minimum: 1
                  maximum: 168
                monitorId:
                  type: string
                  description: Monitor to extend (extend only).
              required:
              - action
            example:
              action: create
              username: vercel
              eventTypes:
              - tweet.new
              hours: 24
      responses:
        '200':
          description: Result dataset.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    description: Array of returned items. Shape varies per tool — see each tool's documentation.
                    items:
                      type: object
                  runId:
                    type: string
                    description: Run ID for debugging/audit.
                  duration:
                    type: integer
                    description: Run duration in seconds.
                required:
                - items
              example:
                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
        '201':
          description: Monitor created — body carries {monitor, events_url, manage_url, extend}. Poll events_url (free, SIWX) or register a webhook at /api/webhooks.
        '202':
          description: Async extraction accepted — body carries {snapshot_id, status_url} (x_extract only).
        '400':
          description: Bad request — missing resultsLimit or Idempotency-Key where required. Body is a Problem with `retryable:false` and a `hint`; never charged.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '402':
          description: 'Payment Required. Per-result reads require x402 upto on Base: authorize the maximum and pay only for delivered records, with a $0.0024 non-empty minimum and zero for empty results. Fixed-price operations may additionally offer exact x402 and MPP.'
        '403':
          description: Acting handle not connected to this wallet — connect it via /api/x-accounts/start first; never charged.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: Unknown tool path — GET /openapi.json for the valid list; never charged.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: Active-monitor cap reached — never charged.
        '410':
          description: Extend target already expired — create a new monitor; never charged.
        '429':
          description: Rate limited — `retryable:true`; retry unchanged after the Retry-After header; never charged.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Unexpected handler error — inspect payment receipt before retrying.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Upstream provider error — `retryable:true`; inspect payment receipt before retrying; prepaid operations may already be charged.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service capacity temporarily unavailable — `retryable:true`; retry later; never charged.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /api/tools/radar:
    post:
      operationId: x_radar
      summary: Trend Radar
      description: 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.
      tags:
      - Intelligence
      x-guidance: 'Optional filters: category, region, hours (lookback), limit, source. Use report.next_cursor via `after` for the next page. Flat floor price per call.'
      x-ux-hints: 'Price is quoted in the 402 body — confirm with the user before signing anything above $0.10. Volume tools (search, timelines, lists, community reads) REQUIRE resultsLimit and bill per returned item; the cap is enforced upstream so you never pay for more than you asked. x_extract runs async: the 202 body carries {snapshot_id, status_url} — hand the ID to the user and poll status_url (free, SIWX) only when they ask for progress. draws + x_extract require an Idempotency-Key header; retries with the same key replay the original response for 10 min instead of re-charging. Read failures before x402 settlement are not charged. Prepaid operations can fail after payment; inspect their receipt.'
      x-payment-info:
        authMode: paid
        price:
          mode: dynamic
          currency: USD
          min: '0.002400'
          max: '0.002400'
        protocols:
        - x402:
            network: base
            asset: USDC
        - x402:
            network: solana
            asset: USDC
        - mpp:
            method: usdc
            intent: charge
            currency: USD
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                category:
                  type: string
                  description: Topic category filter.
                  enum:
                  - general
                  - tech
                  - dev
                  - science
                  - culture
                  - politics
                  - business
                  - entertainment
                region:
                  type: string
                hours:
                  type: integer
                limit:
                  type: integer
                source:
                  type: string
                  description: Trend source filter.
                  enum:
                  - github
                  - google_trends
                  - hacker_news
                  - polymarket
                  - reddit
                  - trustmrr
                  - wikipedia
                after:
                  type: string
                  description: Pagination cursor.
            example:
              category: tech
              hours: 24
              limit: 20
      responses:
        '200':
          description: Result dataset.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    description: Array of returned items. Shape varies per tool — see each tool's documentation.
                    items:
                      type: object
                  runId:
                    type: string
                    description: Run ID for debugging/audit.
                  duration:
                    type: integer
                    description: Run duration in seconds.
                required:
                - items
              example:
                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
        '202':
          description: Async extraction accepted — body carries {snapshot_id, status_url} (x_extract only).
        '400':
          description: Bad request — missing resultsLimit or Idempotency-Key where required. Body is a Problem with `retryable:false` and a `hint`; never charged.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '402':
          description: 'Payment Required. Per-result reads require x402 upto on Base: authorize the maximum and pay only for delivered records, with a $0.0024 non-empty minimum and zero for empty results. Fixed-price operations may additionally offer exact x402 and MPP.'
        '403':
          description: Acting handle not connected to this wallet — connect it via /api/x-accounts/start first; never charged.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: Unknown tool path — GET /openapi.json for the valid list; never charged.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limited — `retryable:true`; retry unchanged after the Retry-After header; never charged.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Unexpected handler error — inspect payment receipt before retrying.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Upstream provider error — `retryable:true`; inspect payment receipt before retrying; prepaid operations may already be charged.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service capacity temporarily unavailable — `retryable:true`; retry later; never charged.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
components:
  schemas:
    Problem:
      type: object
      description: RFC 9457 Problem Details, extended with machine-actionable recovery fields. Every non-2xx body from /api/tools/* uses this shape. x402 reads settle after success. Prepaid operations can fail after payment; inspect the receipt.
      properties:
        type:
          type: string
          description: Problem type URI (https://paymentauth.org/problems/{code}).
        title:
          type: string
          description: Human-readable summary of the problem class.
        status:
          type: integer
          description: HTTP status code, repeated in the body.
        detail:
          type: string
          description: What went wrong on this specific call.
        error:
          type: string
          description: Machine code (snake_case), e.g. records_cap_required, rate_limited.
        message:
          type: string
          description: Legacy alias of detail.
        retryable:
          type: boolean
          description: True when the SAME request, unchanged, may succeed if retried later (rate limit, capacity, transient upstream). False when the request must change first.
        hint:
          type: string
          description: One actionable next step for the calling agent.
        retry_after_seconds:
          type: integer
          description: 'Present on 429: seconds to wait before retrying.'
      required:
      - type
      - title
      - status
  securitySchemes:
    siwx:
      type: apiKey
      in: header
      name: SIGN-IN-WITH-X
      description: Sign-In-With-X (CAIP-122). Base64-encoded CAIP-122 payload signed by the caller's wallet. Server recovers the signer address cryptographically; any client-supplied wallet parameter is ignored.
    bearerKey:
      type: http
      scheme: bearer
      description: Optional API key (tw_live_…) created in the dashboard. Paid tools charge the key owner's prepaid USD balance instead of an on-chain payment; free endpoints accept it in place of SIWX.
    publicRead:
      type: apiKey
      in: query
      name: _public
      description: No-op placeholder. This endpoint requires no authentication; the scheme exists so validators that want a named security reference on public operations have one to point at.
x-ux-hints: Confirm with the user before any call that quotes above $0.10 or requests resultsLimit >= 500. Never spin a background poll loop — when the user asks progress on an extraction, call /api/snapshots/{id} (free, SIWX). Send Idempotency-Key with paid calls so a dropped response is replayed from cache (10 min) instead of re-running. Wallet history is free — use it when the user asks 'what have I extracted?'.
x-service-info:
  categories:
  - data
  - social
  - search
  - developer-tools
  docs:
    homepage: https://twitr.sh
    apiReference: https://twitr.sh/openapi.json
    llms: https://twitr.sh/llms.txt
x-discovery:
  ownershipProofs: []