Get MATIC wallet balance

GET /v1/polygon/wallet/balance/{address} returns the native MATIC balance held by a Polygon address. The balance covers native MATIC only — it does not include ERC-20 token balances, which live in their own contracts (use GET /v1/polygon/wallet/tokens/{address} for those).

This is one of the few endpoints available on the free tier with no authentication. You can call it without an API key; sending a Authorization: Bearer $TRIPORT_API_KEY header simply raises the per-second rate limit applied to your requests.

The response gives you the balance two ways: wei as a u256 decimal string (the exact on-chain value — always parse it with a big-integer type to avoid precision loss) and matic as a convenience floating-point value already divided by 10¹⁸. By default the balance is read at the latest block; pass the block query parameter to read it at a specific height or block tag.

Path parameters

Response fields

Errors use the shared REST envelope (error code + message, with an optional request_id). See errors.md for the full envelope and every shared code.

{
  "error": "rate_limited",
  "message": "Sustained RPS exceeded for category polygon_read_rpc.",
  "retry_after_sec": 1,
  "limit_rps": 5,
  "current_tier": "free",
  "category": "polygon_read_rpc"
}

JavaScript (fetch)

const address = "0x0000000000000000000000000000000000001010";


const res = await fetch(
  `https://api.triport.io/v1/polygon/wallet/balance/${address}`,
  {
    headers: {
      // Optional on the free tier; required for higher rate limits.
      "Authorization": `Bearer ${process.env.TRIPORT_API_KEY}`,
    },
  },
);


const { wei, matic, block } = await res.json();
console.log(`${matic} MATIC (${BigInt(wei)} wei) at block ${block}`);

TypeScript SDK (@triport/sdk)

import { Triport } from "@triport/sdk";


const client = new Triport({ apiKey: process.env.TRIPORT_API_KEY });


const balance = await client.polygon.wallet.balance(
  "0x0000000000000000000000000000000000001010",
  { block: "latest" },
);


console.log(balance.matic);        // 12.45
console.log(BigInt(balance.wei));  // 12450000000000000000n

Python (triport-sdk)

import os
from triport import Triport


client = Triport(api_key=os.environ.get("TRIPORT_API_KEY"))


balance = client.polygon.wallet.balance(
    "0x0000000000000000000000000000000000001010",
    block="latest",
)


print(balance.matic)        # 12.45
print(int(balance.wei))     # 12450000000000000000

• Use wei for exactness. matic is a double provided for convenience and can lose precision on large balances. For accounting, parse the wei decimal string with a big-integer type and divide by 10¹⁸ yourself.
• Block selection. pending reflects not-yet-mined state and may change; latest is the safest default. A historical block number lets you read the balance at any past height.
• Native MATIC only. For ERC-20 holdings use /v1/polygon/wallet/tokens/{address}; for transaction history use /v1/polygon/wallet/history/{address}.
• Rate limits are enforced per second per tier with up to 2× burst, and there is no daily cap. Sending an API key on this otherwise-anonymous endpoint raises your limit — see authentication and rate limits.