Balance

Query token holder balances.

import { Client } from '@sceneinfrastructure/sdk'
 
const client = Client.create({ url: '...' })

Try It

Balance Namespace Demo

Query token holder balances. Supports the ticket/stub pattern where odd token IDs are unredeemed tickets and even IDs are stubs.

SQL endpoint URL

Contract address

Query

Token ID

Holder address

Get balance for a specific holder and token.

await client.balance.get({
  contractAddress,
  tokenId,
  address,
})

Browser requests require CORS to be enabled.

Results

Methods

get

Get a specific balance for a token and holder.

import { Client } from '@sceneinfrastructure/sdk'
 
const client = Client.create({ url: '...' })
 
const balance = await client.balance.get({
  contractAddress: '0x1234567890123456789012345678901234567890',
  tokenId: 1n,
  address: '0x2345678901234567890123456789012345678901'
})
 
if (balance) {
  console.log('Balance:', balance.balance)
}

Parameters

Parameter	Type	Description
`contractAddress`	`Address`	The contract address
`tokenId`	`bigint`	The token ID
`address`	`Address`	The holder address

Returns

Balance | null - The balance record or null if not found.

getTokenStatus

Get detailed status for a holder's tokens and stubs.

import { Client } from '@sceneinfrastructure/sdk'
 
const client = Client.create({ url: '...' })
 
const status = await client.balance.getTokenStatus({
  contractAddress: '0x1234567890123456789012345678901234567890',
  tokenId: 1n,  // Ticket token ID (odd)
  address: '0x2345678901234567890123456789012345678901'
})
 
console.log('Ticket count:', status.tokenCount)
console.log('Stub count:', status.stubCount)
console.log('Has tickets:', status.hasTokens)
console.log('Has stubs:', status.hasStubs)
console.log('Fully stubbed:', status.isFullyStubbed)

Parameters

Parameter	Type	Description
`contractAddress`	`Address`	The contract address
`tokenId`	`bigint`	The ticket token ID (odd number)
`address`	`Address`	The holder address

Returns

TokenStatus - Status object with token and stub counts.

getHoldings

Get all token holdings for an address.

import { Client } from '@sceneinfrastructure/sdk'
 
const client = Client.create({ url: '...' })
 
const holdings = await client.balance.getHoldings({
  address: '0x2345678901234567890123456789012345678901'
})
 
console.log('Tickets:', holdings.tokens.length)
console.log('Stubs:', holdings.stubs.length)
 
// Filter by contract
const contractHoldings = await client.balance.getHoldings({
  address: '0x2345678901234567890123456789012345678901',
  contractAddress: '0x1234567890123456789012345678901234567890'
})
 
// Filter by minimum balance
const significantHoldings = await client.balance.getHoldings({
  address: '0x2345678901234567890123456789012345678901',
  minBalance: 5n
})

Parameters

Parameter	Type	Default	Description
`address`	`Address`	required	The holder address
`contractAddress`	`Address`	-	Filter to specific contract
`minBalance`	`bigint`	`1n`	Minimum balance to include

Returns

TokenHoldings - Object with tokens and stubs arrays.

isStubbed

Check if a holder has converted their tickets to stubs.

import { Client } from '@sceneinfrastructure/sdk'
 
const client = Client.create({ url: '...' })
 
const stubbed = await client.balance.isStubbed({
  contractAddress: '0x1234567890123456789012345678901234567890',
  tokenId: 1n,
  address: '0x2345678901234567890123456789012345678901'
})
 
if (stubbed) {
  console.log('User has checked in')
}

Parameters

Parameter	Type	Description
`contractAddress`	`Address`	The contract address
`tokenId`	`bigint`	The ticket token ID
`address`	`Address`	The holder address

Returns

boolean - True if the holder has any stubs for this tier.

listByToken

List all holders of a specific token.

import { Client } from '@sceneinfrastructure/sdk'
 
const client = Client.create({ url: '...' })
 
const holders = await client.balance.listByToken({
  contractAddress: '0x1234567890123456789012345678901234567890',
  tokenId: 1n,
  limit: 100
})
 
for (const balance of holders) {
  console.log(`${balance.address}: ${balance.balance}`)
}
 
// Filter by minimum balance
const whales = await client.balance.listByToken({
  contractAddress: '0x1234567890123456789012345678901234567890',
  tokenId: 1n,
  minBalance: 10n
})

Parameters

Parameter	Type	Default	Description
`contractAddress`	`Address`	required	The contract address
`tokenId`	`bigint`	required	The token ID
`minBalance`	`bigint`	-	Minimum balance to include
`limit`	`number`	`50`	Maximum results to return
`offset`	`number`	`0`	Number of results to skip

Returns

Balance[] - Array of balance records.

listByHolder

List all balances for a specific holder.

import { Client } from '@sceneinfrastructure/sdk'
 
const client = Client.create({ url: '...' })
 
const balances = await client.balance.listByHolder({
  address: '0x2345678901234567890123456789012345678901',
  limit: 100
})
 
for (const balance of balances) {
  console.log(`Token ${balance.tokenId}: ${balance.balance}`)
}
 
// Filter by contract
const contractBalances = await client.balance.listByHolder({
  address: '0x2345678901234567890123456789012345678901',
  contractAddress: '0x1234567890123456789012345678901234567890'
})

Parameters

Parameter	Type	Default	Description
`address`	`Address`	required	The holder address
`contractAddress`	`Address`	-	Filter to specific contract
`minBalance`	`bigint`	-	Minimum balance to include
`limit`	`number`	`50`	Maximum results to return
`offset`	`number`	`0`	Number of results to skip

Returns

Balance[] - Array of balance records.

hasBalance

Check if a holder has any balance of a specific token.

import { Client } from '@sceneinfrastructure/sdk'
 
const client = Client.create({ url: '...' })
 
const hasTicket = await client.balance.hasBalance({
  contractAddress: '0x1234567890123456789012345678901234567890',
  tokenId: 1n,
  address: '0x2345678901234567890123456789012345678901'
})
 
if (hasTicket) {
  console.log('User has tickets')
}

Parameters

Parameter	Type	Description
`contractAddress`	`Address`	The contract address
`tokenId`	`bigint`	The token ID
`address`	`Address`	The holder address

Returns

boolean - True if balance > 0.

Types

Balance

import type { Address, Hex } from 'viem'
 
type Balance = {
  contractAddress: Address
  tokenId: bigint
  address: Address
  balance: bigint
  createdAt: bigint
  createdAtBlock: bigint
  createdAtLogIndex: number
  creationTxHash: Hex
  updatedAt: bigint
  updatedAtBlock: bigint
  updatedAtLogIndex: number
  updatedTxHash: Hex | null
}

Field	Type	Description
`contractAddress`	`Address`	The contract address
`tokenId`	`bigint`	The token ID
`address`	`Address`	The holder address
`balance`	`bigint`	Current balance

TokenStatus

type TokenStatus = {
  tokenCount: bigint   // Balance of ticket token (odd ID)
  stubCount: bigint    // Balance of stub token (even ID)
  hasTokens: boolean   // tokenCount > 0
  hasStubs: boolean    // stubCount > 0
  isFullyStubbed: boolean  // hasStubs && !hasTokens
}

TokenHoldings

import type { Balance } from '@sceneinfrastructure/sdk'
 
type TokenHoldings = {
  tokens: Balance.Balance[]  // Balances with odd token IDs (tickets)
  stubs: Balance.Balance[]   // Balances with even token IDs (stubs)
}

Schema

Zod Validation

import { Balance } from '@sceneinfrastructure/sdk'
 
const data = {} // Data from API or external source
 
const result = Balance.schema.safeParse(data)
 
if (result.success) {
  console.log('Valid balance:', result.data)
}