Tether Token Balances API
Query current token balances for addresses
OpenAPI Specification
openapi: 3.2.0
info:
title: WDK Indexer Token Balances API
description: API for querying blockchain token transfers and balances across multiple networks. Authenticated
endpoints require an API key passed via the X-API-KEY header.
version: 1.0.0
tags:
- name: Token Balances
description: Query current token balances for addresses
paths:
/api/v1/{blockchain}/{token}/{address}/token-balances:
get:
summary: Get token balance for an address
tags:
- Token Balances
description: Retrieve the current token balance for a specific wallet address on a given blockchain.
Returns a single balance amount representing how much of the specified token the address currently
holds.
parameters:
- schema:
type: string
enum:
- ethereum
- arbitrum
- avalanche
- polygon
- sepolia
- tron
- ton
- bitcoin
- spark
in: path
name: blockchain
required: true
description: Blockchain network identifier. Use GET /api/v1/chains to see all available options.
- schema:
type: string
enum:
- usdt
- xaut
- usat
- btc
in: path
name: token
required: true
description: Token identifier. Must be a valid token for the specified blockchain.
- schema:
type: string
minLength: 1
in: path
name: address
required: true
description: Wallet address to query. Format varies by blockchain (e.g. 0x... for EVM, bc1...
for Bitcoin, T... for Tron).
security:
- ApiKeyAuth: []
responses:
'200':
description: Current token balance for the queried address
content:
application/json:
schema:
description: Current token balance for the queried address
type: object
properties:
tokenBalance:
type: object
description: Balance information.
properties:
blockchain:
type: string
description: Blockchain queried.
token:
type: string
description: Token queried.
amount:
type: string
description: Current balance as a decimal string.
additionalProperties: false
additionalProperties: false
'400':
description: Bad Request - invalid parameters, address format, blockchain, or token
content:
application/json:
schema:
description: Bad Request - invalid parameters, address format, blockchain, or token
type: object
properties:
error:
type: string
description: Error type
message:
type: string
description: Human-readable error description
status:
type: number
description: HTTP status code
additionalProperties: false
'401':
description: Unauthorized - expired API key
content:
application/json:
schema:
description: Unauthorized - expired API key
type: object
properties:
error:
type: string
description: Authentication error type
message:
type: string
description: Authentication error details
status:
type: number
description: HTTP status code
additionalProperties: false
'403':
description: Forbidden - missing or invalid API key
content:
application/json:
schema:
description: Forbidden - missing or invalid API key
type: object
properties:
error:
type: string
description: Authorization error type
message:
type: string
description: Authorization error details
status:
type: number
description: HTTP status code
additionalProperties: false
'429':
description: Too Many Requests - rate limit exceeded
content:
application/json:
schema:
description: Too Many Requests - rate limit exceeded
type: object
properties:
error:
type: string
description: Rate limit error type
message:
type: string
description: Rate limit error details
status:
type: number
description: HTTP status code
additionalProperties: false
'500':
description: Internal Server Error - indexer service unavailable or unexpected failure
content:
application/json:
schema:
description: Internal Server Error - indexer service unavailable or unexpected failure
type: object
properties:
error:
type: string
description: Error type
message:
type: string
description: Error details
status:
type: number
description: HTTP status code
additionalProperties: false
/api/v1/batch/token-balances:
post:
summary: Get token balances for multiple addresses
tags:
- Token Balances
description: Retrieve the current token balance for multiple addresses in a single request. Each
item in the batch is processed independently - if one item fails (e.g. invalid address), the others
still return results. The response array maintains the same order as the request. Maximum 10 items
per batch.
requestBody:
required: true
content:
application/json:
schema:
type: array
description: Array of balance query objects. Maximum 10 items.
minItems: 1
maxItems: 10
items:
type: object
properties:
blockchain:
type: string
enum:
- ethereum
- arbitrum
- avalanche
- polygon
- sepolia
- tron
- ton
- bitcoin
- spark
description: Blockchain network identifier.
token:
type: string
enum:
- usdt
- xaut
- usat
- btc
description: Token identifier.
address:
type: string
minLength: 1
description: Wallet address to query.
required:
- blockchain
- token
- address
additionalProperties: false
description: Array of balance query objects. Maximum 10 items.
security:
- ApiKeyAuth: []
responses:
'200':
description: Array of results in the same order as the request. Each element is either a balance
result or an error object.
content:
application/json:
schema:
description: Array of results in the same order as the request. Each element is either
a balance result or an error object.
type: array
items:
oneOf:
- description: Current token balance for the queried address
type: object
properties:
tokenBalance:
type: object
description: Balance information.
properties:
blockchain:
type: string
description: Blockchain queried.
token:
type: string
description: Token queried.
amount:
type: string
description: Current balance as a decimal string.
additionalProperties: false
additionalProperties: false
- type: object
properties:
error:
type: string
message:
type: string
status:
type: number
additionalProperties: false
'400':
description: Bad Request - invalid parameters, address format, blockchain, or token
content:
application/json:
schema:
description: Bad Request - invalid parameters, address format, blockchain, or token
type: object
properties:
error:
type: string
description: Error type
message:
type: string
description: Human-readable error description
status:
type: number
description: HTTP status code
additionalProperties: false
'401':
description: Unauthorized - expired API key
content:
application/json:
schema:
description: Unauthorized - expired API key
type: object
properties:
error:
type: string
description: Authentication error type
message:
type: string
description: Authentication error details
status:
type: number
description: HTTP status code
additionalProperties: false
'403':
description: Forbidden - missing or invalid API key
content:
application/json:
schema:
description: Forbidden - missing or invalid API key
type: object
properties:
error:
type: string
description: Authorization error type
message:
type: string
description: Authorization error details
status:
type: number
description: HTTP status code
additionalProperties: false
'429':
description: Too Many Requests - rate limit exceeded
content:
application/json:
schema:
description: Too Many Requests - rate limit exceeded
type: object
properties:
error:
type: string
description: Rate limit error type
message:
type: string
description: Rate limit error details
status:
type: number
description: HTTP status code
additionalProperties: false
'500':
description: Internal Server Error - indexer service unavailable or unexpected failure
content:
application/json:
schema:
description: Internal Server Error - indexer service unavailable or unexpected failure
type: object
properties:
error:
type: string
description: Error type
message:
type: string
description: Error details
status:
type: number
description: HTTP status code
additionalProperties: false
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
description: API key obtained via the registration form. Include in the X-API-KEY header for all
authenticated requests.