Skip to main content
GET
/
v1
/
wallets
/
{walletAddressOrPublicKey}
/
tokens
Get BTC balances for a Bitcoin address or xpub
curl --request GET \
  --url https://api.moralis.com/v1/wallets/{walletAddressOrPublicKey}/tokens \
  --header 'X-Api-Key: <api-key>'
{
  "meta": {
    "syncedAt": {
      "bitcoin": "latest"
    },
    "unsupportedChains": [],
    "failedChains": []
  },
  "address": "0xcb1c1fde09f811b294172696404e88e658659905",
  "addressType": "evm",
  "cursor": "eyJhbGciOi...VCaaw",
  "result": [
    {
      "tokenAddress": "0xdac17f958d2ee523a2206206994597c13d831ec7",
      "balanceRaw": "8541786218567066193031597821",
      "chainId": "bitcoin",
      "name": "Tether USD",
      "symbol": "USDT",
      "decimals": 6,
      "logo": "https://logo.moralis.io/0x1_0xdac17f958d2ee523a2206206994597c13d831ec7_3b83ef2ba0dba0e3385a845032e48304.webp",
      "possibleSpam": false,
      "verifiedContract": true,
      "balance": "8541786218567066193031.597821",
      "securityScore": 99,
      "portfolioPercentage": 100,
      "usdPrice": 1,
      "usdPrice24hrUsdChange": 0,
      "usdPrice24hrPercentChange": 0,
      "usdValue": 1,
      "usdValue24hrUsdChange": 0,
      "nativeToken": false,
      "derivedAddress": "1EfgV2Hr5CDjXPavHDpDMjmU33BA2veHy6",
      "derivedPath": "m/44'/0'/0'/0/0"
    }
  ]
}
The walletAddressOrPublicKey path parameter accepts either a Bitcoin address or an xpub — when an xpub is supplied, balances are aggregated across all derived addresses server-side.
Address auto-detection: for a Bitcoin address or xpub, the chains parameter is optional — Moralis detects the chain family from the address format. Passing chains=bitcoin explicitly still works.

Authorizations

​
X-Api-Key
string
header
required

Path Parameters

​
walletAddressOrPublicKey
string
required

A Bitcoin address or an xpub. When an xpub is supplied, the API derives all addresses server-side.

Query Parameters

​
chains
enum<string>[]

Chains to query. For the Bitcoin API, pass bitcoin.

Available options:
bitcoin
​
cursor
string

The cursor to the next page

​
limit
number
default:100

The limit per page

Required range: 1 <= x <= 1000
​
tokenAddresses
string[]

The token addresses to be filtered in

Example:
[
  "0xdac17f958d2ee523a2206206994597c13d831ec7"
]
​
excludeSpam
boolean
default:false

Should exclude spam contract

Example:

true

​
excludeUnverifiedContracts
boolean
default:false

Should exclude unverified contract

Example:

true

​
excludeNative
boolean
default:false

Should exclude native contract

Example:

true

​
maxTokenInactivity
number

Should filter out contract exceeding max token inactivity

Example:

1

​
liquidityThreshold
number

Should filter out contract under liquidity threshold

Example:

0

Response

200 - application/json
​
meta
object
required

Metadata about the multi-chain request

​
address
string
required

The wallet address

Example:

"0xcb1c1fde09f811b294172696404e88e658659905"

​
addressType
enum<string>
required

The wallet address type

Available options:
bitcoin
Example:

"evm"

​
cursor
string | null
required

The cursor to be used for getting the next page of results

Example:

"eyJhbGciOi...VCaaw"

​
result
object[]
required

The list of items