twitr-sh Accounts API

openapi: 3.2.0
info:
  title: twitr.sh Accounts 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: Accounts
paths:
  /api/x-accounts:
    get:
      operationId: list_connected_accounts
      summary: List the wallet's connected X accounts
      tags:
      - Accounts
      security:
      - siwx: []
      responses:
        '200':
          description: '{accounts: [{handle, status (pending_code|linked), created_at, linked_at}]}.'
        '402':
          description: Identity Required (sign in with your wallet).
  /api/x-accounts/start:
    post:
      operationId: start_account_connect
      summary: Start connecting an X account — returns a link for the user (free, SIWX)
      description: 'THE way an agent connects an account: send only {username} and receive a single-use connect_url (15-minute TTL). Show that link to the user — they open it in their own browser and sign in to X there, so no password, email, or 2FA secret ever passes through the agent. Then poll GET /api/x-accounts until the handle reads linked. This endpoint refuses any request containing credentials.'
      tags:
      - Accounts
      security:
      - siwx: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  description: The X handle to connect, without @.
              required:
              - username
            example:
              username: myhandle
      responses:
        '200':
          description: '{handle, connect_url, expires_in} — give connect_url to the user.'
        '400':
          description: Invalid handle, or credentials were sent (never accepted here).
        '402':
          description: Identity Required (sign in with your wallet).
        '409':
          description: That handle is already connected by another wallet.
  /api/x-accounts/connect:
    post:
      operationId: connect_account
      summary: Browser credential submit — agents should use /api/x-accounts/start instead
      description: 'The browser form behind a connect link posts here; AGENTS CANNOT USE THIS. It REQUIRES a one-time token from POST /api/x-accounts/start, which is only delivered through the link the user opens — and the token is bound to the wallet that minted it, so a handle can never link to a different wallet. Use /api/x-accounts/start and give the user the link; never ask a user for their X password. Credentials arriving here are sealed in transit, relayed to the platform (encrypted at rest there), and never stored or logged by twitr.sh. Returns status=linked, or status=pending_code + challenge_id when an email code is needed (then /api/x-accounts/confirm). On 429 login_cooldown the account is temporarily paused: wait the Retry-After seconds, do NOT retry sooner (it extends the pause).'
      tags:
      - Accounts
      security:
      - siwx: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  description: X handle, no @.
                email:
                  type: string
                  description: Email on the X account (may receive a verification code).
                password:
                  type: string
                  description: X account password.
                totp_secret:
                  type: string
                  description: 'REQUIRED if the account has 2FA: the authenticator secret key, not the 6-digit code.'
              required:
              - username
              - email
              - password
      responses:
        '200':
          description: '{handle, status: ''linked''} or {handle, status: ''pending_code'', challenge_id}.'
        '402':
          description: Identity Required.
        '429':
          description: Login temporarily paused (login_cooldown) — wait Retry-After seconds; retrying extends it.
  /api/x-accounts/confirm:
    post:
      operationId: confirm_account
      summary: Submit the email verification code (free, SIWX)
      tags:
      - Accounts
      security:
      - siwx: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                challenge_id:
                  type: string
                  description: From the connect response.
                code:
                  type: string
                  description: The code emailed to the account.
              required:
              - challenge_id
              - code
      responses:
        '200':
          description: '{handle, status: ''linked''} — the handle is now usable for x_write.'
        '402':
          description: Identity Required.
  /api/x-accounts/{handle}:
    delete:
      operationId: disconnect_account
      summary: Disconnect an X account (free, SIWX)
      tags:
      - Accounts
      security:
      - siwx: []
      parameters:
      - name: handle
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '{ok: true, handle}.'
        '402':
          description: Identity Required.
        '404':
          description: This wallet has no such connected account.
components:
  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: []