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: 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