Tokens
ICPay supports verified tokens across chains (IC ICRC and EVM). You can fetch lists (with or without price data), resolve canister IDs by symbol, and read detailed metadata.
Overview
- Each token provides
id,name,symbol,shortcode?,canisterId,decimals,fee,verified, and optional price data. - Prices are available when configured; USD conversions are supported via SDK helpers.
Data model
Selected fields exposed by the SDK:
type LedgerPublic = {
id: string
name: string
symbol: string
shortcode?: string | null
canisterId: string
chainId?: string // backend chain UUID or chain id (as string)
decimals: number
logoUrl: string | null
verified: boolean
fee: string | null
currentPrice: number | null
lastPriceUpdate: string | null
}
Detailed info:
type SdkLedger = {
id: string
name: string
symbol: string
chainId?: string // backend chain UUID or chain id (as string)
shortcode?: string | null
canisterId: string
decimals: number
logoUrl: string | null
verified: boolean
fee: string | null
network: 'mainnet' | 'testnet'
description: string | null
lastBlockIndex: string | null
coingeckoId: string | null
currentPrice: number | null
lastPriceUpdate: string | null
createdAt: string
updatedAt: string
}
Notes:
shortcodeis a human-friendly token identifier (e.g.,ic_icp,ic_ckusdc) that can be used in UX and filtering.chainIdrefers to the underlying chain (ICPay backend UUID) associated to the token.
Using with SDK
import { Icpay } from '@ic-pay/icpay-sdk'
const icpay = new Icpay({ publishableKey: 'pk_test_xxx' })
const list = await icpay.getVerifiedLedgers()
const idBySymbol = await icpay.getLedgerCanisterIdBySymbol('ICP')
const info = await icpay.getLedgerInfo(idBySymbol)
const withPrices = await icpay.getAllLedgersWithPrices()
// Convert 10 USD to token amount for a token
const calc = await icpay.calculateTokenAmountFromUSD({ usdAmount: 10, ledgerSymbol: 'ICP' })
Using with Widget
Widgets fetch verified tokens automatically. You can constrain choices via multichain filters in the widget config:
chainTypes?: Array<'ic' | 'evm'>chainShortcodes?: string[](e.g.,['ic','base'])tokenShortcodes?: string[](e.g.,['ic_icp','ic_ckusdc'])
Widget examples
'use client'
import { useEffect, useRef } from 'react'
import '@ic-pay/icpay-widget'
export default function Page() {
const ref = useRef<any>(null)
useEffect(() => {
if (!ref.current) return
ref.current.config = {
publishableKey: process.env.NEXT_PUBLIC_ICPAY_PK,
amountsUsd: [1,5,10],
// Optional filters to limit networks/tokens:
// chainTypes: ['ic','evm'],
// chainShortcodes: ['ic','base'],
// tokenShortcodes: ['ic_icp','ic_ckusdc'],
}
}, [])
return <icpay-tip-jar ref={ref as any} />
}