Wallet APIs

Token Balances

The Token Balances API allows retrieval of the balance of the native token and all ERC20 fungible tokens held by a specific address on a given blockchain. However, this API is being deprecated in favor of the new Balances API with pagination.

Filters:

  • Get All Assets Without dust tokens: The Dust Filtering filters out dust tokens and returns only verified tokens if the "verified" parameter is set to true. It accepts a "true" or "false" value for the "verified" query parameter.
import Unmarshal, {Chain} from "@unmarshal/sdk";

const unmarshal = new Unmarshal({apiKey: "YOUR_API_KEY_GOES_HERE"});

unmarshal.WalletApi
    .getTokenBalances(Chain.ethereum, "demo.eth")
    .then(({data}) => console.log(data))
Request
Security:
auth_key
path Parameters
chain
required
string

Chain name (example: bsc, ethereum, matic...)

Enum: "ethereum" "bsc" "matic" "kadena" "celo" "klaytn" "cronos" "velas" "arbitrum" "avalanche" "xinfin" "zilliqa" "solana" "fantom" "fuse" "aurora" "bsc-testnet" "matic-testnet" "rinkeby-testnet"
Example: bsc
address
required
string
Default: "demo.eth"

Any valid address or ENS

Example: demo.eth
query Parameters
verified
boolean
Default: "false"

Set true for only verified tokens

includeLowVolume
boolean
Default: false

Get the prices of low volume tokens

chainId
string
Default: "false"

Return details for requested chain id (For Kadena chain)

token
string
Default: "false"

Return balances of the requested token (For Kadena chain)

aggregatedBalance
string
Default: "false"

Return aggregated balances accross all chains (For Kadena chain)

Responses
200
401
get/v1/{chain}/address/{address}/assets
Request samples
    4 more
    JavaScript
    PHP
    Ruby
    C#
curl -i -X GET \
  'https://api.unmarshal.com/v1/:chain/address/:address/assets?verified=false&includeLowVolume=false&chainId=false&token=false&aggregatedBalance=false&auth_key=YOUR_API_KEY_HERE'
Response samples
application/json
[
  • {},
  • {
    },
  • {
    }
]

Token balances with pagination

The Token Balances API with pagination enables the retrieval of the balance of the native token and all ERC20 fungible tokens for a specific blockchain, based on a particular address. It also allows for pagination to improve response times when dealing with large numbers of tokens. This API will become the default option once support for the older Token Balances API is deprecated.

Note:

  • To fetch items on the next page, pass next_offset value of current page as the offset.

  • For Kadena and Solana, all assets will be returned in a single response.

Filters:

  • Get All Assets Without dust tokens: The Dust Filtering filters out dust tokens and returns only verified tokens if the "verified" parameter is set to true. It accepts a "true" or "false" value for the "verified" query parameter.
import Unmarshal, {Chain} from "@unmarshal/sdk";

const unmarshal = new Unmarshal({apiKey: "YOUR_API_KEY_GOES_HERE"});

unmarshal.WalletApi
    .getTokenBalances(Chain.ethereum, "demo.eth")
    .then(({data}) => console.log(data))
Request
Security:
auth_key
path Parameters
chain
required
string

Chain name (example: bsc, ethereum, matic...)

Enum: "ethereum" "bsc" "matic" "kadena" "celo" "klaytn" "cronos" "velas" "arbitrum" "avalanche" "xinfin" "zilliqa" "solana" "fantom" "fuse" "aurora" "bsc-testnet" "matic-testnet" "rinkeby-testnet"
Example: bsc
address
required
string
Default: "demo.eth"

Any valid address or ENS

Example: demo.eth
query Parameters
verified
boolean
Default: "false"

Set true for only verified tokens

pageSize
number
Default: 50

Number of records to be fetched per page

Example: pageSize=5
offset
string
Default: "0"

The offset to start with, this is returned in the previous response.

chainId
string
Default: "false"

Return details for requested chain id (For Kadena chain)

token
string
Default: "false"

Return balances of the requested token (For Kadena chain)

aggregatedBalance
string
Default: "false"

Return aggregated balances accross all chains (For Kadena chain)

Responses
200
401
get/v2/{chain}/address/{address}/assets
Request samples
    4 more
    JavaScript
    PHP
    Ruby
    C#
curl -i -X GET \
  'https://api.unmarshal.com/v2/:chain/address/:address/assets?verified=false&pageSize=5&offset=0&chainId=false&token=false&aggregatedBalance=false&auth_key=YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "items_on_page": 5,
  • "next_offset": 5,
  • "assets": [
    ]
}

Profit and Loss

The Profit/Loss API returns the net profit or loss made by a specified address for a particular token.

unmarshal.WalletApi
    .getProfitAndLoss(Chain.ethereum, "demo.eth", "token-address")
    .then(({data}) => console.log(data))
Request
Security:
auth_key
path Parameters
address
required
string
Default: "demo.eth"

Any valid address or ENS

Example: demo.eth
chain
required
string

Chain name (example: bsc, ethereum, matic...)

Enum: "ethereum" "bsc" "matic"
Example: bsc
query Parameters
contract
required
string

Valid contract address

Responses
200
401
get/v2/{chain}/address/{address}/userData
Request samples
    4 more
    JavaScript
    PHP
    Ruby
    C#
curl -i -X GET \
  'https://api.unmarshal.com/v2/:chain/address/:address/userData?contract=string&auth_key=YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "quote_rate": 1.88,
  • "total_fees_paid": 0.00408196,
  • "total_fees_paid_usd": 12.35876252184,
  • "average_token_price": 0.6777538233562116,
  • "overall_profit_loss": 1390.998826376863,
  • "current_holding_quantity": 1157,
  • "percentage_change_24H": 3.87773,
  • "price_change_24H": 81.37875199999999
}

Token Holders Count

The Token Holders API enables the retrieval of the total number of token holders for a specific token contract address.

unmarshal.WalletApi
    .getTokenHoldersCount(Chain.ethereum, "token address")
    .then(({data}) => console.log(data))
Request
Security:
auth_key
path Parameters
chain
required
string
Enum: "ethereum" "bsc" "matic" "celo"
Example: ethereum
address
required
string

Any valid Erc20 token address

Example: 0x5a666c7d92E5fA7Edcb6390E4efD6d0CDd69cF37
Responses
200
401
get/v1/{chain}/token-address/{address}/holders-count
Request samples
    4 more
    JavaScript
    PHP
    Ruby
    C#
curl -i -X GET \
  'https://api.unmarshal.com/v1/:chain/token-address/:address/holders-count?auth_key=YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "token_holders_count": "3367"
}

Top Token Holders

The Top Holders API retrieves the list of the top token holders for a specific token on the Ethereum and Polygon blockchains.

Request
Security:
auth_key
path Parameters
chain
required
string
Enum: "ethereum" "matic"
Example: ethereum
contract
required
string

Any valid Erc20 token address

Example: 0x5a666c7d92E5fA7Edcb6390E4efD6d0CDd69cF37
Responses
200

Example response

401
get/v1/{chain}/contract/{contract}/top-holders
Request samples
    4 more
    JavaScript
    PHP
    Ruby
    C#
curl -i -X GET \
  'https://api.unmarshal.com/v1/:chain/contract/:contract/top-holders?auth_key=YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "token_address": "0x5a666c7d92e5fa7edcb6390e4efd6d0cdd69cf37",
  • "top_holders": [
    ],
  • "holders_count": 4070
}

Batch Assets

The Batch Assets API enables the retrieval of wallet balances across multiple blockchain networks by batching together multiple asset balance API requests. The API accepts comma-separated addresses and chains as input parameters, allowing for efficient retrieval of wallet balances on multiple networks in a single API call.

Request
Security:
auth_key
query Parameters
address
string

comma separated wallet addresses

chain
string

comma separated chains

Responses
200

OK

get/v1/batch-assets
Request samples
    4 more
    JavaScript
    PHP
    Ruby
    C#
curl -i -X GET \
  'https://api.unmarshal.com/v1/batch-assets?address=string&chain=string&auth_key=YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "0x8140e0d5ed099f45d616d61d7fbaf5b635e12647": {
    },
  • "0x963737c550e70ffe4d59464542a28604edb2ef9a": {
    }
}