Surf Social API

openapi: 3.1.0
info:
  contact:
    email: backend@cybertinolab.com
    name: Cyber team
  description: "Surf data API gateway providing typed endpoints for crypto market data, project analytics, social signals, on-chain queries, and more. All endpoints use credit-based billing with per-request rate limiting.\n\n## Parameter Naming Conventions\n\nAll endpoints follow a standardized naming scheme. Use these canonical names when calling the API.\n\n### Asset Identification\n\n| Param | Type | Description | Example |\n|-------|------|-------------|---------|\n| `symbol` | string | Uppercase ticker symbol(s), comma-separated | `BTC`, `ETH,SOL` |\n| `q` | string | Free-text search keyword | `bitcoin` |\n| `id` | string | Surf entity UUID for direct lookup | `550e8400-...` |\n| `address` | string | On-chain contract or wallet address. Also accepts ENS names (e.g. `vitalik.eth`) which resolve automatically. | `0xdead...`, `vitalik.eth` |\n\n### Time & Aggregation\n\n| Param | Type | Description | Example |\n|-------|------|-------------|---------|\n| `time_range` | string or int | Lookback window | `7d`, `30d`, `365d`, `max` |\n| `interval` | string | Candlestick / indicator interval | `1h`, `1d`, `1w` |\n| `granularity` | string | Data aggregation granularity | `day`, `block`, `hour` |\n\n### Filtering & Sorting\n\n| Param | Type | Description | Example |\n|-------|------|-------------|---------|\n| `chain` | string | Blockchain name (canonical long-form only) | `ethereum`, `solana`, `base` |\n| `currency` | string | Quote currency | `usd`, `eur`, `btc` |\n| `metric` | string | Metric name (endpoint-specific enum) | `nupl`, `tvl` |\n| `type` | string | Category selector (endpoint-specific enum) | `us-btc-spot` |\n| `sort` | string | Sort direction | `asc`, `desc` |\n\n### Pagination\n\nAll list endpoints support:\n- `limit` (int, default: 20, max: 100) — results per page\n- `offset` (int, default: 0) — pagination offset\n\n### Supported Chains\n\nUse canonical long-form names only. Short aliases (eth, sol, matic, etc.) are **not accepted**.\n\n| Chain | Value |\n|-------|-------|\n| Ethereum | `ethereum` |\n| Polygon | `polygon` |\n| BNB Chain | `bsc` |\n| Solana | `solana` |\n| Avalanche | `avalanche` |\n| Arbitrum | `arbitrum` |\n| Optimism | `optimism` |\n| Fantom | `fantom` |\n| Base | `base` |\n| Linea | `linea` |\n| Cyber | `cyber` |\n\nNot all chains are available on every endpoint. Check each endpoint's `chain` enum for supported values.\n\n## Authentication\n\nAll data endpoints require a Bearer token in the `Authorization` header:\n\n```\nAuthorization: Bearer <API_KEY>\n```\n\n## Error Responses\n\nAll endpoints return errors in a consistent format:\n\n```json\n{\n  \"error\": {\n    \"code\": \"FORBIDDEN\",\n    \"message\": \"insufficient credits\"\n  }\n}\n```\n\n| HTTP Status | Meaning |\n|-------------|---------|\n| `400` | Bad request — invalid or missing parameters |\n| `401` | Unauthorized — missing or invalid API key |\n| `404` | Not found — the requested entity does not exist |\n| `422` | Validation error — parameter value is out of range or invalid |\n| `429` | Rate limited — too many requests, retry after the indicated interval |\n| `502` | Upstream error — a data source is temporarily unavailable |\n\n## Credits\n\nEach API call costs a certain number of credits. The cost is returned in every response under `meta.credits_used`. Check your remaining balance via `GET /v1/me/credit-balance`.\n"
  title: Hermod DEX Social API
  version: sha-80d3407
servers:
- url: /
tags:
- description: Monitor crypto social activity on X (Twitter). Look up user profiles and their posts, track project sentiment scores and follower geography, discover smart followers, and analyze mindshare trends over time to gauge social momentum.
  name: Social
paths:
  /gateway/v1/social/detail:
    get:
      description: 'Returns Twitter/X analytics for a crypto project: sentiment score, follower geography, and smart follower breakdown (VCs, KOLs, developers). For individual user profiles use `social-user` instead.


        **Available fields** (via `fields`): `sentiment`, `follower_geo`, `smart_followers`.


        **Lookup:** by X account ID (`x_id`) or project name (`q`, e.g. `uniswap`, `solana`). The `q` parameter must be a crypto project name, not a personal Twitter handle. Returns 404 if the project has no linked Twitter account.


        For sentiment **trends over time**, use `/social/mindshare` instead.'
      operationId: social-detail
      parameters:
      - description: Numeric X (Twitter) account ID (takes priority over `q`)
        explode: false
        in: query
        name: x_id
        schema:
          description: Numeric X (Twitter) account ID (takes priority over `q`)
          examples:
          - '984188226826010624'
          type: string
      - description: Entity name to resolve like `uniswap`, `ethereum`, or `aave`
        explode: false
        in: query
        name: q
        schema:
          description: Entity name to resolve like `uniswap`, `ethereum`, or `aave`
          examples:
          - uniswap
          type: string
      - description: Comma-separated sub-resources to include. Can be `sentiment`, `follower_geo`, or `smart_followers`.
        explode: false
        in: query
        name: fields
        schema:
          default: sentiment,follower_geo,smart_followers
          description: Comma-separated sub-resources to include. Can be `sentiment`, `follower_geo`, or `smart_followers`.
          examples:
          - sentiment
          type: string
      - description: 'Window to aggregate sentiment data over: `24h`, `48h`, `7d`, `30d`, `3m`, `6m`, or `1y`. Returns a single snapshot (not a time-series). This endpoint uses `time_range` only — it does NOT accept `interval`. For mindshare time-series use /v1/social/mindshare.'
        explode: false
        in: query
        name: time_range
        schema:
          default: 7d
          description: 'Window to aggregate sentiment data over: `24h`, `48h`, `7d`, `30d`, `3m`, `6m`, or `1y`. Returns a single snapshot (not a time-series). This endpoint uses `time_range` only — it does NOT accept `interval`. For mindshare time-series use /v1/social/mindshare.'
          enum:
          - 24h
          - 48h
          - 7d
          - 30d
          - 3m
          - 6m
          - 1y
          examples:
          - 7d
          type: string
      - description: Max geo locations to return
        explode: false
        in: query
        name: geo_limit
        schema:
          default: 20
          description: Max geo locations to return
          examples:
          - 10
          format: int64
          maximum: 100
          minimum: 1
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataObjectResponseSocialDetailBody'
          description: OK
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataAPIError'
          description: Error
      security:
      - AccessToken: []
      summary: Aggregated Social Analytics
      tags:
      - Social
  /gateway/v1/social/mindshare:
    get:
      description: 'Returns mindshare (social view count) **time-series trend** for a project, aggregated by `interval`.


        **Intervals:** `5m`, `1h`, `1d`, `7d`. `interval` is REQUIRED.


        **Filters:** date range with `from`/`to` (Unix seconds). Lookup by Surf project UUID (`id`) or by name (`q`) — exactly one of the two is required.


        **No pagination and no `time_range`** — this endpoint does NOT accept `limit`, `offset`, or `time_range`. Size of the returned series is controlled by `from`/`to` divided by `interval`.


        Use this for sentiment **trends**, mindshare **over time**, or social momentum changes.


        For a **point-in-time snapshot** of social analytics (sentiment score, follower geo, smart followers), use `/social/detail` instead.'
      operationId: social-mindshare
      parameters:
      - description: Surf project UUID. Provide one of `id` or `q`.
        explode: false
        in: query
        name: id
        schema:
          description: Surf project UUID. Provide one of `id` or `q`.
          examples:
          - 25c6612a-395c-4974-94eb-3b5f9f4b2ed7
          type: string
      - description: Entity name to resolve like `uniswap`, `ethereum`, or `aave`. Provide one of `id` or `q`.
        explode: false
        in: query
        name: q
        schema:
          description: Entity name to resolve like `uniswap`, `ethereum`, or `aave`. Provide one of `id` or `q`.
          examples:
          - uniswap
          type: string
      - description: 'Bucket size for each point in the returned time-series: `5m`, `1h`, `1d`, or `7d`. This is NOT a window — this endpoint has no default window, pass `from`/`to` to bound the range. Not the same parameter as `time_range` (which does not exist on this endpoint). Note: when `include_tag_percents=true`, `5m` falls back to hourly data for the per-tag series (Argus has no 5m granularity for tag percentages).'
        explode: false
        in: query
        name: interval
        required: true
        schema:
          description: 'Bucket size for each point in the returned time-series: `5m`, `1h`, `1d`, or `7d`. This is NOT a window — this endpoint has no default window, pass `from`/`to` to bound the range. Not the same parameter as `time_range` (which does not exist on this endpoint). Note: when `include_tag_percents=true`, `5m` falls back to hourly data for the per-tag series (Argus has no 5m granularity for tag percentages).'
          enum:
          - 5m
          - 1h
          - 1d
          - 7d
          examples:
          - 1d
          type: string
      - description: Start timestamp. Accepts Unix seconds (1704067200) or date string (2024-01-01)
        explode: false
        in: query
        name: from
        schema:
          description: Start timestamp. Accepts Unix seconds (1704067200) or date string (2024-01-01)
          examples:
          - '1704067200'
          type: string
      - description: End timestamp. Accepts Unix seconds (1706745600) or date string (2024-02-01)
        explode: false
        in: query
        name: to
        schema:
          description: End timestamp. Accepts Unix seconds (1706745600) or date string (2024-02-01)
          examples:
          - '1706745600'
          type: string
      - description: Set to `true` to additionally return per-tag mindshare percentage time-series in the `tag_percents` field. A project can belong to multiple tags; each tag returns its own sparse time-series (values are 0~100 percentages, not ratios). Default `false` — response shape is byte-identical to the legacy format.
        explode: false
        in: query
        name: include_tag_percents
        schema:
          description: Set to `true` to additionally return per-tag mindshare percentage time-series in the `tag_percents` field. A project can belong to multiple tags; each tag returns its own sparse time-series (values are 0~100 percentages, not ratios). Default `false` — response shape is byte-identical to the legacy format.
          examples:
          - true
          type: boolean
      - description: 'Data lane: `x` (X/Twitter, default) or `binance_square` (Binance Square). Response shape is identical across sources.'
        explode: false
        in: query
        name: source
        schema:
          default: x
          description: 'Data lane: `x` (X/Twitter, default) or `binance_square` (Binance Square). Response shape is identical across sources.'
          enum:
          - x
          - binance_square
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SocialMindshareBody'
          description: OK
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataAPIError'
          description: Error
      security:
      - AccessToken: []
      summary: Project Mindshare Time Series
      tags:
      - Social
  /gateway/v1/social/ranking:
    get:
      description: 'Returns top crypto projects ranked by mindshare (social view count), refreshed every 5 minutes.


        **Filters:**

        - `tag` — scope to a category (e.g. `dex`, `l1`, `meme`)

        - `time_range` — ranking window (`24h`, `48h`, `7d`, `30d`)


        Supports `limit`/`offset` pagination.'
      operationId: social-ranking
      parameters:
      - description: Pagination offset
        explode: false
        in: query
        name: offset
        schema:
          default: 0
          description: Pagination offset
          examples:
          - 0
          format: int64
          minimum: 0
          type: integer
      - description: Results per page
        explode: false
        in: query
        name: limit
        schema:
          default: 20
          description: Results per page
          examples:
          - 20
          format: int64
          maximum: 100
          minimum: 1
          type: integer
      - description: Filter by project category. `l1` = Layer 1, `l2` = Layer 2/scaling, `dex` = DEX/AMM, `derivatives` = perps/options, `cex` = centralized exchange, `gamefi` = gaming, `nft` = NFT collections, `oracle` = oracle, `prediction` = prediction market, `rwa` = real-world assets, `yield` = yield/asset management, `data` = data/analytics, `devtool` = developer tooling, `compliance` = compliance/regtech, `meme` = meme/token launchpad.
        explode: false
        in: query
        name: tag
        schema:
          description: Filter by project category. `l1` = Layer 1, `l2` = Layer 2/scaling, `dex` = DEX/AMM, `derivatives` = perps/options, `cex` = centralized exchange, `gamefi` = gaming, `nft` = NFT collections, `oracle` = oracle, `prediction` = prediction market, `rwa` = real-world assets, `yield` = yield/asset management, `data` = data/analytics, `devtool` = developer tooling, `compliance` = compliance/regtech, `meme` = meme/token launchpad.
          enum:
          - l1
          - l2
          - dex
          - derivatives
          - cex
          - gamefi
          - nft
          - oracle
          - prediction
          - rwa
          - yield
          - data
          - devtool
          - compliance
          - meme
          - ''
          examples:
          - dex
          type: string
      - description: 'Window to compute the ranking over: `24h`, `48h`, `7d`, or `30d`. Returns a single ranked snapshot (not a time-series). This endpoint uses `time_range` only — it does NOT accept `interval`.'
        explode: false
        in: query
        name: time_range
        schema:
          default: 7d
          description: 'Window to compute the ranking over: `24h`, `48h`, `7d`, or `30d`. Returns a single ranked snapshot (not a time-series). This endpoint uses `time_range` only — it does NOT accept `interval`.'
          enum:
          - 24h
          - 48h
          - 7d
          - 30d
          examples:
          - 7d
          type: string
      - description: Filter by sentiment polarity. Only projects with sufficient tweet data are classified.
        explode: false
        in: query
        name: sentiment
        schema:
          description: Filter by sentiment polarity. Only projects with sufficient tweet data are classified.
          enum:
          - positive
          - negative
          - ''
          examples:
          - positive
          type: string
      - description: 'Data lane: `x` (X/Twitter, default) or `binance_square` (Binance Square). Response shape is identical across sources.'
        explode: false
        in: query
        name: source
        schema:
          default: x
          description: 'Data lane: `x` (X/Twitter, default) or `binance_square` (Binance Square). Response shape is identical across sources.'
          enum:
          - x
          - binance_square
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataResponseMindshareTopProject'
          description: OK
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataAPIError'
          description: Error
      security:
      - AccessToken: []
      summary: Social Mindshare Ranking
      tags:
      - Social
  /gateway/v1/social/sentiment:
    get:
      description: 'Returns the aggregate social sentiment score for a project.


        Score ranges from -1.0 (bearish) to 1.0 (bullish).'
      operationId: social-sentiment
      parameters:
      - description: Surf project UUID
        explode: false
        in: query
        name: id
        schema:
          description: Surf project UUID
          examples:
          - 25c6612a-395c-4974-94eb-3b5f9f4b2ed7
          type: string
      - description: Project name or symbol for entity resolution
        explode: false
        in: query
        name: q
        schema:
          description: Project name or symbol for entity resolution
          examples:
          - bitcoin
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataObjectResponseSocialSentimentItem'
          description: OK
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataAPIError'
          description: Error
      security:
      - AccessToken: []
      summary: Social Sentiment
      tags:
      - Social
  /gateway/v1/social/smart-followers/history:
    get:
      description: 'Returns smart follower count time-series for a project, sorted by date descending.


        **Lookup:** by X account ID (`x_id`) or project name (`q`). The `q` parameter must be a project name (e.g. `uniswap`, `ethereum`), not a personal X handle — use `x_id` for individual accounts. Returns 404 if the project has no linked X account.'
      operationId: social-smart-followers-history
      parameters:
      - description: Numeric X (Twitter) account ID (takes priority over `q`)
        explode: false
        in: query
        name: x_id
        schema:
          description: Numeric X (Twitter) account ID (takes priority over `q`)
          examples:
          - '984188226826010624'
          type: string
      - description: Project name to resolve (e.g. `uniswap`, `ethereum`). Must be a project with a linked X account — personal handles like `VitalikButerin` return 404. Use `x_id` for individual accounts.
        explode: false
        in: query
        name: q
        schema:
          description: Project name to resolve (e.g. `uniswap`, `ethereum`). Must be a project with a linked X account — personal handles like `VitalikButerin` return 404. Use `x_id` for individual accounts.
          examples:
          - uniswap
          type: string
      - description: Max data points to return (upstream typically provides ~36 daily points)
        explode: false
        in: query
        name: limit
        schema:
          default: 36
          description: Max data points to return (upstream typically provides ~36 daily points)
          examples:
          - 36
          format: int64
          maximum: 100
          minimum: 1
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataResponseSmartFollowerHistoryPoint'
          description: OK
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataAPIError'
          description: Error
      security:
      - AccessToken: []
      summary: Smart Follower Count History
      tags:
      - Social
  /gateway/v1/social/tweet/replies:
    get:
      description: 'Returns replies/comments on a specific tweet.


        **Lookup:** by `tweet_id`.'
      operationId: social-tweet-replies
      parameters:
      - description: Tweet ID to get replies for
        explode: false
        in: query
        name: tweet_id
        required: true
        schema:
          description: Tweet ID to get replies for
          examples:
          - '1999187154530898007'
          type: string
      - description: Max results to return
        explode: false
        in: query
        name: limit
        schema:
          default: 20
          description: Max results to return
          examples:
          - 20
          format: int64
          maximum: 100
          minimum: 1
          type: integer
      - description: Opaque cursor token from a previous response's next_cursor field for fetching the next page
        explode: false
        in: query
        name: cursor
        schema:
          description: Opaque cursor token from a previous response's next_cursor field for fetching the next page
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorDataResponseXTweet'
          description: OK
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataAPIError'
          description: Error
      security:
      - AccessToken: []
      summary: Tweet Replies
      tags:
      - Social
  /gateway/v1/social/tweets:
    get:
      description: 'Returns X (Twitter) posts by numeric post ID strings.


        Pass up to 100 comma-separated IDs via the `ids` query parameter.'
      operationId: social-tweets
      parameters:
      - description: Comma-separated numeric post ID strings, max 100
        explode: false
        in: query
        name: ids
        required: true
        schema:
          description: Comma-separated numeric post ID strings, max 100
          examples:
          - 1880293339000000000,1880293339000000001
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataResponseXTweet'
          description: OK
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataAPIError'
          description: Error
      security:
      - AccessToken: []
      summary: Social Posts by IDs
      tags:
      - Social
  /gateway/v1/social/user:
    get:
      description: 'Returns a basic X/Twitter profile (name, bio, avatar, follower/following counts) for any handle. For crypto project social analytics (sentiment, smart followers, geo), use `social-detail` instead.


        **Lookup:** by `handle` (without @).'
      operationId: social-user
      parameters:
      - description: X (Twitter) username without @ like `cz_binance` or `vitalikbuterin`
        explode: false
        in: query
        name: handle
        required: true
        schema:
          description: X (Twitter) username without @ like `cz_binance` or `vitalikbuterin`
          examples:
          - vitalikbuterin
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataObjectResponseXUser'
          description: OK
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataAPIError'
          description: Error
      security:
      - AccessToken: []
      summary: Social User Profile
      tags:
      - Social
  /gateway/v1/social/user/followers:
    get:
      description: 'Returns a list of followers for the specified handle on X (Twitter).


        **Lookup:** by `handle` (without @).'
      operationId: social-user-followers
      parameters:
      - description: X (Twitter) username without @ like `vitalikbuterin` or `cz_binance`
        explode: false
        in: query
        name: handle
        required: true
        schema:
          description: X (Twitter) username without @ like `vitalikbuterin` or `cz_binance`
          examples:
          - vitalikbuterin
          type: string
      - description: Max results to return
        explode: false
        in: query
        name: limit
        schema:
          default: 20
          description: Max results to return
          examples:
          - 20
          format: int64
          maximum: 100
          minimum: 1
          type: integer
      - description: Opaque cursor token from a previous response's next_cursor field for fetching the next page
        explode: false
        in: query
        name: cursor
        schema:
          description: Opaque cursor token from a previous response's next_cursor field for fetching the next page
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorDataResponseXUser'
          description: OK
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataAPIError'
          description: Error
      security:
      - AccessToken: []
      summary: User Followers List
      tags:
      - Social
  /gateway/v1/social/user/following:
    get:
      description: 'Returns a list of users that the specified handle follows on X (Twitter).


        **Lookup:** by `handle` (without @).'
      operationId: social-user-following
      parameters:
      - description: X (Twitter) username without @ like `vitalikbuterin` or `cz_binance`
        explode: false
        in: query
        name: handle
        required: true
        schema:
          description: X (Twitter) username without @ like `vitalikbuterin` or `cz_binance`
          examples:
          - vitalikbuterin
          type: string
      - description: Max results to return
        explode: false
        in: query
        name: limit
        schema:
          default: 20
          description: Max results to return
          examples:
          - 20
          format: int64
          maximum: 100
          minimum: 1
          type: integer
      - description: Opaque cursor token from a previous response's next_cursor field for fetching the next page
        explode: false
        in: query
        name: cursor
        schema:
          description: Opaque cursor token from a previous response's next_cursor field for fetching the next page
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorDataResponseXUser'
          description: OK
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataAPIError'
          description: Error
      security:
      - AccessToken: []
      summary: User Following List
      tags:
      - Social
  /gateway/v1/social/user/posts:
    get:
      description: 'Returns recent X (Twitter) posts by a specific user, ordered by recency.


        **Lookup:** by `handle` (without @). Use `filter=original` to exclude retweets.


        **Pagination:** check `meta.has_more`; if true, pass `meta.next_cursor` as the `cursor` query parameter in the next request.'
      operationId: social-user-posts
      parameters:
      - description: X (Twitter) username without @ like `vitalikbuterin` or `cz_binance`
        explode: false
        in: query
        name: handle
        required: true
        schema:
          description: X (Twitter) username without @ like `vitalikbuterin` or `cz_binance`
          examples:
          - vitalikbuterin
          type: string
      - description: Results per page
        explode: false
        in: query
        name: limit
        schema:
          default: 20
          description: Results per page
          examples:
          - 20
          format: int64
          maximum: 100
          minimum: 1
          type: integer
      - description: Opaque cursor token from a previous response's next_cursor field for fetching the next page
        explode: false
        in: query
        name: cursor
        schema:
          description: Opaque cursor token from a previous response's next_cursor field for fetching the next page
          type: string
      - description: 'Filter tweets: `all` returns everything, `original` excludes retweets'
        explode: false
        in: query
        name: filter
        schema:
          default: all
          description: 'Filter tweets: `all` returns everything, `original` excludes retweets'
          enum:
          - all
          - original
          examples:
          - all
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorDataResponseXTweet'
          description: OK
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataAPIError'
          description: Error
      security:
      - AccessToken: []
      summary: User Social Posts
      tags:
      - Social
  /gateway/v1/social/user/replies:
    get:
      description: 'Returns recent replies by the specified handle on X (Twitter).


        **Lookup:** by `handle` (without @).'
      operationId: social-user-replies
      parameters:
      - description: X (Twitter) username without @ like `vitalikbuterin` or `cz_binance`
        explode: false
        in: query
        name: handle
        required: true
        schema:
          description: X (Twitter) username without @ like `vitalikbuterin` or `cz_binance`
          examples:
          - vitalikbuterin
          type: string
      - description: Max results to return
        explode: false
        in: query
        name: limit
        schema:
          default: 20
          description: Max results to return
          examples:
          - 20
          format: int64
          maximum: 100
          minimum: 1
          type: integer
      - description: Opaque cursor token from a previous response's next_cursor field for fetching the next page
        explode: false
        in: query
        name: cursor
        schema:
          description: Opaque cursor token from a previous response's next_cursor field for fetching the next page
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorDataResponseXTweet'
          description: OK
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataAPIError'
          description: Error
      security:
      - AccessToken: []
      summary: User Replies
      tags:
      - Social
components:
  schemas:
    OffsetMeta:
      additionalProperties: false
      properties:
        cached:
          description: Whether this response was served from cache
          type: boolean
        credits_used:
          description: Credits deducted for this request
          format: int64
          type: integer
        empty_reason:
          description: Hint explaining why the data array is empty, when applicable
          type: string
        has_more:
          description: Whether more items may exist beyond this response. For offset-paged endpoints, continue with a larger offset. For time-series endpoints without offset/cursor controls, true means the requested time range hit an upstream cap; narrow from/to to continue. Omitted when exhaustion cannot be proven.
          type: boolean
        limit:
          description: Maximum number of items returned in this response
          format: int64
          type: integer
        offset:
          description: Number of items skipped (pagination offset)
          format: int64
          type: integer
        total:
          description: Total number of matching items (before pagination). Omitted when total is unknown.
          format: int64
          type: integer
        

# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/surf/refs/heads/main/openapi/surf-social-api-openapi.yml