Sparkscan API

Token

Endpointhttps://api.sparkscan.io

Download schema

Operations related to tokens

GET

https://api.sparkscan.io

/v1/address/{address}/tokens

path Parameters

address

string · required

query Parameters

network

string · enum

Enum values:

MAINNET

REGTEST

Responses

Response for status 200

object[] · required

required

totalTokenValueUsd

number · required

GET/v1/address/{address}/tokens

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

shell

Example Responses

{
  "tokens": [
    {
      "tokenIdentifier": "tokenIdentifier",
      "tokenAddress": "tokenAddress",
      "name": "name",
      "ticker": "ticker",
      "decimals": "string",
      "balance": "balance",
      "valueUsd": 0,
      "issuerPublicKey": "issuerPublicKey",
      "iconUrl": "iconUrl",
      "maxSupply": "string",
      "isFreezable": true
    }
  ],
  "tokenCount": "string",
  "totalTokenValueUsd": 0
}

json

application/json

POST

https://api.sparkscan.io

/v1/tokens/metadata/batch

query Parameters

network

string · enum

Enum values:

MAINNET

REGTEST

Request Body

token_addresses

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

Responses

Response for status 200

object[] · required

total_count

integer · required

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

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

POST/v1/tokens/issuer-lookup

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

shell

Example Request Body

{
  "pubkeys": [
    "string"
  ],
  "tokens": [
    "string"
  ]
}

json

Example Responses

{
  "results": [
    {
      "pubkey": "pubkey",
      "tokenIdentifier": "tokenIdentifier",
      "tokenAddress": "tokenAddress"
    }
  ]
}

json

application/json

GET

https://api.sparkscan.io

/v1/tokens/{identifier}

path Parameters

identifier

string · required

query Parameters

network

string · enum

Enum values:

MAINNET

REGTEST

limit

min: 1

Maximum number of tokens to return. Limit is 50.

offset

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

marketCapUsd

number · required

volume24hUsd

number · required

GET/v1/tokens/{identifier}

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

shell

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,
  "volume24hUsd": 0
}

json

application/json

GET

https://api.sparkscan.io

/v1/tokens/{identifier}/holders

path Parameters

identifier

string · required

query Parameters

network

string · enum

Enum values:

MAINNET

REGTEST

limit

min: 1

Maximum number of holders to return. Limit is 75.

offset

Responses

Response for status 200

object · required

object[] · required

GET/v1/tokens/{identifier}/holders

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

shell

Example Responses

{
  "meta": {
    "totalItems": 0,
    "limit": 0,
    "offset": 0
  },
  "data": [
    {
      "address": "address",
      "pubkey": "pubkey",
      "balance": "balance",
      "valueUsd": 0,
      "percentage": 0
    }
  ]
}

json

application/json

GET

https://api.sparkscan.io

/v1/tokens/{identifier}/transactions

path Parameters

identifier

string · required

query Parameters

network

string · enum

Enum values:

MAINNET

REGTEST

limit

offset

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

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

required

GET/v2/tokens/list

curl --request GET \
  --url 'https://api.sparkscan.io/v2/tokens/list?network=%3Cstring%3E'

shell

Example Responses

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

json

application/json

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

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

curl --request GET \
  --url 'https://api.sparkscan.io/v2/historical/tokens/balances/:address/:tokenIdentifier?network=%3Cstring%3E'

shell

Example Responses

{
  "data": [
    {
      "t": 0,
      "b": "b"
    }
  ],
  "nextCursor": "string"
}

json

application/json

Address Sats

{ "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 }

Variant

Matching Criteria

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

type = array

{ "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" } ] }