thirdweb Payments and Bridge

Bridge, swap, convert, and onramp any currency across thousands of chains, and accept HTTP and agentic payments with the x402 verify, settle, fetch, and discovery endpoints.

OpenAPI Specification

thirdweb-openapi.yml Raw ↑
openapi: 3.0.1
info:
  title: thirdweb 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: Authentication
    description: Wallet authentication flows.
  - name: Wallets
    description: User and server wallet management, signing, and transfers.
  - name: Contracts
    description: Smart contract read, write, and deployment.
  - name: Transactions
    description: Transaction submission and status.
  - name: Tokens
    description: Token creation, listing, and ownership.
  - name: Payments
    description: Bridge, swap, convert, onramp, and x402 payments.
  - name: Engine
    description: Backend transaction execution with server wallets.
  - name: Insight
    description: Indexed on-chain events, transactions, tokens, and NFTs.
  - name: Nebula
    description: AI blockchain interface.
paths:
  /v1/auth/initiate:
    post:
      operationId: initiateAuth
      tags:
        - Authentication
      summary: Initiate a wallet authentication flow.
      description: Starts an authentication flow (email, phone, OAuth, or SIWE) and triggers any verification step such as an OTP.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthInitiateRequest'
      responses:
        '200':
          description: Authentication initiated.
  /v1/auth/complete:
    post:
      operationId: completeAuth
      tags:
        - Authentication
      summary: Complete a wallet authentication flow.
      description: Completes authentication by verifying the challenge and returns a JWT access token and wallet address.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthCompleteRequest'
      responses:
        '200':
          description: Authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResult'
  /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'
  /v1/contracts/read:
    post:
      operationId: readContract
      tags:
        - Contracts
      summary: Read from one or more smart contracts.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContractReadRequest'
      responses:
        '200':
          description: Read results.
  /v1/contracts/write:
    post:
      operationId: writeContract
      tags:
        - Contracts
      summary: Write to one or more smart contracts.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContractWriteRequest'
      responses:
        '200':
          description: Transaction queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionResult'
  /v1/contracts:
    post:
      operationId: deployContract
      tags:
        - Contracts
      summary: Deploy a smart contract.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Deployment queued.
  /v1/contracts/{chainId}/{address}/events:
    get:
      operationId: getContractEvents
      tags:
        - Contracts
      summary: Get events emitted by a contract.
      parameters:
        - $ref: '#/components/parameters/ChainId'
        - $ref: '#/components/parameters/Address'
      responses:
        '200':
          description: Contract events.
  /v1/transactions:
    get:
      operationId: listTransactions
      tags:
        - Transactions
      summary: List transactions.
      responses:
        '200':
          description: A list of transactions.
    post:
      operationId: sendTransactions
      tags:
        - Transactions
      summary: Send a batch of transactions.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Transactions queued.
  /v1/transactions/{transactionId}:
    get:
      operationId: getTransaction
      tags:
        - Transactions
      summary: Get a transaction by ID.
      parameters:
        - name: transactionId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Transaction details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionResult'
  /v1/tokens:
    get:
      operationId: listTokens
      tags:
        - Tokens
      summary: List tokens.
      responses:
        '200':
          description: A list of tokens.
    post:
      operationId: createToken
      tags:
        - Tokens
      summary: Create (deploy) a token.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTokenRequest'
      responses:
        '200':
          description: Token creation queued.
  /v1/tokens/{chainId}/{address}/owners:
    get:
      operationId: getTokenOwners
      tags:
        - Tokens
      summary: Get owners of a token.
      parameters:
        - $ref: '#/components/parameters/ChainId'
        - $ref: '#/components/parameters/Address'
      responses:
        '200':
          description: Token owners.
  /v1/bridge/chains:
    get:
      operationId: bridgeChains
      tags:
        - Payments
      summary: List chains supported for bridging.
      responses:
        '200':
          description: Supported chains.
  /v1/bridge/routes:
    get:
      operationId: bridgeRoutes
      tags:
        - Payments
      summary: List supported bridge/swap routes.
      responses:
        '200':
          description: Supported routes.
  /v1/bridge/convert:
    get:
      operationId: bridgeConvert
      tags:
        - Payments
      summary: Convert a fiat amount to a crypto quote.
      responses:
        '200':
          description: Conversion quote.
  /v1/bridge/swap:
    post:
      operationId: bridgeSwap
      tags:
        - Payments
      summary: Swap or bridge tokens.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BridgeSwapRequest'
      responses:
        '200':
          description: Swap prepared.
  /v1/payments/x402/verify:
    post:
      operationId: x402Verify
      tags:
        - Payments
      summary: Verify an x402 payment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Verification result.
  /v1/payments/x402/settle:
    post:
      operationId: x402Settle
      tags:
        - Payments
      summary: Settle an x402 payment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Settlement result.
  /v1/payments/x402/supported:
    get:
      operationId: x402Supported
      tags:
        - Payments
      summary: List supported x402 payment methods.
      responses:
        '200':
          description: Supported payment methods.
  /ai/chat:
    post:
      operationId: aiChat
      tags:
        - Nebula
      summary: Chat with the thirdweb AI to read and write on-chain.
      servers:
        - url: https://api.thirdweb.com
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: AI chat response.
  /v1/write/contract:
    post:
      operationId: engineWriteContract
      tags:
        - Engine
      summary: Write to a contract via Engine.
      servers:
        - url: https://engine.thirdweb.com
      security:
        - SecretKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Transaction queued by Engine.
  /v1/read/contract:
    post:
      operationId: engineReadContract
      tags:
        - Engine
      summary: Read from a contract via Engine.
      servers:
        - url: https://engine.thirdweb.com
      security:
        - SecretKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Read result.
  /v1/accounts:
    get:
      operationId: engineListServerWallets
      tags:
        - Engine
      summary: List Engine server wallets.
      servers:
        - url: https://engine.thirdweb.com
      security:
        - SecretKeyAuth: []
      responses:
        '200':
          description: A list of server wallets.
    post:
      operationId: engineGetOrCreateServerWallet
      tags:
        - Engine
      summary: Get or create an Engine server wallet.
      servers:
        - url: https://engine.thirdweb.com
      security:
        - SecretKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Server wallet.
  /v1/events:
    get:
      operationId: insightGetEvents
      tags:
        - Insight
      summary: Get indexed on-chain events.
      servers:
        - url: https://insight.thirdweb.com
      security:
        - ClientAuth: []
        - SecretKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/InsightChainId'
      responses:
        '200':
          description: Indexed events.
  /v1/transactions/{contractAddress}:
    get:
      operationId: insightGetContractTransactions
      tags:
        - Insight
      summary: Get indexed transactions for a contract.
      servers:
        - url: https://insight.thirdweb.com
      security:
        - ClientAuth: []
        - SecretKeyAuth: []
      parameters:
        - name: contractAddress
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/InsightChainId'
      responses:
        '200':
          description: Indexed transactions.
  /v1/tokens/erc20/{ownerAddress}:
    get:
      operationId: insightGetErc20Balances
      tags:
        - Insight
      summary: Get ERC-20 balances for an address.
      servers:
        - url: https://insight.thirdweb.com
      security:
        - ClientAuth: []
        - SecretKeyAuth: []
      parameters:
        - name: ownerAddress
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/InsightChainId'
      responses:
        '200':
          description: ERC-20 balances.
  /v1/nfts/balance/{ownerAddress}:
    get:
      operationId: insightGetNftBalances
      tags:
        - Insight
      summary: Get NFT balances for an address.
      servers:
        - url: https://insight.thirdweb.com
      security:
        - ClientAuth: []
        - SecretKeyAuth: []
      parameters:
        - name: ownerAddress
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/InsightChainId'
      responses:
        '200':
          description: NFT balances.
  /v1/webhooks:
    get:
      operationId: insightListWebhooks
      tags:
        - Insight
      summary: List Insight webhooks.
      servers:
        - url: https://insight.thirdweb.com
      security:
        - ClientAuth: []
        - SecretKeyAuth: []
      responses:
        '200':
          description: A list of webhooks.
    post:
      operationId: insightCreateWebhook
      tags:
        - Insight
      summary: Create an Insight webhook for on-chain events.
      servers:
        - url: https://insight.thirdweb.com
      security:
        - ClientAuth: []
        - SecretKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreateRequest'
      responses:
        '201':
          description: Webhook created.
  /chat:
    post:
      operationId: nebulaChat
      tags:
        - Nebula
      summary: Send a message to a Nebula AI session.
      servers:
        - url: https://nebula-api.thirdweb.com
      security:
        - SecretKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Nebula response.
  /execute:
    post:
      operationId: nebulaExecute
      tags:
        - Nebula
      summary: Have Nebula execute an on-chain action.
      servers:
        - url: https://nebula-api.thirdweb.com
      security:
        - SecretKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Execution result.
  /session:
    post:
      operationId: nebulaCreateSession
      tags:
        - Nebula
      summary: Create a Nebula session.
      servers:
        - url: https://nebula-api.thirdweb.com
      security:
        - SecretKeyAuth: []
      responses:
        '200':
          description: Session created.
components:
  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.
  parameters:
    Address:
      name: address
      in: path
      required: true
      description: An EVM wallet or contract address.
      schema:
        type: string
    ChainId:
      name: chainId
      in: path
      required: true
      description: The numeric EVM chain ID.
      schema:
        type: integer
    InsightChainId:
      name: chain
      in: query
      required: false
      description: One or more chain IDs to scope the query.
      schema:
        type: integer
  schemas:
    AuthInitiateRequest:
      type: object
      properties:
        method:
          type: string
          description: Authentication method (e.g. email, phone, siwe, an OAuth provider).
        email:
          type: string
        phone:
          type: string
      required:
        - method
    AuthCompleteRequest:
      type: object
      properties:
        method:
          type: string
        code:
          type: string
          description: Verification code or signed payload completing the challenge.
      required:
        - method
    AuthResult:
      type: object
      properties:
        token:
          type: string
          description: JWT access token.
        walletAddress:
          type: string
        isNewUser:
          type: boolean
    Wallet:
      type: object
      properties:
        address:
          type: string
        smartWalletAddress:
          type: string
        createdAt:
          type: string
          format: date-time
    SignMessageRequest:
      type: object
      properties:
        from:
          type: string
          description: The wallet address signing the message.
        message:
          type: string
        chainId:
          type: integer
      required:
        - message
    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
    ContractCall:
      type: object
      properties:
        contractAddress:
          type: string
        method:
          type: string
          description: Function signature or name to call.
        params:
          type: array
          items: {}
      required:
        - contractAddress
        - method
    ContractReadRequest:
      type: object
      properties:
        chainId:
          type: integer
        calls:
          type: array
          items:
            $ref: '#/components/schemas/ContractCall'
      required:
        - chainId
        - calls
    ContractWriteRequest:
      type: object
      properties:
        chainId:
          type: integer
        from:
          type: string
          description: The wallet address sending the transactions.
        calls:
          type: array
          items:
            $ref: '#/components/schemas/ContractCall'
        idempotencyKey:
          type: string
      required:
        - chainId
        - calls
    CreateTokenRequest:
      type: object
      properties:
        chainId:
          type: integer
        name:
          type: string
        symbol:
          type: string
        description:
          type: string
        imageUrl:
          type: string
        owner:
          type: string
        maxSupply:
          type: string
      required:
        - chainId
        - name
        - symbol
        - description
        - imageUrl
    BridgeSwapRequest:
      type: object
      properties:
        tokenIn:
          type: object
          description: Source token (chainId and address).
        tokenOut:
          type: object
          description: Destination token (chainId and address).
        exact:
          type: string
          description: Exact input or output amount.
        from:
          type: string
        receiver:
          type: string
        slippageToleranceBps:
          type: integer
      required:
        - tokenIn
        - tokenOut
    TransactionResult:
      type: object
      properties:
        transactionId:
          type: string
        transactionHash:
          type: string
        chainId:
          type: integer
        status:
          type: string
          description: Queued, submitted, mined, or errored.
    WebhookCreateRequest:
      type: object
      properties:
        webhookUrl:
          type: string
        name:
          type: string
        filters:
          type: object
          description: Event/transaction filters scoping which on-chain activity triggers the webhook.
      required:
        - webhookUrl