API Reference
Complete reference for the WDK Indexer REST API
Download OpenAPI · Snapshot provenance · Request an API key
Replace placeholders in the cURL templates before running. For requests with a body, save your payload in request.json. Response examples illustrate the schema and are not captured API responses.
Text reference and complete schemas (available while the viewer loads)
Base URL
https://wdk-api.tether.ioExplore all 14 operations below. Use chain discovery to find current blockchain and token identifiers.
Download OpenAPI · Snapshot provenance
Authentication
Authentication requirements are listed under each endpoint. Send your API key in the documented header for protected endpoints. Request an API key.
API Endpoints
GET /api/v1/health
Deep health check endpoint
Checks internal dependencies and blockchain indexer sync status. Returns HTTP 200 only when the overall status is `healthy`. Returns HTTP 503 for any non-healthy overall status (`degraded` or `unhealthy`), so readiness probes and load balancers can rely on the HTTP status code alone.
Authentication: Public endpoint.
Example request
Replace path placeholders and the API key before running.
curl --request GET 'https://wdk-api.tether.io/api/v1/health'Responses
| Status | Description |
|---|---|
200 | Default Response |
503 | Default Response |
Response fields · HTTP 200 · application/json
| Field | Type | Details |
|---|---|---|
$ | object | — |
$.status | string | Allowed values: "healthy", "degraded", "unhealthy". Example: "healthy". |
$.timestamp | string | Format: "date-time". |
$.deployEnvironment | string | Example: "production". |
$.deployedVersion | string | Example: "1.1.2". |
$.summary | object | — |
$.summary.healthy | integer | Example: 10. |
$.summary.unhealthy | integer | Example: 2. |
$.summary.total | integer | Example: 12. |
$.checks | object | — |
$.checks.dependencies | object | — |
$.checks.dependencies.status | string | Allowed values: "healthy", "unhealthy". Example: "healthy". |
$.checks.indexers | object | — |
$.checks.indexers.* | object | — |
$.checks.indexers.*.status | string | Allowed values: "healthy", "unhealthy". Example: "healthy". |
$.checks.indexers.*.rpcLatencyMs | number | Example: 45. |
$.checks.indexers.*.lag | number | Example: 3. |
$.checks.indexers.*.dependencies | object | — |
$.checks.indexers.*.dependencies.status | string | Allowed values: "healthy", "unhealthy". Example: "healthy". |
Full endpoint schema (JSON)
{
"method": "GET",
"path": "/api/v1/health",
"operation": {
"summary": "Deep health check endpoint",
"tags": [
"Health"
],
"description": "Checks internal dependencies and blockchain indexer sync status. Returns HTTP 200 only when the overall status is `healthy`. Returns HTTP 503 for any non-healthy overall status (`degraded` or `unhealthy`), so readiness probes and load balancers can rely on the HTTP status code alone.",
"responses": {
"200": {
"description": "Default Response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"healthy",
"degraded",
"unhealthy"
],
"example": "healthy"
},
"timestamp": {
"type": "string",
"format": "date-time"
},
"deployEnvironment": {
"type": "string",
"example": "production"
},
"deployedVersion": {
"type": "string",
"example": "1.1.2"
},
"summary": {
"type": "object",
"properties": {
"healthy": {
"type": "integer",
"example": 10
},
"unhealthy": {
"type": "integer",
"example": 2
},
"total": {
"type": "integer",
"example": 12
}
}
},
"checks": {
"type": "object",
"properties": {
"dependencies": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"healthy",
"unhealthy"
],
"example": "healthy"
}
}
},
"indexers": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"healthy",
"unhealthy"
],
"example": "healthy"
},
"rpcLatencyMs": {
"type": "number",
"example": 45
},
"lag": {
"type": "number",
"example": 3
},
"dependencies": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"healthy",
"unhealthy"
],
"example": "healthy"
}
}
}
}
}
}
}
}
}
}
}
}
},
"503": {
"description": "Default Response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"healthy",
"degraded",
"unhealthy"
],
"example": "healthy"
},
"timestamp": {
"type": "string",
"format": "date-time"
},
"deployEnvironment": {
"type": "string",
"example": "production"
},
"deployedVersion": {
"type": "string",
"example": "1.1.2"
},
"summary": {
"type": "object",
"properties": {
"healthy": {
"type": "integer",
"example": 10
},
"unhealthy": {
"type": "integer",
"example": 2
},
"total": {
"type": "integer",
"example": 12
}
}
},
"checks": {
"type": "object",
"properties": {
"dependencies": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"healthy",
"unhealthy"
],
"example": "healthy"
}
}
},
"indexers": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"healthy",
"unhealthy"
],
"example": "healthy"
},
"rpcLatencyMs": {
"type": "number",
"example": 45
},
"lag": {
"type": "number",
"example": 3
},
"dependencies": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"healthy",
"unhealthy"
],
"example": "healthy"
}
}
}
}
}
}
}
}
}
}
}
}
}
}
},
"pathParameters": [],
"security": [],
"securitySchemes": {}
}GET /api/v1/chains
Get supported blockchains and tokens
Returns the list of all supported blockchains and their available tokens. Endpoint to discover valid blockchain and token combinations before calling other endpoints. This endpoint reads directly from the server configuration and requires no authentication.
Authentication: Public endpoint.
Example request
Replace path placeholders and the API key before running.
curl --request GET 'https://wdk-api.tether.io/api/v1/chains'Responses
| Status | Description |
|---|---|
200 | List of supported blockchains with their tokens and case sensitivity rules |
500 | Internal Server Error - indexer service unavailable or unexpected failure |
Response fields · HTTP 200 · application/json
| Field | Type | Details |
|---|---|---|
$ | object | List of supported blockchains with their tokens and case sensitivity rules |
$.chains | array | All supported blockchains. |
$.chains[] | object | — |
$.chains[].name | string | Required. Blockchain identifier used as the {blockchain} path parameter in other endpoints. |
$.chains[].tokens | array | Required. Token identifiers available on this blockchain, used as the {token} path parameter. |
$.chains[].tokens[] | string | — |
$.chains[].caseSensitive | object | Case sensitivity rules. If present, addresses are preserved as-is (case-sensitive). If absent, addresses are automatically lowercased. |
$.chains[].caseSensitive.address | oneOf | Indicates address case sensitivity. When the caseSensitive object is present, addresses are not lowercased regardless of this field value. |
$.chains[].caseSensitive.address (oneOf 1) | boolean | — |
$.chains[].caseSensitive.address (oneOf 2) | string | — |
$.chains[].caseSensitive.tx | boolean | true = transaction hashes are case-sensitive. |
$.chains[].caseSensitive.block | boolean | true = block identifiers are case-sensitive. |
Other response fields: $.error, $.message, $.status. See the full schema for each status.
Full endpoint schema (JSON)
{
"method": "GET",
"path": "/api/v1/chains",
"operation": {
"summary": "Get supported blockchains and tokens",
"tags": [
"Chains"
],
"description": "Returns the list of all supported blockchains and their available tokens. Endpoint to discover valid blockchain and token combinations before calling other endpoints. This endpoint reads directly from the server configuration and requires no authentication.",
"responses": {
"200": {
"description": "List of supported blockchains with their tokens and case sensitivity rules",
"content": {
"application/json": {
"schema": {
"description": "List of supported blockchains with their tokens and case sensitivity rules",
"type": "object",
"properties": {
"chains": {
"type": "array",
"description": "All supported blockchains.",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Blockchain identifier used as the {blockchain} path parameter in other endpoints."
},
"tokens": {
"type": "array",
"description": "Token identifiers available on this blockchain, used as the {token} path parameter.",
"items": {
"type": "string"
}
},
"caseSensitive": {
"type": "object",
"description": "Case sensitivity rules. If present, addresses are preserved as-is (case-sensitive). If absent, addresses are automatically lowercased.",
"properties": {
"address": {
"oneOf": [
{
"type": "boolean"
},
{
"type": "string"
}
],
"description": "Indicates address case sensitivity. When the caseSensitive object is present, addresses are not lowercased regardless of this field value."
},
"tx": {
"type": "boolean",
"description": "true = transaction hashes are case-sensitive."
},
"block": {
"type": "boolean",
"description": "true = block identifiers are case-sensitive."
}
},
"additionalProperties": false
}
},
"required": [
"name",
"tokens"
],
"additionalProperties": false
}
}
},
"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
}
}
}
}
}
},
"pathParameters": [],
"security": [],
"securitySchemes": {}
}GET /api/v1/{blockchain}/{token}/{address}/token-transfers
Get token transfers for an address
Retrieve the token transfer history for a specific wallet address on a given blockchain. Returns incoming and outgoing transfers sorted by block number.
Authentication: X-API-KEY header required.
Parameters
| Name | Type | Details |
|---|---|---|
limit (query) | integer | Required: No. Maximum number of transfers to return. Minimum: 1. Maximum: 1000. Default: 10. |
fromTs (query) | integer | Required: No. Start timestamp in milliseconds (inclusive). Use 0 to query from the beginning. Minimum: 0. Default: 0. |
toTs (query) | integer | Required: No. End timestamp in milliseconds (inclusive). Omit to query up to the latest available data. Minimum: 0. |
blockchain (path) | string | Required: Yes. Blockchain network identifier. Use GET /api/v1/chains to see all available options. Allowed values: "ethereum", "arbitrum", "avalanche", "polygon", "plasma", "sepolia", "tron", "ton", "bitcoin", "spark". |
token (path) | string | Required: Yes. Token identifier. Must be a valid token for the specified blockchain. Allowed values: "usdt", "xaut", "usat", "btc". |
address (path) | string | Required: Yes. Wallet address to query. Format varies by blockchain (e.g. 0x... for EVM, bc1... for Bitcoin, T... for Tron). Min length: 1. |
Example request
Replace path placeholders and the API key before running.
curl --request GET 'https://wdk-api.tether.io/api/v1/{blockchain}/{token}/{address}/token-transfers' \
--header 'X-API-KEY: <api-key>'Responses
| Status | Description |
|---|---|
200 | Token transfer history for the queried address |
400 | Bad Request - invalid parameters, address format, blockchain, or token |
401 | Unauthorized - expired API key |
403 | Forbidden - missing or invalid API key |
429 | Too Many Requests - rate limit exceeded |
500 | Internal Server Error - indexer service unavailable or unexpected failure |
Response fields · HTTP 200 · application/json
| Field | Type | Details |
|---|---|---|
$ | object | Token transfer history for the queried address |
$.transfers | array | List of token transfers sorted by block number. |
$.transfers[] | object | — |
$.transfers[].blockchain | string | Blockchain where the transfer occurred. |
$.transfers[].blockNumber | integer | Block number containing the transfer. |
$.transfers[].transactionHash | string | Hash of the transaction. |
$.transfers[].transferIndex | integer | Index of the transfer within the transaction. |
$.transfers[].token | string | Token identifier. |
$.transfers[].amount | string | Transfer amount as a decimal string. |
$.transfers[].timestamp | integer | Block timestamp in milliseconds since Unix epoch. |
$.transfers[].transactionIndex | oneOf | Position of the transaction within the block. |
$.transfers[].transactionIndex (oneOf 1) | integer | — |
$.transfers[].transactionIndex (oneOf 2) | null | — |
$.transfers[].logIndex | oneOf | Event log index for EVM chains. null for non-EVM chains like Bitcoin. |
$.transfers[].logIndex (oneOf 1) | integer | — |
$.transfers[].logIndex (oneOf 2) | null | — |
$.transfers[].from | oneOf | Sender wallet address. |
$.transfers[].from (oneOf 1) | string | — |
$.transfers[].from (oneOf 2) | null | — |
$.transfers[].to | oneOf | The recipient's address |
$.transfers[].to (oneOf 1) | string | — |
$.transfers[].to (oneOf 2) | null | — |
$.transfers[].label | string | A label associated with the transfer, if any |
$.transfers[].metadata | oneOf | Chain-specific extra data attached to the transfer, if any. |
$.transfers[].metadata (oneOf 1) | object | — |
$.transfers[].metadata (oneOf 2) | null | — |
Other response fields: $.error, $.message, $.status. See the full schema for each status.
Full endpoint schema (JSON)
{
"method": "GET",
"path": "/api/v1/{blockchain}/{token}/{address}/token-transfers",
"operation": {
"summary": "Get token transfers for an address",
"tags": [
"Token Transfers"
],
"description": "Retrieve the token transfer history for a specific wallet address on a given blockchain. Returns incoming and outgoing transfers sorted by block number.",
"parameters": [
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 10
},
"in": "query",
"name": "limit",
"required": false,
"description": "Maximum number of transfers to return."
},
{
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"in": "query",
"name": "fromTs",
"required": false,
"description": "Start timestamp in milliseconds (inclusive). Use 0 to query from the beginning."
},
{
"schema": {
"type": "integer",
"minimum": 0
},
"in": "query",
"name": "toTs",
"required": false,
"description": "End timestamp in milliseconds (inclusive). Omit to query up to the latest available data."
},
{
"schema": {
"type": "string",
"enum": [
"ethereum",
"arbitrum",
"avalanche",
"polygon",
"plasma",
"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": "Token transfer history for the queried address",
"content": {
"application/json": {
"schema": {
"description": "Token transfer history for the queried address",
"type": "object",
"properties": {
"transfers": {
"type": "array",
"description": "List of token transfers sorted by block number.",
"items": {
"type": "object",
"properties": {
"blockchain": {
"type": "string",
"description": "Blockchain where the transfer occurred."
},
"blockNumber": {
"type": "integer",
"description": "Block number containing the transfer."
},
"transactionHash": {
"type": "string",
"description": "Hash of the transaction."
},
"transferIndex": {
"type": "integer",
"description": "Index of the transfer within the transaction."
},
"token": {
"type": "string",
"description": "Token identifier."
},
"amount": {
"type": "string",
"description": "Transfer amount as a decimal string."
},
"timestamp": {
"type": "integer",
"description": "Block timestamp in milliseconds since Unix epoch."
},
"transactionIndex": {
"oneOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Position of the transaction within the block."
},
"logIndex": {
"oneOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Event log index for EVM chains. null for non-EVM chains like Bitcoin."
},
"from": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Sender wallet address."
},
"to": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The recipient's address"
},
"label": {
"type": "string",
"description": "A label associated with the transfer, if any"
},
"metadata": {
"oneOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"description": "Chain-specific extra data attached to the transfer, if any."
}
},
"additionalProperties": true
}
}
},
"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
}
}
}
}
}
},
"pathParameters": [],
"security": [
{
"ApiKeyAuth": []
}
],
"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."
}
}
}GET /api/v1/{blockchain}/{token}/{address}/token-balances
Get token balance for an address
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.
Authentication: X-API-KEY header required.
Parameters
| Name | Type | Details |
|---|---|---|
blockchain (path) | string | Required: Yes. Blockchain network identifier. Use GET /api/v1/chains to see all available options. Allowed values: "ethereum", "arbitrum", "avalanche", "polygon", "plasma", "sepolia", "tron", "ton", "bitcoin", "spark". |
token (path) | string | Required: Yes. Token identifier. Must be a valid token for the specified blockchain. Allowed values: "usdt", "xaut", "usat", "btc". |
address (path) | string | Required: Yes. Wallet address to query. Format varies by blockchain (e.g. 0x... for EVM, bc1... for Bitcoin, T... for Tron). Min length: 1. |
Example request
Replace path placeholders and the API key before running.
curl --request GET 'https://wdk-api.tether.io/api/v1/{blockchain}/{token}/{address}/token-balances' \
--header 'X-API-KEY: <api-key>'Responses
| Status | Description |
|---|---|
200 | Current token balance for the queried address |
400 | Bad Request - invalid parameters, address format, blockchain, or token |
401 | Unauthorized - expired API key |
403 | Forbidden - missing or invalid API key |
429 | Too Many Requests - rate limit exceeded |
500 | Internal Server Error - indexer service unavailable or unexpected failure |
Response fields · HTTP 200 · application/json
| Field | Type | Details |
|---|---|---|
$ | object | Current token balance for the queried address |
$.tokenBalance | object | Balance information. |
$.tokenBalance.blockchain | string | Blockchain queried. |
$.tokenBalance.token | string | Token queried. |
$.tokenBalance.amount | string | Current balance as a decimal string. |
Other response fields: $.error, $.message, $.status. See the full schema for each status.
Full endpoint schema (JSON)
{
"method": "GET",
"path": "/api/v1/{blockchain}/{token}/{address}/token-balances",
"operation": {
"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",
"plasma",
"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
}
}
}
}
}
},
"pathParameters": [],
"security": [
{
"ApiKeyAuth": []
}
],
"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."
}
}
}GET /api/v1/blockchains/{blockchain}/{token}/token-transfers/{transactionHash}
Get transfers for a transaction
Retrieve the transfer records of a single transaction for one token, read from the chain. Only transfers of the requested token are returned, so a transaction moving several tokens has to be queried once per token. Returns 404 when the transaction moved no amount of that token, including when the transaction id does not exist at all.
Authentication: X-API-KEY header required.
Parameters
| Name | Type | Details |
|---|---|---|
blockchain (path) | string | Required: Yes. Blockchain network identifier. Use GET /api/v1/chains to see all available options. Allowed values: "ethereum", "arbitrum", "avalanche", "polygon", "plasma", "sepolia", "tron", "ton", "bitcoin", "spark". |
token (path) | string | Required: Yes. Token identifier. Must be a valid token for the specified blockchain. Allowed values: "usdt", "xaut", "usat", "btc". |
transactionHash (path) | string | Required: Yes. Transaction id/hash, as returned in the `transactionHash` field of transfers. Format varies by blockchain (e.g. 0x... for EVM, hex for TON, base58 signature for Solana). Min length: 1. Max length: 255. |
Example request
Replace path placeholders and the API key before running.
curl --request GET 'https://wdk-api.tether.io/api/v1/blockchains/{blockchain}/{token}/token-transfers/{transactionHash}' \
--header 'X-API-KEY: <api-key>'Responses
| Status | Description |
|---|---|
200 | Transfer records for the queried transaction |
400 | Bad Request - invalid parameters, address format, blockchain, or token |
401 | Unauthorized - expired API key |
403 | Forbidden - missing or invalid API key |
404 | Not Found - the transaction has no transfers of the requested token |
429 | Too Many Requests - rate limit exceeded |
500 | Internal Server Error - indexer service unavailable or unexpected failure |
Response fields · HTTP 200 · application/json
| Field | Type | Details |
|---|---|---|
$ | object | Transfer records for the queried transaction |
$.transfers | array | All transfers recorded under this transaction for the requested token. |
$.transfers[] | object | — |
$.transfers[].blockchain | string | Blockchain where the transfer occurred. |
$.transfers[].blockNumber | integer | Block number containing the transfer. |
$.transfers[].transactionHash | string | Hash of the transaction. |
$.transfers[].transferIndex | integer | Index of the transfer within the transaction. |
$.transfers[].token | string | Token identifier. |
$.transfers[].amount | string | Transfer amount as a decimal string. |
$.transfers[].timestamp | integer | Block timestamp in milliseconds since Unix epoch. |
$.transfers[].transactionIndex | oneOf | Position of the transaction within the block. |
$.transfers[].transactionIndex (oneOf 1) | integer | — |
$.transfers[].transactionIndex (oneOf 2) | null | — |
$.transfers[].logIndex | oneOf | Event log index for EVM chains. null for non-EVM chains like Bitcoin. |
$.transfers[].logIndex (oneOf 1) | integer | — |
$.transfers[].logIndex (oneOf 2) | null | — |
$.transfers[].from | oneOf | Sender wallet address. |
$.transfers[].from (oneOf 1) | string | — |
$.transfers[].from (oneOf 2) | null | — |
$.transfers[].to | oneOf | The recipient's address |
$.transfers[].to (oneOf 1) | string | — |
$.transfers[].to (oneOf 2) | null | — |
$.transfers[].label | string | A label associated with the transfer, if any |
$.transfers[].metadata | oneOf | Chain-specific extra data attached to the transfer, if any. |
$.transfers[].metadata (oneOf 1) | object | — |
$.transfers[].metadata (oneOf 2) | null | — |
Other response fields: $.error, $.message, $.status. See the full schema for each status.
Full endpoint schema (JSON)
{
"method": "GET",
"path": "/api/v1/blockchains/{blockchain}/{token}/token-transfers/{transactionHash}",
"operation": {
"summary": "Get transfers for a transaction",
"tags": [
"Token Transfers"
],
"description": "Retrieve the transfer records of a single transaction for one token, read from the chain. Only transfers of the requested token are returned, so a transaction moving several tokens has to be queried once per token. Returns 404 when the transaction moved no amount of that token, including when the transaction id does not exist at all.",
"parameters": [
{
"schema": {
"type": "string",
"enum": [
"ethereum",
"arbitrum",
"avalanche",
"polygon",
"plasma",
"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,
"maxLength": 255
},
"in": "path",
"name": "transactionHash",
"required": true,
"description": "Transaction id/hash, as returned in the `transactionHash` field of transfers. Format varies by blockchain (e.g. 0x... for EVM, hex for TON, base58 signature for Solana)."
}
],
"security": [
{
"ApiKeyAuth": []
}
],
"responses": {
"200": {
"description": "Transfer records for the queried transaction",
"content": {
"application/json": {
"schema": {
"description": "Transfer records for the queried transaction",
"type": "object",
"properties": {
"transfers": {
"type": "array",
"description": "All transfers recorded under this transaction for the requested token.",
"items": {
"type": "object",
"properties": {
"blockchain": {
"type": "string",
"description": "Blockchain where the transfer occurred."
},
"blockNumber": {
"type": "integer",
"description": "Block number containing the transfer."
},
"transactionHash": {
"type": "string",
"description": "Hash of the transaction."
},
"transferIndex": {
"type": "integer",
"description": "Index of the transfer within the transaction."
},
"token": {
"type": "string",
"description": "Token identifier."
},
"amount": {
"type": "string",
"description": "Transfer amount as a decimal string."
},
"timestamp": {
"type": "integer",
"description": "Block timestamp in milliseconds since Unix epoch."
},
"transactionIndex": {
"oneOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Position of the transaction within the block."
},
"logIndex": {
"oneOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Event log index for EVM chains. null for non-EVM chains like Bitcoin."
},
"from": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Sender wallet address."
},
"to": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The recipient's address"
},
"label": {
"type": "string",
"description": "A label associated with the transfer, if any"
},
"metadata": {
"oneOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"description": "Chain-specific extra data attached to the transfer, if any."
}
},
"additionalProperties": true
}
}
},
"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
}
}
}
},
"404": {
"description": "Not Found - the transaction has no transfers of the requested token",
"content": {
"application/json": {
"schema": {
"description": "Not Found - the transaction has no transfers of the requested token",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error type"
},
"message": {
"type": "string",
"description": "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
}
}
}
}
}
},
"pathParameters": [],
"security": [
{
"ApiKeyAuth": []
}
],
"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."
}
}
}POST /api/v1/batch/token-transfers
Get token transfers for multiple addresses
Retrieve token transfer history 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.
Authentication: X-API-KEY header required.
Request body · application/json · Required
Array of transfer query objects. Maximum 10 items.
| Field | Type | Details |
|---|---|---|
$ | array | Array of transfer query objects. Maximum 10 items. Min items: 1. Max items: 10. |
$[] | object | — |
$[].blockchain | string | Required. Blockchain network identifier. Allowed values: "ethereum", "arbitrum", "avalanche", "polygon", "plasma", "sepolia", "tron", "ton", "bitcoin", "spark". |
$[].token | string | Required. Token identifier. Allowed values: "usdt", "xaut", "usat", "btc". |
$[].address | string | Required. Wallet address to query. Min length: 1. |
$[].limit | integer | Maximum number of transfers to return for this address. Minimum: 1. Maximum: 1000. Default: 10. |
$[].fromTs | integer | Start timestamp in milliseconds (inclusive). Minimum: 0. Default: 0. |
$[].toTs | integer | End timestamp in milliseconds (inclusive). Minimum: 0. |
Example request
Replace path placeholders and the API key before running. Save your request body in request.json using the fields above.
curl --request POST 'https://wdk-api.tether.io/api/v1/batch/token-transfers' \
--header 'X-API-KEY: <api-key>' \
--header 'Content-Type: application/json' \
--data-binary @request.jsonResponses
| Status | Description |
|---|---|
200 | Array of results in the same order as the request. Each element is either a transfer result or an error object. |
400 | Bad Request - invalid parameters, address format, blockchain, or token |
401 | Unauthorized - expired API key |
403 | Forbidden - missing or invalid API key |
429 | Too Many Requests - rate limit exceeded |
500 | Internal Server Error - indexer service unavailable or unexpected failure |
Response fields · HTTP 200 · application/json
| Field | Type | Details |
|---|---|---|
$ | array | Array of results in the same order as the request. Each element is either a transfer result or an error object. Min items: 1. |
$[] | oneOf | — |
$[] (oneOf 1) | object | Token transfer history for the queried address |
$[] (oneOf 1).transfers | array | List of token transfers sorted by block number. |
$[] (oneOf 1).transfers[] | object | — |
$[] (oneOf 1).transfers[].blockchain | string | Blockchain where the transfer occurred. |
$[] (oneOf 1).transfers[].blockNumber | integer | Block number containing the transfer. |
$[] (oneOf 1).transfers[].transactionHash | string | Hash of the transaction. |
$[] (oneOf 1).transfers[].transferIndex | integer | Index of the transfer within the transaction. |
$[] (oneOf 1).transfers[].token | string | Token identifier. |
$[] (oneOf 1).transfers[].amount | string | Transfer amount as a decimal string. |
$[] (oneOf 1).transfers[].timestamp | integer | Block timestamp in milliseconds since Unix epoch. |
$[] (oneOf 1).transfers[].transactionIndex | oneOf | Position of the transaction within the block. |
$[] (oneOf 1).transfers[].transactionIndex (oneOf 1) | integer | — |
$[] (oneOf 1).transfers[].transactionIndex (oneOf 2) | null | — |
$[] (oneOf 1).transfers[].logIndex | oneOf | Event log index for EVM chains. null for non-EVM chains like Bitcoin. |
$[] (oneOf 1).transfers[].logIndex (oneOf 1) | integer | — |
$[] (oneOf 1).transfers[].logIndex (oneOf 2) | null | — |
$[] (oneOf 1).transfers[].from | oneOf | Sender wallet address. |
$[] (oneOf 1).transfers[].from (oneOf 1) | string | — |
$[] (oneOf 1).transfers[].from (oneOf 2) | null | — |
$[] (oneOf 1).transfers[].to | oneOf | The recipient's address |
$[] (oneOf 1).transfers[].to (oneOf 1) | string | — |
$[] (oneOf 1).transfers[].to (oneOf 2) | null | — |
$[] (oneOf 1).transfers[].label | string | A label associated with the transfer, if any |
$[] (oneOf 1).transfers[].metadata | oneOf | Chain-specific extra data attached to the transfer, if any. |
$[] (oneOf 1).transfers[].metadata (oneOf 1) | object | — |
$[] (oneOf 1).transfers[].metadata (oneOf 2) | null | — |
$[] (oneOf 2) | object | — |
$[] (oneOf 2).error | string | — |
$[] (oneOf 2).message | string | — |
$[] (oneOf 2).status | number | — |
Other response fields: $.error, $.message, $.status. See the full schema for each status.
Full endpoint schema (JSON)
{
"method": "POST",
"path": "/api/v1/batch/token-transfers",
"operation": {
"summary": "Get token transfers for multiple addresses",
"tags": [
"Token Transfers"
],
"description": "Retrieve token transfer history 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 transfer query objects. Maximum 10 items.",
"minItems": 1,
"maxItems": 10,
"items": {
"type": "object",
"properties": {
"blockchain": {
"type": "string",
"enum": [
"ethereum",
"arbitrum",
"avalanche",
"polygon",
"plasma",
"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."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 10,
"description": "Maximum number of transfers to return for this address."
},
"fromTs": {
"type": "integer",
"minimum": 0,
"default": 0,
"description": "Start timestamp in milliseconds (inclusive)."
},
"toTs": {
"type": "integer",
"minimum": 0,
"description": "End timestamp in milliseconds (inclusive)."
}
},
"required": [
"blockchain",
"token",
"address"
],
"additionalProperties": false
}
}
}
},
"description": "Array of transfer 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 transfer 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 transfer result or an error object.",
"type": "array",
"items": {
"oneOf": [
{
"description": "Token transfer history for the queried address",
"type": "object",
"properties": {
"transfers": {
"type": "array",
"description": "List of token transfers sorted by block number.",
"items": {
"type": "object",
"properties": {
"blockchain": {
"type": "string",
"description": "Blockchain where the transfer occurred."
},
"blockNumber": {
"type": "integer",
"description": "Block number containing the transfer."
},
"transactionHash": {
"type": "string",
"description": "Hash of the transaction."
},
"transferIndex": {
"type": "integer",
"description": "Index of the transfer within the transaction."
},
"token": {
"type": "string",
"description": "Token identifier."
},
"amount": {
"type": "string",
"description": "Transfer amount as a decimal string."
},
"timestamp": {
"type": "integer",
"description": "Block timestamp in milliseconds since Unix epoch."
},
"transactionIndex": {
"oneOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Position of the transaction within the block."
},
"logIndex": {
"oneOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Event log index for EVM chains. null for non-EVM chains like Bitcoin."
},
"from": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Sender wallet address."
},
"to": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The recipient's address"
},
"label": {
"type": "string",
"description": "A label associated with the transfer, if any"
},
"metadata": {
"oneOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"description": "Chain-specific extra data attached to the transfer, if any."
}
},
"additionalProperties": true
}
}
},
"additionalProperties": false
},
{
"type": "object",
"properties": {
"error": {
"type": "string"
},
"message": {
"type": "string"
},
"status": {
"type": "number"
}
},
"additionalProperties": false
}
]
},
"minItems": 1
}
}
}
},
"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
}
}
}
}
}
},
"pathParameters": [],
"security": [
{
"ApiKeyAuth": []
}
],
"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."
}
}
}POST /api/v1/batch/token-balances
Get token balances for multiple addresses
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.
Authentication: X-API-KEY header required.
Request body · application/json · Required
Array of balance query objects. Maximum 10 items.
| Field | Type | Details |
|---|---|---|
$ | array | Array of balance query objects. Maximum 10 items. Min items: 1. Max items: 10. |
$[] | object | — |
$[].blockchain | string | Required. Blockchain network identifier. Allowed values: "ethereum", "arbitrum", "avalanche", "polygon", "plasma", "sepolia", "tron", "ton", "bitcoin", "spark". |
$[].token | string | Required. Token identifier. Allowed values: "usdt", "xaut", "usat", "btc". |
$[].address | string | Required. Wallet address to query. Min length: 1. |
Example request
Replace path placeholders and the API key before running. Save your request body in request.json using the fields above.
curl --request POST 'https://wdk-api.tether.io/api/v1/batch/token-balances' \
--header 'X-API-KEY: <api-key>' \
--header 'Content-Type: application/json' \
--data-binary @request.jsonResponses
| Status | Description |
|---|---|
200 | Array of results in the same order as the request. Each element is either a balance result or an error object. |
400 | Bad Request - invalid parameters, address format, blockchain, or token |
401 | Unauthorized - expired API key |
403 | Forbidden - missing or invalid API key |
429 | Too Many Requests - rate limit exceeded |
500 | Internal Server Error - indexer service unavailable or unexpected failure |
Response fields · HTTP 200 · application/json
| Field | Type | Details |
|---|---|---|
$ | array | Array of results in the same order as the request. Each element is either a balance result or an error object. |
$[] | oneOf | — |
$[] (oneOf 1) | object | Current token balance for the queried address |
$[] (oneOf 1).tokenBalance | object | Balance information. |
$[] (oneOf 1).tokenBalance.blockchain | string | Blockchain queried. |
$[] (oneOf 1).tokenBalance.token | string | Token queried. |
$[] (oneOf 1).tokenBalance.amount | string | Current balance as a decimal string. |
$[] (oneOf 2) | object | — |
$[] (oneOf 2).error | string | — |
$[] (oneOf 2).message | string | — |
$[] (oneOf 2).status | number | — |
Other response fields: $.error, $.message, $.status. See the full schema for each status.
Full endpoint schema (JSON)
{
"method": "POST",
"path": "/api/v1/batch/token-balances",
"operation": {
"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",
"plasma",
"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
}
}
}
}
}
},
"pathParameters": [],
"security": [
{
"ApiKeyAuth": []
}
],
"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."
}
}
}POST /api/v1/wallets
Register wallets for automatic transaction syncing
Registers one or more wallets for the authenticated owner. Registered wallet addresses are synced automatically - transfers touching them are collected continuously and can be queried via the wallet transfer endpoints without polling the chain endpoints. Each item is processed independently and returns its own status: 201 created, 400 invalid, 429 wallet limit exceeded. Registration is rejected with 409 if an address is already registered.
Authentication: X-API-KEY header required.
Request body · application/json · Required
Array of wallets to register. Maximum 10 items.
| Field | Type | Details |
|---|---|---|
$ | array | Array of wallets to register. Maximum 10 items. Min items: 1. Max items: 10. |
$[] | object | — |
$[].type | string | Required. Wallet type. Must be the type this gateway registers. Allowed values: "client_wallet". |
$[].name | string | Optional display name for the wallet. Min length: 1. Max length: 100. |
$[].addresses | object | Required. Addresses to register, keyed by blockchain (e.g. {"ethereum": "0x...", "bitcoin": "bc1..."}). Use GET /api/v1/chains for supported blockchains. Min properties: 1. |
$[].addresses.* | string | Min length: 1. Max length: 200. |
$[].meta | object | Optional wallet metadata. Required when registering a spark address. |
$[].meta.spark | object | — |
$[].meta.spark.sparkDepositAddress | string | Required. Min length: 1. Pattern: "^([13][a-km-zA-HJ-NP-Z1-9]{25,34}|bc1[a-z0-9]{39,59})$". |
$[].meta.spark.sparkIdentityKey | string | Required. Min length: 1. |
Example request
Replace path placeholders and the API key before running. Save your request body in request.json using the fields above.
curl --request POST 'https://wdk-api.tether.io/api/v1/wallets' \
--header 'X-API-KEY: <api-key>' \
--header 'Content-Type: application/json' \
--data-binary @request.jsonResponses
| Status | Description |
|---|---|
200 | Per-wallet registration results in request order |
400 | Bad Request - invalid parameters, address format, or blockchain |
401 | Unauthorized - expired API key |
403 | Forbidden - missing or invalid API key |
409 | Conflict - address already registered |
429 | Too Many Requests - rate limit exceeded |
500 | Internal Server Error - wallet service unavailable or unexpected failure |
503 | Service Unavailable - wallet service temporarily unreachable |
Response fields · HTTP 200 · application/json
| Field | Type | Details |
|---|---|---|
$ | object | Per-wallet registration results in request order |
$.wallets | array | — |
$.wallets[] | object | Per-wallet registration result |
$.wallets[].status | number | Per-item status code: 201 created, 400 invalid, 429 wallet limit exceeded. |
$.wallets[].id | string | Wallet identifier (present when created). |
$.wallets[].name | string | Wallet display name. |
$.wallets[].type | string | Wallet type assigned at registration. |
$.wallets[].enabled | boolean | Whether the wallet is active for transaction syncing. |
$.wallets[].addresses | object | Registered addresses keyed by blockchain. |
$.wallets[].addresses.* | string | — |
$.wallets[].meta | object | Optional wallet metadata. Required when registering a spark address. |
$.wallets[].meta.spark | object | — |
$.wallets[].meta.spark.sparkDepositAddress | string | Required. Min length: 1. Pattern: "^([13][a-km-zA-HJ-NP-Z1-9]{25,34}|bc1[a-z0-9]{39,59})$". |
$.wallets[].meta.spark.sparkIdentityKey | string | Required. Min length: 1. |
$.wallets[].error | string | Error code when the item was rejected. |
$.wallets[].limit | number | Wallet limit that was exceeded (present on 429). |
$.wallets[].currentCount | number | Current wallet count (present on 429). |
Other response fields: $.error, $.message, $.status. See the full schema for each status.
Full endpoint schema (JSON)
{
"method": "POST",
"path": "/api/v1/wallets",
"operation": {
"summary": "Register wallets for automatic transaction syncing",
"tags": [
"Wallets"
],
"description": "Registers one or more wallets for the authenticated owner. Registered wallet addresses are synced automatically - transfers touching them are collected continuously and can be queried via the wallet transfer endpoints without polling the chain endpoints. Each item is processed independently and returns its own status: 201 created, 400 invalid, 429 wallet limit exceeded. Registration is rejected with 409 if an address is already registered.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "array",
"description": "Array of wallets to register. Maximum 10 items.",
"minItems": 1,
"maxItems": 10,
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"client_wallet"
],
"description": "Wallet type. Must be the type this gateway registers."
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Optional display name for the wallet."
},
"addresses": {
"type": "object",
"description": "Addresses to register, keyed by blockchain (e.g. {\"ethereum\": \"0x...\", \"bitcoin\": \"bc1...\"}). Use GET /api/v1/chains for supported blockchains.",
"minProperties": 1,
"propertyNames": {
"enum": [
"ethereum",
"arbitrum",
"avalanche",
"polygon",
"plasma",
"sepolia",
"tron",
"ton",
"bitcoin",
"spark"
]
},
"additionalProperties": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"meta": {
"type": "object",
"description": "Optional wallet metadata. Required when registering a spark address.",
"properties": {
"spark": {
"type": "object",
"properties": {
"sparkDepositAddress": {
"type": "string",
"minLength": 1,
"pattern": "^([13][a-km-zA-HJ-NP-Z1-9]{25,34}|bc1[a-z0-9]{39,59})$"
},
"sparkIdentityKey": {
"type": "string",
"minLength": 1
}
},
"required": [
"sparkDepositAddress",
"sparkIdentityKey"
],
"additionalProperties": false
}
},
"additionalProperties": false
}
},
"required": [
"type",
"addresses"
],
"additionalProperties": false
}
}
}
},
"description": "Array of wallets to register. Maximum 10 items."
},
"security": [
{
"ApiKeyAuth": []
}
],
"responses": {
"200": {
"description": "Per-wallet registration results in request order",
"content": {
"application/json": {
"schema": {
"description": "Per-wallet registration results in request order",
"type": "object",
"properties": {
"wallets": {
"type": "array",
"items": {
"description": "Per-wallet registration result",
"type": "object",
"properties": {
"status": {
"type": "number",
"description": "Per-item status code: 201 created, 400 invalid, 429 wallet limit exceeded."
},
"id": {
"type": "string",
"description": "Wallet identifier (present when created)."
},
"name": {
"type": "string",
"description": "Wallet display name."
},
"type": {
"type": "string",
"description": "Wallet type assigned at registration."
},
"enabled": {
"type": "boolean",
"description": "Whether the wallet is active for transaction syncing."
},
"addresses": {
"type": "object",
"description": "Registered addresses keyed by blockchain.",
"additionalProperties": {
"type": "string"
}
},
"meta": {
"type": "object",
"description": "Optional wallet metadata. Required when registering a spark address.",
"properties": {
"spark": {
"type": "object",
"properties": {
"sparkDepositAddress": {
"type": "string",
"minLength": 1,
"pattern": "^([13][a-km-zA-HJ-NP-Z1-9]{25,34}|bc1[a-z0-9]{39,59})$"
},
"sparkIdentityKey": {
"type": "string",
"minLength": 1
}
},
"required": [
"sparkDepositAddress",
"sparkIdentityKey"
],
"additionalProperties": false
}
},
"additionalProperties": false
},
"error": {
"type": "string",
"description": "Error code when the item was rejected."
},
"limit": {
"type": "number",
"description": "Wallet limit that was exceeded (present on 429)."
},
"currentCount": {
"type": "number",
"description": "Current wallet count (present on 429)."
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
}
},
"400": {
"description": "Bad Request - invalid parameters, address format, or blockchain",
"content": {
"application/json": {
"schema": {
"description": "Bad Request - invalid parameters, address format, or blockchain",
"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": "Error type"
},
"message": {
"type": "string",
"description": "Human-readable error description"
},
"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": "Error type"
},
"message": {
"type": "string",
"description": "Human-readable error description"
},
"status": {
"type": "number",
"description": "HTTP status code"
}
},
"additionalProperties": false
}
}
}
},
"409": {
"description": "Conflict - address already registered",
"content": {
"application/json": {
"schema": {
"description": "Conflict - address already registered",
"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
}
}
}
},
"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": "Error type"
},
"message": {
"type": "string",
"description": "Human-readable error description"
},
"status": {
"type": "number",
"description": "HTTP status code"
}
},
"additionalProperties": false
}
}
}
},
"500": {
"description": "Internal Server Error - wallet service unavailable or unexpected failure",
"content": {
"application/json": {
"schema": {
"description": "Internal Server Error - wallet service unavailable or unexpected failure",
"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
}
}
}
},
"503": {
"description": "Service Unavailable - wallet service temporarily unreachable",
"content": {
"application/json": {
"schema": {
"description": "Service Unavailable - wallet service temporarily unreachable",
"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
}
}
}
}
}
},
"pathParameters": [],
"security": [
{
"ApiKeyAuth": []
}
],
"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."
}
}
}GET /api/v1/wallets
List registered wallets
Returns all active wallets registered by the authenticated owner.
Authentication: X-API-KEY header required.
Example request
Replace path placeholders and the API key before running.
curl --request GET 'https://wdk-api.tether.io/api/v1/wallets' \
--header 'X-API-KEY: <api-key>'Responses
| Status | Description |
|---|---|
200 | Registered wallets |
401 | Unauthorized - expired API key |
403 | Forbidden - missing or invalid API key |
429 | Too Many Requests - rate limit exceeded |
500 | Internal Server Error - wallet service unavailable or unexpected failure |
503 | Service Unavailable - wallet service temporarily unreachable |
Response fields · HTTP 200 · application/json
| Field | Type | Details |
|---|---|---|
$ | object | Registered wallets |
$.wallets | array | — |
$.wallets[] | object | A registered wallet |
$.wallets[].id | string | Wallet identifier. |
$.wallets[].name | string | Optional wallet display name. |
$.wallets[].type | string | Wallet type assigned at registration. |
$.wallets[].enabled | boolean | Whether the wallet is active for transaction syncing. |
$.wallets[].addresses | object | Registered addresses keyed by blockchain. |
$.wallets[].addresses.* | string | — |
$.wallets[].meta | object | Optional wallet metadata. Required when registering a spark address. |
$.wallets[].meta.spark | object | — |
$.wallets[].meta.spark.sparkDepositAddress | string | Required. Min length: 1. Pattern: "^([13][a-km-zA-HJ-NP-Z1-9]{25,34}|bc1[a-z0-9]{39,59})$". |
$.wallets[].meta.spark.sparkIdentityKey | string | Required. Min length: 1. |
$.wallets[].createdAt | number | Creation timestamp in milliseconds. |
$.wallets[].updatedAt | number | Last update timestamp in milliseconds. |
Other response fields: $.error, $.message, $.status. See the full schema for each status.
Full endpoint schema (JSON)
{
"method": "GET",
"path": "/api/v1/wallets",
"operation": {
"summary": "List registered wallets",
"tags": [
"Wallets"
],
"description": "Returns all active wallets registered by the authenticated owner.",
"security": [
{
"ApiKeyAuth": []
}
],
"responses": {
"200": {
"description": "Registered wallets",
"content": {
"application/json": {
"schema": {
"description": "Registered wallets",
"type": "object",
"properties": {
"wallets": {
"type": "array",
"items": {
"description": "A registered wallet",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Wallet identifier."
},
"name": {
"type": "string",
"description": "Optional wallet display name."
},
"type": {
"type": "string",
"description": "Wallet type assigned at registration."
},
"enabled": {
"type": "boolean",
"description": "Whether the wallet is active for transaction syncing."
},
"addresses": {
"type": "object",
"description": "Registered addresses keyed by blockchain.",
"additionalProperties": {
"type": "string"
}
},
"meta": {
"type": "object",
"description": "Optional wallet metadata. Required when registering a spark address.",
"properties": {
"spark": {
"type": "object",
"properties": {
"sparkDepositAddress": {
"type": "string",
"minLength": 1,
"pattern": "^([13][a-km-zA-HJ-NP-Z1-9]{25,34}|bc1[a-z0-9]{39,59})$"
},
"sparkIdentityKey": {
"type": "string",
"minLength": 1
}
},
"required": [
"sparkDepositAddress",
"sparkIdentityKey"
],
"additionalProperties": false
}
},
"additionalProperties": false
},
"createdAt": {
"type": "number",
"description": "Creation timestamp in milliseconds."
},
"updatedAt": {
"type": "number",
"description": "Last update timestamp in milliseconds."
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
}
},
"401": {
"description": "Unauthorized - expired API key",
"content": {
"application/json": {
"schema": {
"description": "Unauthorized - expired API key",
"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
}
}
}
},
"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": "Error type"
},
"message": {
"type": "string",
"description": "Human-readable error description"
},
"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": "Error type"
},
"message": {
"type": "string",
"description": "Human-readable error description"
},
"status": {
"type": "number",
"description": "HTTP status code"
}
},
"additionalProperties": false
}
}
}
},
"500": {
"description": "Internal Server Error - wallet service unavailable or unexpected failure",
"content": {
"application/json": {
"schema": {
"description": "Internal Server Error - wallet service unavailable or unexpected failure",
"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
}
}
}
},
"503": {
"description": "Service Unavailable - wallet service temporarily unreachable",
"content": {
"application/json": {
"schema": {
"description": "Service Unavailable - wallet service temporarily unreachable",
"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
}
}
}
}
}
},
"pathParameters": [],
"security": [
{
"ApiKeyAuth": []
}
],
"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."
}
}
}GET /api/v1/wallets/{walletId}
Get a registered wallet
Returns a single wallet registered by the authenticated owner.
Authentication: X-API-KEY header required.
Parameters
| Name | Type | Details |
|---|---|---|
walletId (path) | string | Required: Yes. Wallet identifier from POST /api/v1/wallets. Min length: 1. |
Example request
Replace path placeholders and the API key before running.
curl --request GET 'https://wdk-api.tether.io/api/v1/wallets/{walletId}' \
--header 'X-API-KEY: <api-key>'Responses
| Status | Description |
|---|---|
200 | A registered wallet |
401 | Unauthorized - expired API key |
403 | Forbidden - missing or invalid API key |
404 | Not Found - wallet not found or access denied |
429 | Too Many Requests - rate limit exceeded |
500 | Internal Server Error - wallet service unavailable or unexpected failure |
503 | Service Unavailable - wallet service temporarily unreachable |
Response fields · HTTP 200 · application/json
| Field | Type | Details |
|---|---|---|
$ | object | A registered wallet |
$.id | string | Wallet identifier. |
$.name | string | Optional wallet display name. |
$.type | string | Wallet type assigned at registration. |
$.enabled | boolean | Whether the wallet is active for transaction syncing. |
$.addresses | object | Registered addresses keyed by blockchain. |
$.addresses.* | string | — |
$.meta | object | Optional wallet metadata. Required when registering a spark address. |
$.meta.spark | object | — |
$.meta.spark.sparkDepositAddress | string | Required. Min length: 1. Pattern: "^([13][a-km-zA-HJ-NP-Z1-9]{25,34}|bc1[a-z0-9]{39,59})$". |
$.meta.spark.sparkIdentityKey | string | Required. Min length: 1. |
$.createdAt | number | Creation timestamp in milliseconds. |
$.updatedAt | number | Last update timestamp in milliseconds. |
Other response fields: $.error, $.message, $.status. See the full schema for each status.
Full endpoint schema (JSON)
{
"method": "GET",
"path": "/api/v1/wallets/{walletId}",
"operation": {
"summary": "Get a registered wallet",
"tags": [
"Wallets"
],
"description": "Returns a single wallet registered by the authenticated owner.",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "walletId",
"required": true,
"description": "Wallet identifier from POST /api/v1/wallets."
}
],
"security": [
{
"ApiKeyAuth": []
}
],
"responses": {
"200": {
"description": "A registered wallet",
"content": {
"application/json": {
"schema": {
"description": "A registered wallet",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Wallet identifier."
},
"name": {
"type": "string",
"description": "Optional wallet display name."
},
"type": {
"type": "string",
"description": "Wallet type assigned at registration."
},
"enabled": {
"type": "boolean",
"description": "Whether the wallet is active for transaction syncing."
},
"addresses": {
"type": "object",
"description": "Registered addresses keyed by blockchain.",
"additionalProperties": {
"type": "string"
}
},
"meta": {
"type": "object",
"description": "Optional wallet metadata. Required when registering a spark address.",
"properties": {
"spark": {
"type": "object",
"properties": {
"sparkDepositAddress": {
"type": "string",
"minLength": 1,
"pattern": "^([13][a-km-zA-HJ-NP-Z1-9]{25,34}|bc1[a-z0-9]{39,59})$"
},
"sparkIdentityKey": {
"type": "string",
"minLength": 1
}
},
"required": [
"sparkDepositAddress",
"sparkIdentityKey"
],
"additionalProperties": false
}
},
"additionalProperties": false
},
"createdAt": {
"type": "number",
"description": "Creation timestamp in milliseconds."
},
"updatedAt": {
"type": "number",
"description": "Last update timestamp in milliseconds."
}
},
"additionalProperties": false
}
}
}
},
"401": {
"description": "Unauthorized - expired API key",
"content": {
"application/json": {
"schema": {
"description": "Unauthorized - expired API key",
"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
}
}
}
},
"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": "Error type"
},
"message": {
"type": "string",
"description": "Human-readable error description"
},
"status": {
"type": "number",
"description": "HTTP status code"
}
},
"additionalProperties": false
}
}
}
},
"404": {
"description": "Not Found - wallet not found or access denied",
"content": {
"application/json": {
"schema": {
"description": "Not Found - wallet not found or access denied",
"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
}
}
}
},
"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": "Error type"
},
"message": {
"type": "string",
"description": "Human-readable error description"
},
"status": {
"type": "number",
"description": "HTTP status code"
}
},
"additionalProperties": false
}
}
}
},
"500": {
"description": "Internal Server Error - wallet service unavailable or unexpected failure",
"content": {
"application/json": {
"schema": {
"description": "Internal Server Error - wallet service unavailable or unexpected failure",
"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
}
}
}
},
"503": {
"description": "Service Unavailable - wallet service temporarily unreachable",
"content": {
"application/json": {
"schema": {
"description": "Service Unavailable - wallet service temporarily unreachable",
"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
}
}
}
}
}
},
"pathParameters": [],
"security": [
{
"ApiKeyAuth": []
}
],
"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."
}
}
}PATCH /api/v1/wallets/{walletId}
Update a registered wallet
Updates the display name of a wallet or enables/disables its transaction syncing.
Authentication: X-API-KEY header required.
Parameters
| Name | Type | Details |
|---|---|---|
walletId (path) | string | Required: Yes. Wallet identifier from POST /api/v1/wallets. Min length: 1. |
Request body · application/json · Required
| Field | Type | Details |
|---|---|---|
$ | object | Min properties: 1. |
$.name | string | New display name for the wallet. Min length: 1. Max length: 100. |
$.enabled | boolean | Whether the wallet is active for transaction syncing. |
Example request
Replace path placeholders and the API key before running. Save your request body in request.json using the fields above.
curl --request PATCH 'https://wdk-api.tether.io/api/v1/wallets/{walletId}' \
--header 'X-API-KEY: <api-key>' \
--header 'Content-Type: application/json' \
--data-binary @request.jsonResponses
| Status | Description |
|---|---|
200 | A registered wallet |
400 | Bad Request - invalid parameters, address format, or blockchain |
401 | Unauthorized - expired API key |
403 | Forbidden - missing or invalid API key |
404 | Not Found - wallet not found or access denied |
429 | Too Many Requests - rate limit exceeded |
500 | Internal Server Error - wallet service unavailable or unexpected failure |
503 | Service Unavailable - wallet service temporarily unreachable |
Response fields · HTTP 200 · application/json
| Field | Type | Details |
|---|---|---|
$ | object | A registered wallet |
$.id | string | Wallet identifier. |
$.name | string | Optional wallet display name. |
$.type | string | Wallet type assigned at registration. |
$.enabled | boolean | Whether the wallet is active for transaction syncing. |
$.addresses | object | Registered addresses keyed by blockchain. |
$.addresses.* | string | — |
$.meta | object | Optional wallet metadata. Required when registering a spark address. |
$.meta.spark | object | — |
$.meta.spark.sparkDepositAddress | string | Required. Min length: 1. Pattern: "^([13][a-km-zA-HJ-NP-Z1-9]{25,34}|bc1[a-z0-9]{39,59})$". |
$.meta.spark.sparkIdentityKey | string | Required. Min length: 1. |
$.createdAt | number | Creation timestamp in milliseconds. |
$.updatedAt | number | Last update timestamp in milliseconds. |
Other response fields: $.error, $.message, $.status. See the full schema for each status.
Full endpoint schema (JSON)
{
"method": "PATCH",
"path": "/api/v1/wallets/{walletId}",
"operation": {
"summary": "Update a registered wallet",
"tags": [
"Wallets"
],
"description": "Updates the display name of a wallet or enables/disables its transaction syncing.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "New display name for the wallet."
},
"enabled": {
"type": "boolean",
"description": "Whether the wallet is active for transaction syncing."
}
},
"minProperties": 1,
"additionalProperties": false
}
}
}
},
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "walletId",
"required": true,
"description": "Wallet identifier from POST /api/v1/wallets."
}
],
"security": [
{
"ApiKeyAuth": []
}
],
"responses": {
"200": {
"description": "A registered wallet",
"content": {
"application/json": {
"schema": {
"description": "A registered wallet",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Wallet identifier."
},
"name": {
"type": "string",
"description": "Optional wallet display name."
},
"type": {
"type": "string",
"description": "Wallet type assigned at registration."
},
"enabled": {
"type": "boolean",
"description": "Whether the wallet is active for transaction syncing."
},
"addresses": {
"type": "object",
"description": "Registered addresses keyed by blockchain.",
"additionalProperties": {
"type": "string"
}
},
"meta": {
"type": "object",
"description": "Optional wallet metadata. Required when registering a spark address.",
"properties": {
"spark": {
"type": "object",
"properties": {
"sparkDepositAddress": {
"type": "string",
"minLength": 1,
"pattern": "^([13][a-km-zA-HJ-NP-Z1-9]{25,34}|bc1[a-z0-9]{39,59})$"
},
"sparkIdentityKey": {
"type": "string",
"minLength": 1
}
},
"required": [
"sparkDepositAddress",
"sparkIdentityKey"
],
"additionalProperties": false
}
},
"additionalProperties": false
},
"createdAt": {
"type": "number",
"description": "Creation timestamp in milliseconds."
},
"updatedAt": {
"type": "number",
"description": "Last update timestamp in milliseconds."
}
},
"additionalProperties": false
}
}
}
},
"400": {
"description": "Bad Request - invalid parameters, address format, or blockchain",
"content": {
"application/json": {
"schema": {
"description": "Bad Request - invalid parameters, address format, or blockchain",
"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": "Error type"
},
"message": {
"type": "string",
"description": "Human-readable error description"
},
"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": "Error type"
},
"message": {
"type": "string",
"description": "Human-readable error description"
},
"status": {
"type": "number",
"description": "HTTP status code"
}
},
"additionalProperties": false
}
}
}
},
"404": {
"description": "Not Found - wallet not found or access denied",
"content": {
"application/json": {
"schema": {
"description": "Not Found - wallet not found or access denied",
"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
}
}
}
},
"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": "Error type"
},
"message": {
"type": "string",
"description": "Human-readable error description"
},
"status": {
"type": "number",
"description": "HTTP status code"
}
},
"additionalProperties": false
}
}
}
},
"500": {
"description": "Internal Server Error - wallet service unavailable or unexpected failure",
"content": {
"application/json": {
"schema": {
"description": "Internal Server Error - wallet service unavailable or unexpected failure",
"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
}
}
}
},
"503": {
"description": "Service Unavailable - wallet service temporarily unreachable",
"content": {
"application/json": {
"schema": {
"description": "Service Unavailable - wallet service temporarily unreachable",
"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
}
}
}
}
}
},
"pathParameters": [],
"security": [
{
"ApiKeyAuth": []
}
],
"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."
}
}
}DELETE /api/v1/wallets/{walletId}
Delete a registered wallet
Deletes a wallet registered by the authenticated owner and stops syncing its transactions. Its addresses can be registered again afterwards.
Authentication: X-API-KEY header required.
Parameters
| Name | Type | Details |
|---|---|---|
walletId (path) | string | Required: Yes. Wallet identifier from POST /api/v1/wallets. Min length: 1. |
Example request
Replace path placeholders and the API key before running.
curl --request DELETE 'https://wdk-api.tether.io/api/v1/wallets/{walletId}' \
--header 'X-API-KEY: <api-key>'Responses
| Status | Description |
|---|---|
200 | Wallet deleted |
401 | Unauthorized - expired API key |
403 | Forbidden - missing or invalid API key |
404 | Not Found - wallet not found or access denied |
429 | Too Many Requests - rate limit exceeded |
500 | Internal Server Error - wallet service unavailable or unexpected failure |
503 | Service Unavailable - wallet service temporarily unreachable |
Response fields · HTTP 200 · application/json
| Field | Type | Details |
|---|---|---|
$ | object | Wallet deleted |
$.success | boolean | — |
Other response fields: $.error, $.message, $.status. See the full schema for each status.
Full endpoint schema (JSON)
{
"method": "DELETE",
"path": "/api/v1/wallets/{walletId}",
"operation": {
"summary": "Delete a registered wallet",
"tags": [
"Wallets"
],
"description": "Deletes a wallet registered by the authenticated owner and stops syncing its transactions. Its addresses can be registered again afterwards.",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "walletId",
"required": true,
"description": "Wallet identifier from POST /api/v1/wallets."
}
],
"security": [
{
"ApiKeyAuth": []
}
],
"responses": {
"200": {
"description": "Wallet deleted",
"content": {
"application/json": {
"schema": {
"description": "Wallet deleted",
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
},
"additionalProperties": false
}
}
}
},
"401": {
"description": "Unauthorized - expired API key",
"content": {
"application/json": {
"schema": {
"description": "Unauthorized - expired API key",
"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
}
}
}
},
"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": "Error type"
},
"message": {
"type": "string",
"description": "Human-readable error description"
},
"status": {
"type": "number",
"description": "HTTP status code"
}
},
"additionalProperties": false
}
}
}
},
"404": {
"description": "Not Found - wallet not found or access denied",
"content": {
"application/json": {
"schema": {
"description": "Not Found - wallet not found or access denied",
"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
}
}
}
},
"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": "Error type"
},
"message": {
"type": "string",
"description": "Human-readable error description"
},
"status": {
"type": "number",
"description": "HTTP status code"
}
},
"additionalProperties": false
}
}
}
},
"500": {
"description": "Internal Server Error - wallet service unavailable or unexpected failure",
"content": {
"application/json": {
"schema": {
"description": "Internal Server Error - wallet service unavailable or unexpected failure",
"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
}
}
}
},
"503": {
"description": "Service Unavailable - wallet service temporarily unreachable",
"content": {
"application/json": {
"schema": {
"description": "Service Unavailable - wallet service temporarily unreachable",
"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
}
}
}
}
}
},
"pathParameters": [],
"security": [
{
"ApiKeyAuth": []
}
],
"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."
}
}
}GET /api/v1/wallets/{walletId}/transfers
Get synced transfers for a wallet
Returns the automatically synced transfer log for a single registered wallet, newest first by default.
Authentication: X-API-KEY header required.
Parameters
| Name | Type | Details |
|---|---|---|
blockchain (query) | string | Required: No. Filter transfers by blockchain. Allowed values: "ethereum", "arbitrum", "avalanche", "polygon", "plasma", "sepolia", "tron", "ton", "bitcoin", "spark". |
token (query) | string | Required: No. Filter transfers by token. Allowed values: "usdt", "xaut", "usat", "btc". |
type (query) | string | Required: No. Filter by transfer direction relative to the wallet. Allowed values: "sent", "received". |
from (query) | oneOf | Required: No. Start of the time range - timestamp in milliseconds or ISO 8601 date. |
to (query) | oneOf | Required: No. End of the time range - timestamp in milliseconds or ISO 8601 date. |
limit (query) | integer | Required: No. Maximum number of transfers to return. Minimum: 1. Maximum: 100. Default: 10. |
skip (query) | integer | Required: No. Number of matching transfers to skip (pagination offset). Minimum: 0. Default: 0. |
sort (query) | string | Required: No. Sort order by timestamp. Allowed values: "asc", "desc". Default: "desc". |
walletId (path) | string | Required: Yes. Wallet identifier from POST /api/v1/wallets. Min length: 1. |
Example request
Replace path placeholders and the API key before running.
curl --request GET 'https://wdk-api.tether.io/api/v1/wallets/{walletId}/transfers' \
--header 'X-API-KEY: <api-key>'Responses
| Status | Description |
|---|---|
200 | Raw transfer log entries for registered wallets |
400 | Bad Request - invalid parameters, address format, or blockchain |
401 | Unauthorized - expired API key |
403 | Forbidden - missing or invalid API key |
404 | Not Found - wallet not found or access denied |
429 | Too Many Requests - rate limit exceeded |
500 | Internal Server Error - wallet service unavailable or unexpected failure |
503 | Service Unavailable - wallet service temporarily unreachable |
Response fields · HTTP 200 · application/json
| Field | Type | Details |
|---|---|---|
$ | object | Raw transfer log entries for registered wallets |
$.transfers | array | List of transfers sorted by timestamp. |
$.transfers[] | object | — |
$.transfers[].walletId | string | Wallet the transfer belongs to. |
$.transfers[].blockchain | string | Blockchain where the transfer occurred. |
$.transfers[].token | string | Token identifier. |
$.transfers[].transactionHash | string | Hash of the transaction. |
$.transfers[].transferIndex | integer | Index of the transfer within the transaction. |
$.transfers[].blockNumber | integer | Block number containing the transfer. |
$.transfers[].amount | string | Transfer amount as a decimal string. |
$.transfers[].from | oneOf | Sender address. |
$.transfers[].from (oneOf 1) | string | — |
$.transfers[].from (oneOf 2) | null | — |
$.transfers[].to | oneOf | Recipient address. |
$.transfers[].to (oneOf 1) | string | — |
$.transfers[].to (oneOf 2) | null | — |
$.transfers[].ts | integer | Block timestamp in milliseconds since Unix epoch. |
$.transfers[].transactionIndex | oneOf | Position of the transaction within the block. |
$.transfers[].transactionIndex (oneOf 1) | integer | — |
$.transfers[].transactionIndex (oneOf 2) | null | — |
$.transfers[].logIndex | oneOf | Event log index for EVM chains. null for non-EVM chains. |
$.transfers[].logIndex (oneOf 1) | integer | — |
$.transfers[].logIndex (oneOf 2) | null | — |
$.transfers[].label | string | A label associated with the transfer, if any. |
$.transfers[].type | string | Direction of the transfer relative to the wallet. Allowed values: "sent", "received". |
Other response fields: $.error, $.message, $.status. See the full schema for each status.
Full endpoint schema (JSON)
{
"method": "GET",
"path": "/api/v1/wallets/{walletId}/transfers",
"operation": {
"summary": "Get synced transfers for a wallet",
"tags": [
"Wallet Transfers"
],
"description": "Returns the automatically synced transfer log for a single registered wallet, newest first by default.",
"parameters": [
{
"schema": {
"type": "string",
"enum": [
"ethereum",
"arbitrum",
"avalanche",
"polygon",
"plasma",
"sepolia",
"tron",
"ton",
"bitcoin",
"spark"
]
},
"in": "query",
"name": "blockchain",
"required": false,
"description": "Filter transfers by blockchain."
},
{
"schema": {
"type": "string",
"enum": [
"usdt",
"xaut",
"usat",
"btc"
]
},
"in": "query",
"name": "token",
"required": false,
"description": "Filter transfers by token."
},
{
"schema": {
"type": "string",
"enum": [
"sent",
"received"
]
},
"in": "query",
"name": "type",
"required": false,
"description": "Filter by transfer direction relative to the wallet."
},
{
"schema": {
"oneOf": [
{
"type": "integer",
"minimum": 0
},
{
"type": "string",
"format": "date-time"
}
]
},
"in": "query",
"name": "from",
"required": false,
"description": "Start of the time range - timestamp in milliseconds or ISO 8601 date."
},
{
"schema": {
"oneOf": [
{
"type": "integer",
"minimum": 0
},
{
"type": "string",
"format": "date-time"
}
]
},
"in": "query",
"name": "to",
"required": false,
"description": "End of the time range - timestamp in milliseconds or ISO 8601 date."
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 10
},
"in": "query",
"name": "limit",
"required": false,
"description": "Maximum number of transfers to return."
},
{
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"in": "query",
"name": "skip",
"required": false,
"description": "Number of matching transfers to skip (pagination offset)."
},
{
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "desc"
},
"in": "query",
"name": "sort",
"required": false,
"description": "Sort order by timestamp."
},
{
"schema": {
"type": "string",
"minLength": 1
},
"in": "path",
"name": "walletId",
"required": true,
"description": "Wallet identifier from POST /api/v1/wallets."
}
],
"security": [
{
"ApiKeyAuth": []
}
],
"responses": {
"200": {
"description": "Raw transfer log entries for registered wallets",
"content": {
"application/json": {
"schema": {
"description": "Raw transfer log entries for registered wallets",
"type": "object",
"properties": {
"transfers": {
"type": "array",
"description": "List of transfers sorted by timestamp.",
"items": {
"type": "object",
"properties": {
"walletId": {
"type": "string",
"description": "Wallet the transfer belongs to."
},
"blockchain": {
"type": "string",
"description": "Blockchain where the transfer occurred."
},
"token": {
"type": "string",
"description": "Token identifier."
},
"transactionHash": {
"type": "string",
"description": "Hash of the transaction."
},
"transferIndex": {
"type": "integer",
"description": "Index of the transfer within the transaction."
},
"blockNumber": {
"type": "integer",
"description": "Block number containing the transfer."
},
"amount": {
"type": "string",
"description": "Transfer amount as a decimal string."
},
"from": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Sender address."
},
"to": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Recipient address."
},
"ts": {
"type": "integer",
"description": "Block timestamp in milliseconds since Unix epoch."
},
"transactionIndex": {
"oneOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Position of the transaction within the block."
},
"logIndex": {
"oneOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Event log index for EVM chains. null for non-EVM chains."
},
"label": {
"type": "string",
"description": "A label associated with the transfer, if any."
},
"type": {
"type": "string",
"enum": [
"sent",
"received"
],
"description": "Direction of the transfer relative to the wallet."
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
}
},
"400": {
"description": "Bad Request - invalid parameters, address format, or blockchain",
"content": {
"application/json": {
"schema": {
"description": "Bad Request - invalid parameters, address format, or blockchain",
"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": "Error type"
},
"message": {
"type": "string",
"description": "Human-readable error description"
},
"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": "Error type"
},
"message": {
"type": "string",
"description": "Human-readable error description"
},
"status": {
"type": "number",
"description": "HTTP status code"
}
},
"additionalProperties": false
}
}
}
},
"404": {
"description": "Not Found - wallet not found or access denied",
"content": {
"application/json": {
"schema": {
"description": "Not Found - wallet not found or access denied",
"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
}
}
}
},
"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": "Error type"
},
"message": {
"type": "string",
"description": "Human-readable error description"
},
"status": {
"type": "number",
"description": "HTTP status code"
}
},
"additionalProperties": false
}
}
}
},
"500": {
"description": "Internal Server Error - wallet service unavailable or unexpected failure",
"content": {
"application/json": {
"schema": {
"description": "Internal Server Error - wallet service unavailable or unexpected failure",
"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
}
}
}
},
"503": {
"description": "Service Unavailable - wallet service temporarily unreachable",
"content": {
"application/json": {
"schema": {
"description": "Service Unavailable - wallet service temporarily unreachable",
"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
}
}
}
}
}
},
"pathParameters": [],
"security": [
{
"ApiKeyAuth": []
}
],
"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."
}
}
}GET /api/v1/transfers
Get synced transfers across all registered wallets
Returns the automatically synced transfer log across all the owner's registered wallets, merged and sorted by timestamp.
Authentication: X-API-KEY header required.
Parameters
| Name | Type | Details |
|---|---|---|
blockchain (query) | string | Required: No. Filter transfers by blockchain. Allowed values: "ethereum", "arbitrum", "avalanche", "polygon", "plasma", "sepolia", "tron", "ton", "bitcoin", "spark". |
token (query) | string | Required: No. Filter transfers by token. Allowed values: "usdt", "xaut", "usat", "btc". |
type (query) | string | Required: No. Filter by transfer direction relative to the wallet. Allowed values: "sent", "received". |
from (query) | oneOf | Required: No. Start of the time range - timestamp in milliseconds or ISO 8601 date. |
to (query) | oneOf | Required: No. End of the time range - timestamp in milliseconds or ISO 8601 date. |
limit (query) | integer | Required: No. Maximum number of transfers to return. Minimum: 1. Maximum: 100. Default: 10. |
skip (query) | integer | Required: No. Number of matching transfers to skip (pagination offset). Minimum: 0. Default: 0. |
sort (query) | string | Required: No. Sort order by timestamp. Allowed values: "asc", "desc". Default: "desc". |
Example request
Replace path placeholders and the API key before running.
curl --request GET 'https://wdk-api.tether.io/api/v1/transfers' \
--header 'X-API-KEY: <api-key>'Responses
| Status | Description |
|---|---|
200 | Raw transfer log entries for registered wallets |
400 | Bad Request - invalid parameters, address format, or blockchain |
401 | Unauthorized - expired API key |
403 | Forbidden - missing or invalid API key |
429 | Too Many Requests - rate limit exceeded |
500 | Internal Server Error - wallet service unavailable or unexpected failure |
503 | Service Unavailable - wallet service temporarily unreachable |
Response fields · HTTP 200 · application/json
| Field | Type | Details |
|---|---|---|
$ | object | Raw transfer log entries for registered wallets |
$.transfers | array | List of transfers sorted by timestamp. |
$.transfers[] | object | — |
$.transfers[].walletId | string | Wallet the transfer belongs to. |
$.transfers[].blockchain | string | Blockchain where the transfer occurred. |
$.transfers[].token | string | Token identifier. |
$.transfers[].transactionHash | string | Hash of the transaction. |
$.transfers[].transferIndex | integer | Index of the transfer within the transaction. |
$.transfers[].blockNumber | integer | Block number containing the transfer. |
$.transfers[].amount | string | Transfer amount as a decimal string. |
$.transfers[].from | oneOf | Sender address. |
$.transfers[].from (oneOf 1) | string | — |
$.transfers[].from (oneOf 2) | null | — |
$.transfers[].to | oneOf | Recipient address. |
$.transfers[].to (oneOf 1) | string | — |
$.transfers[].to (oneOf 2) | null | — |
$.transfers[].ts | integer | Block timestamp in milliseconds since Unix epoch. |
$.transfers[].transactionIndex | oneOf | Position of the transaction within the block. |
$.transfers[].transactionIndex (oneOf 1) | integer | — |
$.transfers[].transactionIndex (oneOf 2) | null | — |
$.transfers[].logIndex | oneOf | Event log index for EVM chains. null for non-EVM chains. |
$.transfers[].logIndex (oneOf 1) | integer | — |
$.transfers[].logIndex (oneOf 2) | null | — |
$.transfers[].label | string | A label associated with the transfer, if any. |
$.transfers[].type | string | Direction of the transfer relative to the wallet. Allowed values: "sent", "received". |
Other response fields: $.error, $.message, $.status. See the full schema for each status.
Full endpoint schema (JSON)
{
"method": "GET",
"path": "/api/v1/transfers",
"operation": {
"summary": "Get synced transfers across all registered wallets",
"tags": [
"Wallet Transfers"
],
"description": "Returns the automatically synced transfer log across all the owner's registered wallets, merged and sorted by timestamp.",
"parameters": [
{
"schema": {
"type": "string",
"enum": [
"ethereum",
"arbitrum",
"avalanche",
"polygon",
"plasma",
"sepolia",
"tron",
"ton",
"bitcoin",
"spark"
]
},
"in": "query",
"name": "blockchain",
"required": false,
"description": "Filter transfers by blockchain."
},
{
"schema": {
"type": "string",
"enum": [
"usdt",
"xaut",
"usat",
"btc"
]
},
"in": "query",
"name": "token",
"required": false,
"description": "Filter transfers by token."
},
{
"schema": {
"type": "string",
"enum": [
"sent",
"received"
]
},
"in": "query",
"name": "type",
"required": false,
"description": "Filter by transfer direction relative to the wallet."
},
{
"schema": {
"oneOf": [
{
"type": "integer",
"minimum": 0
},
{
"type": "string",
"format": "date-time"
}
]
},
"in": "query",
"name": "from",
"required": false,
"description": "Start of the time range - timestamp in milliseconds or ISO 8601 date."
},
{
"schema": {
"oneOf": [
{
"type": "integer",
"minimum": 0
},
{
"type": "string",
"format": "date-time"
}
]
},
"in": "query",
"name": "to",
"required": false,
"description": "End of the time range - timestamp in milliseconds or ISO 8601 date."
},
{
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 10
},
"in": "query",
"name": "limit",
"required": false,
"description": "Maximum number of transfers to return."
},
{
"schema": {
"type": "integer",
"minimum": 0,
"default": 0
},
"in": "query",
"name": "skip",
"required": false,
"description": "Number of matching transfers to skip (pagination offset)."
},
{
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "desc"
},
"in": "query",
"name": "sort",
"required": false,
"description": "Sort order by timestamp."
}
],
"security": [
{
"ApiKeyAuth": []
}
],
"responses": {
"200": {
"description": "Raw transfer log entries for registered wallets",
"content": {
"application/json": {
"schema": {
"description": "Raw transfer log entries for registered wallets",
"type": "object",
"properties": {
"transfers": {
"type": "array",
"description": "List of transfers sorted by timestamp.",
"items": {
"type": "object",
"properties": {
"walletId": {
"type": "string",
"description": "Wallet the transfer belongs to."
},
"blockchain": {
"type": "string",
"description": "Blockchain where the transfer occurred."
},
"token": {
"type": "string",
"description": "Token identifier."
},
"transactionHash": {
"type": "string",
"description": "Hash of the transaction."
},
"transferIndex": {
"type": "integer",
"description": "Index of the transfer within the transaction."
},
"blockNumber": {
"type": "integer",
"description": "Block number containing the transfer."
},
"amount": {
"type": "string",
"description": "Transfer amount as a decimal string."
},
"from": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Sender address."
},
"to": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Recipient address."
},
"ts": {
"type": "integer",
"description": "Block timestamp in milliseconds since Unix epoch."
},
"transactionIndex": {
"oneOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Position of the transaction within the block."
},
"logIndex": {
"oneOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Event log index for EVM chains. null for non-EVM chains."
},
"label": {
"type": "string",
"description": "A label associated with the transfer, if any."
},
"type": {
"type": "string",
"enum": [
"sent",
"received"
],
"description": "Direction of the transfer relative to the wallet."
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
}
},
"400": {
"description": "Bad Request - invalid parameters, address format, or blockchain",
"content": {
"application/json": {
"schema": {
"description": "Bad Request - invalid parameters, address format, or blockchain",
"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": "Error type"
},
"message": {
"type": "string",
"description": "Human-readable error description"
},
"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": "Error type"
},
"message": {
"type": "string",
"description": "Human-readable error description"
},
"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": "Error type"
},
"message": {
"type": "string",
"description": "Human-readable error description"
},
"status": {
"type": "number",
"description": "HTTP status code"
}
},
"additionalProperties": false
}
}
}
},
"500": {
"description": "Internal Server Error - wallet service unavailable or unexpected failure",
"content": {
"application/json": {
"schema": {
"description": "Internal Server Error - wallet service unavailable or unexpected failure",
"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
}
}
}
},
"503": {
"description": "Service Unavailable - wallet service temporarily unreachable",
"content": {
"application/json": {
"schema": {
"description": "Service Unavailable - wallet service temporarily unreachable",
"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
}
}
}
}
}
},
"pathParameters": [],
"security": [
{
"ApiKeyAuth": []
}
],
"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."
}
}
}Rate Limiting
The production snapshot does not declare per-endpoint quotas. Handle HTTP 429 according to the response documented for the operation you call.
Error Handling
Check the HTTP status before consuming a response. Use the error statuses and schemas documented under the operation you call.
Error Response Format
Use the schema for the returned status under the relevant operation. Error bodies can differ between operations.
Next Steps
- Get Started with an API key and your first request.
- Use the JavaScript SDK to call the API from Node.js or Bare.
Need Help?
Loading API reference. The text reference is available.