Token

Endpointhttps://api.sparkscan.io

Download schema

Operations related to tokens

GET

https://api.sparkscan.io

/v1/address/{address}/tokens

Get all tokens held by an address with their balances and USD values.

path Parameters

address

string · required

The Spark address or public key hex

query Parameters

network

string · enum

Enum values:

MAINNET

REGTEST

Responses

Response for status 200

object[] · required

required

totalTokenValueUsd

number · required

POST

https://api.sparkscan.io

/v1/tokens/metadata/batch

Fetch metadata for multiple tokens in a single request. Accepts 1-100 token addresses.

query Parameters

network

string · enum

Enum values:

MAINNET

REGTEST

Request Body

token_addresses

string[] · minItems: 1 · maxItems: 100 · required

Array of token addresses to look up (1-100).

Responses

Response for status 200

object[] · required

total_count

integer · required

Total number of tokens returned

POST/v1/tokens/metadata/batch

curl --request POST \
  --url https://api.sparkscan.io/v1/tokens/metadata/batch \
  --header 'Content-Type: application/json' \
  --data '
{
  "token_addresses": [
    "string"
  ]
}
'

shell

Example Request Body

{
  "token_addresses": [
    "string"
  ]
}

json

Example Responses

{
  "metadata": [
    {
      "tokenIdentifier": "tokenIdentifier",
      "tokenAddress": "tokenAddress",
      "name": "name",
      "ticker": "ticker",
      "decimals": 0,
      "issuerPublicKey": "issuerPublicKey",
      "iconUrl": "iconUrl",
      "holderCount": 0,
      "priceUsd": 0,
      "maxSupply": "string",
      "isFreezable": true,
      "createdAt": "2024-08-25T15:00:00Z",
      "updatedAt": "2024-08-25T15:00:00Z",
      "totalSupply": "totalSupply",
      "marketCapUsd": 0
    }
  ],
  "total_count": 0
}

json

application/json

deprecated

POST

https://api.sparkscan.io

/v1/tokens/issuer-lookup

Look up token issuer information by public keys or token identifiers.

query Parameters

network

string · enum

Enum values:

MAINNET

REGTEST

Request Body

pubkeys

string[] · maxItems: 100

tokens

string[] · maxItems: 100

Responses

Response for status 200

object[] · required

GET

https://api.sparkscan.io

/v1/tokens/{identifier}

Get token details by identifier/address, or search tokens by name/ticker. Returns TokenDetailsResponse for exact matches and TokenMetadata[] for search queries.

path Parameters

identifier

string · required

Token identifier (64-char hex), token address (bech32 btk...), or search query string.

query Parameters

network

string · enum

Enum values:

MAINNET

REGTEST

limit

min: 1

Maximum number of tokens to return. Limit is 50.

offset

Number of results to skip.

Responses

Response for status 200

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = object · requires: metadata, totalSupply, marketCapUsd +1 more
	type = array

Properties for Variant 1:

object · required

totalSupply

string · required

Current total supply as a decimal string

marketCapUsd

number · required

Market cap in USD

volume24hUsd

number · required

24-hour trading volume in USD

GET

https://api.sparkscan.io

/v1/tokens/{identifier}/holders

Get the top holders of a token sorted by balance descending.

path Parameters

identifier

string · required

Token identifier (hex) or token address (bech32).

query Parameters

network

string · enum

Enum values:

MAINNET

REGTEST

limit

min: 1

Maximum number of holders to return. Limit is 75.

offset

Number of results to skip.

Responses

Response for status 200

object · required

object[] · required

GET

https://api.sparkscan.io

/v1/tokens/{identifier}/transactions

Get paginated transactions for a specific token.

path Parameters

identifier

string · required

Token identifier (hex) or token address (bech32).

query Parameters

network

string · enum

Enum values:

MAINNET

REGTEST

limit

Maximum number of transactions to return (default: 25, max: 100).

offset

Number of results to skip.

Responses

Response for status 200

object · required

object[] · required

GET/v1/tokens/{identifier}/transactions

curl --request GET \
  --url https://api.sparkscan.io/v1/tokens/:identifier/transactions

shell

Example Responses

{
  "meta": {
    "totalItems": 0,
    "limit": 0,
    "offset": 0
  },
  "data": [
    {
      "id": "id",
      "type": "type",
      "status": "confirmed",
      "createdAt": "2024-08-25T15:00:00Z",
      "updatedAt": "2024-08-25T15:00:00Z",
      "expiredTime": "2024-08-25T15:00:00Z",
      "from": {
        "type": "spark",
        "identifier": "identifier",
        "pubkey": "string"
      },
      "to": {
        "type": "spark",
        "identifier": "identifier",
        "pubkey": "string"
      },
      "amount": "amount",
      "valueUsd": 0,
      "tokenMetadata": {
        "tokenIdentifier": "tokenIdentifier",
        "tokenAddress": "tokenAddress",
        "name": "name",
        "ticker": "ticker",
        "decimals": 0,
        "issuerPublicKey": "issuerPublicKey",
        "maxSupply": "string",
        "isFreezable": true
      },
      "multiIoDetails": {
        "inputs": [
          {
            "address": "address",
            "pubkey": "pubkey",
            "amount": "amount"
          }
        ],
        "outputs": [
          {
            "address": "address",
            "pubkey": "pubkey",
            "amount": "amount"
          }
        ],
        "totalInputAmount": "totalInputAmount",
        "totalOutputAmount": "totalOutputAmount"
      },
      "swapId": "string"
    }
  ]
}

json

application/json

GET

https://api.sparkscan.io

/v2/tokens/list

List tokens with cursor-based pagination, sorting, and filtering. Supports filtering by icon availability, holder address, and minimum holder count.

query Parameters

network

string · enum · required

Enum values:

MAINNET

REGTEST

limit

number · min: 1 · max: 50

The number of tokens to return per page. If not provided, the default limit of 25 will be used.

Example: 10

Default: 25

cursor

string

The cursor to paginate the tokens by. If not provided, the first page of tokens will be returned.

sort

string · enum

Enum values:

holders

updated_at

created_at

supply

sortDirection

string · enum

Enum values:

asc

desc

hasIcon

boolean

Whether to filter for tokens with icons. If not provided, all tokens will be returned.

Example: true

holderAddress

string

The public key hex of the holder to filter for. If not provided, all tokens will be returned.

minHolders

number · min: 0

The minimum number of holders to filter for. If not provided, all tokens will be returned.

Example: 5

Responses

Response for status 200

object[] · required

totalTokens

integer · required

Total number of tokens matching the query

required

Cursor for the next page, or null if no more pages

GET

https://api.sparkscan.io

/v2/historical/tokens/balances/{address}/{tokenIdentifier}

Fetches the hourly tokens balances for an address and token identifier. Currently available on the free plan but will be limited to enterprise users in the future.

path Parameters

address

string · required

The address to fetch the tokens balances for.

tokenIdentifier

string · required

The token identifier to fetch the tokens balances for.

query Parameters

network

string · enum · required

Enum values:

MAINNET

REGTEST

direction

string · enum

Enum values:

forward

backward

from

to

cursor

string

Pagination cursor from previous response.

limit

number · min: 1 · max: 48

Number of results per page (default: 12, max: 48).

Responses

Response for status 200

object[] · required

required

Cursor for the next page, or null if no more pages

Address Sats

Variant

Matching Criteria

type = object · requires: metadata, totalSupply, marketCapUsd +1 more

type = array