openapi: 3.0.1
info:
  title: thirdweb Authentication Wallets API
  description: thirdweb provides a unified interface for Web3 development. This specification documents real, publicly documented HTTP endpoints across the thirdweb unified API (api.thirdweb.com - wallets, transactions, contracts, tokens, payments and bridge), Engine (backend transaction execution), Insight (indexed on-chain data) and Nebula (AI blockchain interface). Authenticate frontend usage with an x-client-id header (plus x-bundle-id for native apps) or a Bearer JWT, and backend usage with an x-secret-key header.
  termsOfService: https://thirdweb.com/tos
  contact:
    name: thirdweb Support
    url: https://thirdweb.com/support
  version: '1.22'
servers:
- url: https://api.thirdweb.com
  description: thirdweb unified API (wallets, transactions, contracts, tokens, payments, bridge)
- url: https://engine.thirdweb.com
  description: thirdweb Engine (backend transaction execution)
- url: https://insight.thirdweb.com
  description: thirdweb Insight (indexed on-chain data)
- url: https://nebula-api.thirdweb.com
  description: thirdweb Nebula (AI blockchain interface)
security:
- SecretKeyAuth: []
- ClientAuth: []
- BearerAuth: []
tags:
- name: Wallets
  description: User and server wallet management, signing, and transfers.
paths:
  /v1/wallets/me:
    get:
      operationId: getMyWallet
      tags:
      - Wallets
      summary: Get the authenticated user's wallet.
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Wallet details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Wallet'
  /v1/wallets/user:
    get:
      operationId: listUserWallets
      tags:
      - Wallets
      summary: List user wallets.
      responses:
        '200':
          description: A list of user wallets.
    post:
      operationId: createUserWallet
      tags:
      - Wallets
      summary: Create a user wallet.
      responses:
        '201':
          description: User wallet created.
  /v1/wallets/server:
    get:
      operationId: listServerWallets
      tags:
      - Wallets
      summary: List server wallets.
      responses:
        '200':
          description: A list of server wallets.
    post:
      operationId: createServerWallet
      tags:
      - Wallets
      summary: Create a server wallet.
      responses:
        '201':
          description: Server wallet created.
  /v1/wallets/{address}/balance:
    get:
      operationId: getWalletBalance
      tags:
      - Wallets
      summary: Get a wallet's token balance.
      parameters:
      - $ref: '#/components/parameters/Address'
      - name: chainId
        in: query
        required: true
        schema:
          type: integer
      - name: tokenAddress
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Balance result.
  /v1/wallets/sign-message:
    post:
      operationId: signMessage
      tags:
      - Wallets
      summary: Sign an arbitrary message with a wallet.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignMessageRequest'
      responses:
        '200':
          description: Signature result.
  /v1/wallets/sign-typed-data:
    post:
      operationId: signTypedData
      tags:
      - Wallets
      summary: Sign EIP-712 typed data with a wallet.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Signature result.
  /v1/wallets/send:
    post:
      operationId: sendTokens
      tags:
      - Wallets
      summary: Send native or ERC-20/721/1155 tokens to recipients.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendTokensRequest'
      responses:
        '200':
          description: Transaction queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionResult'
components:
  schemas:
    TransactionResult:
      type: object
      properties:
        transactionId:
          type: string
        transactionHash:
          type: string
        chainId:
          type: integer
        status:
          type: string
          description: Queued, submitted, mined, or errored.
    SignMessageRequest:
      type: object
      properties:
        from:
          type: string
          description: The wallet address signing the message.
        message:
          type: string
        chainId:
          type: integer
      required:
      - message
    Wallet:
      type: object
      properties:
        address:
          type: string
        smartWalletAddress:
          type: string
        createdAt:
          type: string
          format: date-time
    SendTokensRequest:
      type: object
      properties:
        from:
          type: string
        chainId:
          type: integer
        recipients:
          type: array
          items:
            type: object
            properties:
              address:
                type: string
              quantity:
                type: string
        tokenAddress:
          type: string
        tokenId:
          type: string
      required:
      - chainId
      - recipients
  parameters:
    Address:
      name: address
      in: path
      required: true
      description: An EVM wallet or contract address.
      schema:
        type: string
  securitySchemes:
    ClientAuth:
      type: apiKey
      in: header
      name: x-client-id
      description: Client ID for frontend usage. Web sends x-client-id only; native apps also send x-bundle-id.
    BundleIdAuth:
      type: apiKey
      in: header
      name: x-bundle-id
      description: Bundle ID for native (desktop/mobile) platform authentication alongside x-client-id.
    SecretKeyAuth:
      type: apiKey
      in: header
      name: x-secret-key
      description: Secret key for backend usage; never expose publicly.
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT access token obtained from wallet authentication, for frontend usage.