Tier

Query ticket tier configurations.

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

Try It

Tier Namespace Demo

Query tier configurations with supply statistics. Tiers follow a deterministic ID pattern: odd IDs are tickets, even IDs are stubs.

SQL endpoint URL

Contract address

Query

List all tiers for a contract.

await client.tier.listByContract({
  contractAddress,
  limit: 10,
  orderBy: 'tokenId',
  order: 'asc',
})

Browser requests require CORS to be enabled.

Results

Methods

get

Get a tier by contract address and token ID.

import { Client } from '@sceneinfrastructure/sdk'
 
const client = Client.create({ url: '...' })
 
const tier = await client.tier.get({
  contractAddress: '0x1234567890123456789012345678901234567890',
  tokenId: 1n
})
 
if (tier) {
  console.log('Token URI:', tier.tokenURI)
  console.log('Stub URI:', tier.stubURI)
  console.log('Max supply:', tier.quantity)
}

Parameters

Parameter	Type	Description
`contractAddress`	`Address`	The contract address
`tokenId`	`bigint`	The tier token ID (odd numbers are tickets)

Returns

Tier | null - The tier data or null if not found.

getWithSupply

Get a tier with current supply information.

import { Client } from '@sceneinfrastructure/sdk'
 
const client = Client.create({ url: '...' })
 
const tier = await client.tier.getWithSupply({
  contractAddress: '0x1234567890123456789012345678901234567890',
  tokenId: 1n
})
 
if (tier) {
  console.log('Max supply:', tier.supply.maxSupply)
  console.log('Minted:', tier.supply.minted)
  console.log('Remaining:', tier.supply.remaining)
  console.log('Stubbed:', tier.supply.stubbed)
  console.log('Active (unstubbed):', tier.supply.active)
}

Parameters

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

Returns

TierWithSupply | null - Tier with supply data or null if not found.

getStats

Get statistics for a tier.

import { Client } from '@sceneinfrastructure/sdk'
 
const client = Client.create({ url: '...' })
 
const stats = await client.tier.getStats({
  contractAddress: '0x1234567890123456789012345678901234567890',
  tokenId: 1n
})
 
if (stats) {
  console.log('Total sold:', stats.sold)
  console.log('Total stubbed:', stats.stubbed)
  console.log('Stub rate:', stats.stubRate) // e.g., 75 = 75%
  console.log('Remaining:', stats.remaining)
}

Parameters

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

Returns

TierStats | null - Statistics or null if tier not found.

listByContract

List all tiers for a contract.

import { Client } from '@sceneinfrastructure/sdk'
 
const client = Client.create({ url: '...' })
 
const tiers = await client.tier.listByContract({
  contractAddress: '0x1234567890123456789012345678901234567890',
  limit: 20,
  orderBy: 'tokenId',
  order: 'asc'
})
 
for (const tier of tiers) {
  console.log(`Tier ${tier.tokenId}: ${tier.tokenURI}`)
}

Parameters

Parameter	Type	Default	Description
`contractAddress`	`Address`	required	The contract address
`limit`	`number`	`50`	Maximum results to return
`offset`	`number`	`0`	Number of results to skip
`orderBy`	`'createdAt' \| 'tokenId'`	`'createdAt'`	Sort field
`order`	`'asc' \| 'desc'`	`'desc'`	Sort direction

Returns

Tier[] - Array of tiers.

listByContractWithSupply

List all tiers for a contract with supply information.

import { Client } from '@sceneinfrastructure/sdk'
 
const client = Client.create({ url: '...' })
 
const tiers = await client.tier.listByContractWithSupply({
  contractAddress: '0x1234567890123456789012345678901234567890',
  limit: 20
})
 
for (const tier of tiers) {
  console.log(`Tier ${tier.tokenId}:`)
  console.log(`  Minted: ${tier.supply.minted}/${tier.supply.maxSupply}`)
  console.log(`  Active: ${tier.supply.active}`)
}

Parameters

Parameter	Type	Default	Description
`contractAddress`	`Address`	required	The contract address
`limit`	`number`	`50`	Maximum results to return
`offset`	`number`	`0`	Number of results to skip

Returns

TierWithSupply[] - Array of tiers with supply data.

Types

Tier

import type { Address, Hex } from 'viem'
 
type Tier = {
  contractAddress: Address
  tokenId: bigint
  tokenURI: string
  stubTokenId: bigint
  stubURI: string
  quantity: bigint  // Max supply (0 = unlimited)
  createdAt: bigint
  createdAtBlock: bigint
  createdAtLogIndex: number
  creationTxHash: Hex
  updatedAt: bigint
  updatedAtBlock: bigint
  updatedAtLogIndex: number
  updatedTxHash: Hex | null
}

Field	Type	Description
`tokenId`	`bigint`	Ticket token ID (odd: 1, 3, 5...)
`stubTokenId`	`bigint`	Stub token ID (even: 2, 4, 6...)
`tokenURI`	`string`	Metadata URI for tickets
`stubURI`	`string`	Metadata URI for stubs
`quantity`	`bigint`	Max supply (0 = unlimited)

TierSupply

type TierSupply = {
  maxSupply: bigint        // From tier.quantity
  minted: bigint           // Total minted
  remaining: bigint | null // maxSupply - minted (null if unlimited)
  stubbed: bigint          // Number converted to stubs
  voided: bigint           // Number voided (refunds, cancellations)
  active: bigint           // minted - stubbed - voided
}

TierStats

type TierStats = {
  sold: bigint           // Total sold (minted)
  stubbed: bigint        // Total stubbed (checked in)
  stubRate: number       // Percentage stubbed (0-100)
  remaining: bigint | null // Remaining supply (null if unlimited)
}

TierWithSupply

type TierWithSupply = Tier & {
  supply: TierSupply
}

Schema

Zod Validation

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