Utility Functions

Overview

This section covers the most commonly used helpers in the Push Chain Core SDK to simplify common workflows.

Helper Utilities

Parse Units

PushChain.utils.helpers.parseUnits(value, exponent): bigint

Converts a human-readable token amount into its smallest unit representation (bigint). It multiplies the given value by 10^decimals, ensuring amounts are safe for on-chain use.

Commonly used when preparing transaction parameters (e.g., converting 1.5 into 1500000000000000000, similar to how you convert ETH to wei, PC to uPC, or any other tokens to its smallest denominator).

const result = PushChain.utils.helpers.parseUnits('1.5', { decimals: 18 });
// variation: const result = PushChain.utils.helpers.parseUnits('1.5', 18);

// Returns: 1500000000000000000n (1.5 PC in uPC)

TheseArgumentsare mandatory

Arguments	Type	Description
`value`	`string`	The string representation of the number to parse. Can include decimals (e.g., `"1.5"`, `"420"`, `"0.1"`).
`exponent`	`number \| { decimals: number }`	Number of decimal places to scale by. Provide either a number (e.g., `18`) or an object with `decimals`. Must be a non-negative integer. Examples: `18` for PC/ETH, `6` for USDC, `8` for BTC.

Returns `value` <bigint>

// bigint - the scaled integer value
1500000000000000000n

Live Playground: Parse Units for Common Token Scenarios

VIRTUAL NODE IDE

Format Units

PushChain.utils.helpers.formatUnits(value, {options}): string

Converts a raw token amount in smallest units (bigint) into a human-readable decimal string. It divides the given value by 10^decimals, making it easy to display amounts for users.

Commonly used in UI or logs (e.g., turning 1500000000000000000 into 1.5 or any token from smallest unit to its human-readable value).

const result = PushChain.utils.helpers.formatUnits('1500000000000000000', { decimals: 18 });
// variation: const result = PushChain.utils.helpers.formatUnits('1500000000000000000', 18);

// Returns: 1.5 (1.5 PC in uPC)

TheseArgumentsare mandatory

Arguments	Type	Description
`value`	`bigint \| string`	Raw amount in smallest units (e.g., `'1500000000000000000'` for 1.5 assuming `18` decimals).
`options.decimals`	`number`	The number of decimal places to scale by. Must be a non-negative integer. For example, use `18` for PC or ETH, `6` for USDC, `8` for BTC.
`options.precision`	`number`	The number of precision to scale by, will round up the value. Must be a non-negative integer. For example, use `4` for returning 4 digits after the decimal.

Returns `value` <string>

// string - human readable value
1.5

Live Playground: Format Units for Common Token Scenarios

VIRTUAL NODE IDE

Encode Transaction Data

PushChain.utils.helpers.encodeTxData({abi, functionName, args}): string

const encodedData = PushChain.utils.helpers.encodeTxData({
  abi,
  functionName: 'functionName',
  args: []
});

TheseArgumentsare mandatory

Arguments	Type	Default	Description
`abi`	`any[]`	-	The ABI array of the smart contract containing function definitions.
`functionName`	`string`	-	The name of the function to encode transaction data for.
`args`	`any[]`	`[]`	The arguments to pass to the function. Defaults to empty array for functions with no parameters.

Returns `encodedData` <string>

// encodedData string - the encoded function call data
'0xd09de08a';

Live Playground: Encode Transaction Data for Smart Contract Function

VIRTUAL NODE IDE

Chain Utilities

Get Chain Namespace from Chain Name

PushChain.utils.chains.getChainNamespace(chainName): string

Every external chain is represented as a particular string on Push Chain. You can see the list of supported chains in the Chain Configuration section.

const chainName = PushChain.utils.chains.getChainNamespace('PUSH_TESTNET_DONUT');

TheseArgumentsare mandatory

Arguments	Type	Description
`name`	`string`	The chain name to convert to chain namespace. Eg: `PUSH_TESTNET_DONUT` converts to `eip155:42101`, `ETHEREUM_SEPOLIA` converts to `eip155:11155111`.

Returns `chainNamespace` <string>

// chainNamespace string
'eip155:42101';

// NOTE: returns undefined if chainName is unsupported

Live Playground: Get Chain Namespace from Chain Name

VIRTUAL NODE IDE

Get Chain Name from Chain Namespace

PushChain.utils.chains.getChainName(chainNamespace): string

Every external chain is represented as a particular string on Push Chain. You can see the list of supported chains in the chain configuration section.

const chainName = PushChain.utils.chains.getChainName('eip155:42101');

TheseArgumentsare mandatory

Arguments	Type	Description
`namespace`	`string`	The chain namespace to convert to chain name. Eg: `eip155:42101` converts to `PUSH_TESTNET_DONUT`, `eip155:11155111` converts to `ETHEREUM_SEPOLIA`.

Returns `chainName` <string>

// chainName string
'PUSH_TESTNET_DONUT';

// NOTE: returns undefined if chainNamespace is unsupported

Live Playground: Get Chain Name from Chain Namespace

VIRTUAL NODE IDE

Get Supported Chains By Name

PushChain.utils.chains.getSupportedChainsByName(pushNetwork): { chains: [] }

Returns the list of supported chain names (human-readable strings) for a given Push Network.

const chains = PushChain.utils.chains.getSupportedChainsByName(PushChain.CONSTANTS.PUSH_NETWORK.TESTNET);

TheseArgumentsare mandatory

Arguments	Type	Description
`pushNetwork`	`PushChain.CONSTANTS.PUSH_NETWORK`	Push Chain network to retrieve list of supported chain names from. For example: `PushChain.CONSTANTS.PUSH_NETWORK.TESTNET` PushChain.CONSTANTS.PUSH_NETWORK `PushChain.CONSTANTS.PUSH_NETWORK.TESTNETPushChain.CONSTANTS.PUSH_NETWORK.LOCALNET`

Returns `{ chains }` <object>

// { chains } object - returns human-readable chain names as strings
{
  chains: [
    'PUSH_TESTNET_DONUT',
    'ETHEREUM_SEPOLIA',
    'ARBITRUM_SEPOLIA',
    'BASE_SEPOLIA',
    'BNB_TESTNET',
    'SOLANA_DEVNET',
    // ...
  ]
}

// NOTE: returns empty chains array if pushNetwork is unsupported

Live Playground: Get Supported Chains By Name for a given Push Network

VIRTUAL NODE IDE

Get Supported Chains

PushChain.utils.chains.getSupportedChains(pushNetwork): { chains: [] }

Returns the list of chains supported for a given Push Network.

const chains = PushChain.utils.chains.getSupportedChains(PushChain.CONSTANTS.PUSH_NETWORK.TESTNET);

TheseArgumentsare mandatory

Arguments	Type	Description
`pushNetwork`	`PushChain.CONSTANTS.PUSH_NETWORK`	Push Chain network to retrieve list of supported chains from. For example: `PushChain.CONSTANTS.PUSH_NETWORK.TESTNET` PushChain.CONSTANTS.PUSH_NETWORK `PushChain.CONSTANTS.PUSH_NETWORK.TESTNETPushChain.CONSTANTS.PUSH_NETWORK.LOCALNET`

Returns `{ chains }` <object>

// { chains } object
{
  chains: [
    PushChain.CONSTANTS.CHAIN.PUSH_TESTNET,
    PushChain.CONSTANTS.CHAIN.ETHEREUM_SEPOLIA,
    PushChain.CONSTANTS.CHAIN.ARBITRUM_SEPOLIA,
    PushChain.CONSTANTS.CHAIN.BASE_SEPOLIA,
    PushChain.CONSTANTS.CHAIN.BNB_TESTNET,
    PushChain.CONSTANTS.CHAIN.SOLANA_DEVNET,
    // ...
  ]
}

// NOTE: returns empty chains array if pushNetwork is unsupported

Live Playground: Get Supported Chains for a given Push Network

VIRTUAL NODE IDE

Account Utilities

Convert to Universal Account

PushChain.utils.account.toUniversal(address, {options}): <UniversalAccount>

const account = PushChain.utils.account.toUniversal(address, {
  chain: PushChain.CONSTANTS.CHAIN.ETHEREUM_SEPOLIA,
});

TheseArgumentsare mandatory

Arguments	Type	Description
`address`	`string`	An address string (e.g., `0xabc...`).
`options.chain`	`CHAIN`	The target chain for the signer. For example: `PushChain.CONSTANTS.CHAIN.PUSH_TESTNET_DONUT` PushChain.CONSTANTS.CHAIN `PushChain.CONSTANTS.CHAIN.PUSH_MAINNETPushChain.CONSTANTS.CHAIN.PUSH_TESTNETPushChain.CONSTANTS.CHAIN.PUSH_TESTNET_DONUTPushChain.CONSTANTS.CHAIN.PUSH_LOCALNETPushChain.CONSTANTS.CHAIN.ETHEREUM_MAINNETPushChain.CONSTANTS.CHAIN.ETHEREUM_SEPOLIAPushChain.CONSTANTS.CHAIN.SOLANA_MAINNETPushChain.CONSTANTS.CHAIN.SOLANA_TESTNETPushChain.CONSTANTS.CHAIN.SOLANA_DEVNET`

Returns `UniversalAccount` <object>

// UniversalAccount object
{
  chain: 'eip155:11155111',
  address: '0xD8d6aF611a17C236b13235B5318508FA61dE3Dba'
}

Live Playground: Convert Ethereum Sepolia Address to UniversalAccount

VIRTUAL NODE IDE

Convert to Chain-Agnostic Address

PushChain.utils.account.toChainAgnostic(address, {options}): string

const chainAgnosticAddress = PushChain.utils.account.toChainAgnostic(address, {
  chain: PushChain.CONSTANTS.CHAIN.ETHEREUM_SEPOLIA,
});

TheseArgumentsare mandatory

Arguments	Type	Description
`address`	`string`	An address string (e.g., `0xabc...`).
`options.chain`	`CHAIN`	The target chain for the signer. For example: `PushChain.CONSTANTS.CHAIN.PUSH_TESTNET_DONUT` PushChain.CONSTANTS.CHAIN `PushChain.CONSTANTS.CHAIN.PUSH_MAINNETPushChain.CONSTANTS.CHAIN.PUSH_TESTNETPushChain.CONSTANTS.CHAIN.PUSH_TESTNET_DONUTPushChain.CONSTANTS.CHAIN.PUSH_LOCALNETPushChain.CONSTANTS.CHAIN.ETHEREUM_MAINNETPushChain.CONSTANTS.CHAIN.ETHEREUM_SEPOLIAPushChain.CONSTANTS.CHAIN.SOLANA_MAINNETPushChain.CONSTANTS.CHAIN.SOLANA_TESTNETPushChain.CONSTANTS.CHAIN.SOLANA_DEVNET`

Returns `ChainAgnosticAddress` <string>

// Chain Agnostic Address
'eip155:11155111:0xD8d6aF611a17C236b13235B5318508FA61dE3Dba';

Live Playground: Convert Ethereum Sepolia address to chain agnostic address

VIRTUAL NODE IDE

Convert from Chain-Agnostic to Universal Account

PushChain.utils.account.fromChainAgnostic(chainAgnosticAddress): <UniversalAccount>

const account = PushChain.utils.account.fromChainAgnostic(chainAgnosticAddress);

TheseArgumentsare mandatory

Arguments	Type	Description
`chainAgnosticAddress`	`string`	A full chain agnostic address string (e.g., `eip155:11155111:0x35B84d6848D16415177c64D64504663b998A6ab4`).

Returns `UniversalAccount` <object>

// UniversalAccount object: { chain: string, address: string }
{
  chain: 'eip155:11155111',
  address: '0xD8d6aF611a17C236b13235B5318508FA61dE3Dba'
}

Live Playground: Convert Ethereum Sepolia chain agnostic address to UniversalAccount

VIRTUAL NODE IDE

Derive Executor Account

PushChain.utils.account.deriveExecutorAccount(universalAccount, { options? }): Promise<{ address: string, deployed?: boolean }>

Derives the execution account for a given input account. This function supports multiple derivation flows based on the input and options provided.

Use Cases:

UOA → UEA: Derive a Universal Executor Account on Push Chain from a Universal Origin Account
Push account / UOA → CEA: Derive a Chain Executor Account on an external chain from a Push Chain account or UOA
Push-native account: Returns the same account if it's already a Push Chain native account

// Derive UEA from UOA
const universalAccount = PushChain.utils.account.toUniversal(
  '0xD8d6aF611a17C236b13235B5318508FA61dE3Dba',
  { chain: PushChain.CONSTANTS.CHAIN.ETHEREUM_SEPOLIA }
);
const result = await PushChain.utils.account.deriveExecutorAccount(universalAccount);

// Derive UEA from Solana account
const solanaAccount = PushChain.utils.account.toUniversal(
  'EUYcfSUScdFgKMbB3rRdgRZwXmcxY7QCRQa2JwrchP1Q',
  { chain: PushChain.CONSTANTS.CHAIN.SOLANA_DEVNET }
);
const ueaResult = await PushChain.utils.account.deriveExecutorAccount(solanaAccount);

// Derive CEA from Push account
const pushAccount = PushChain.utils.account.toUniversal(
  '0x98cA97d2FB78B3C0597E2F78cd11868cACF423C5',
  { chain: PushChain.CONSTANTS.CHAIN.PUSH_TESTNET }
);
const ceaResult = await PushChain.utils.account.deriveExecutorAccount(
  pushAccount,
  { chain: PushChain.CONSTANTS.CHAIN.BNB_TESTNET }
);

// Derive CEA from Solana account that will be there on BNB Testnet
const ceaSolanaResult = await PushChain.utils.account.deriveExecutorAccount(
  solanaAccount,
  { chain: PushChain.CONSTANTS.CHAIN.BNB_TESTNET }
);

TheseArgumentsare mandatory

Arguments	Type	Default	Description
`universalAccount`	`UniversalAccount`	-	UniversalAccount object created via `toUniversal()`. Represents any blockchain account in a universal format.
`options.chain`	`CHAIN`	`undefined`	Optional. When provided, derives a Chain Executor Account (CEA) on the specified external chain. Use `PushChain.CONSTANTS.CHAIN` values. PushChain.CONSTANTS.CHAIN `PushChain.CONSTANTS.CHAIN.PUSH_TESTNETPushChain.CONSTANTS.CHAIN.PUSH_TESTNET_DONUTPushChain.CONSTANTS.CHAIN.ETHEREUM_SEPOLIAPushChain.CONSTANTS.CHAIN.BNB_TESTNETPushChain.CONSTANTS.CHAIN.BASE_SEPOLIAPushChain.CONSTANTS.CHAIN.ARBITRUM_SEPOLIAPushChain.CONSTANTS.CHAIN.SOLANA_DEVNET`
`options.skipNetworkCheck`	`boolean`	`false`	When `true`, performs deterministic derivation only without checking deployment status. When `false`, includes deployment/existence check.

Returns `{ address, deployed? }` <object>

// Response object
{
  address: '0x98cA97d2FB78B3C0597E2F78cd11868cACF423C5',
  deployed: true  // Only included when skipNetworkCheck is false
}

Live Playground: Derive Executor Account

VIRTUAL NODE IDE

Resolve Controller Account

PushChain.utils.account.resolveControllerAccount(account, { options? }): Promise<{ accounts: Array<AccountInfo> }>

Resolves the controller identity behind an execution account. This function supports recursive resolution to trace back to the original Universal Origin Account (UOA).

Use Cases:

UEA → UOA: Resolve the Universal Origin Account from a Universal Executor Account
CEA → Push account → UOA: Resolve through Chain Executor Account to Push account, then to UOA if applicable
Recursive resolution: Automatically follows the chain of derivation back to the controller identity

// Resolve UOA from UEA
const result = await PushChain.utils.account.resolveControllerAccount('0xUEA...');

// Resolve from CEA with chain context
const ceaResult = await PushChain.utils.account.resolveControllerAccount(
  '0xCEA...',
  { chain: PushChain.CONSTANTS.CHAIN.BNB_TESTNET }
);

TheseArgumentsare mandatory

Arguments	Type	Default	Description
`account`	`string`	-	Executor account to resolve. Can be a UEA, CEA, or Push Chain account address.
`options.chain`	`CHAIN`	`undefined`	Required for CEA context. Specifies which chain the CEA is deployed on. Use `PushChain.CONSTANTS.CHAIN` values. PushChain.CONSTANTS.CHAIN `PushChain.CONSTANTS.CHAIN.PUSH_TESTNETPushChain.CONSTANTS.CHAIN.PUSH_TESTNET_DONUTPushChain.CONSTANTS.CHAIN.ETHEREUM_SEPOLIAPushChain.CONSTANTS.CHAIN.BNB_TESTNETPushChain.CONSTANTS.CHAIN.BASE_SEPOLIAPushChain.CONSTANTS.CHAIN.ARBITRUM_SEPOLIAPushChain.CONSTANTS.CHAIN.SOLANA_DEVNET`
`options.skipNetworkCheck`	`boolean`	`false`	When `true`, performs deterministic resolution only without checking existence. When `false`, includes existence check.

Returns `{ accounts }` <object>

// Example 1: Resolving CEA that has UEA with UOA controller
{
  accounts: [
    {
      chain: 'eip155:42101',
      chainName: 'PUSH_TESTNET_DONUT',
      address: '0x2Fd904d6f2C0b34d58426C8Ae9c5267E845CE98f',
      type: 'uea',
      exists: true
    },
    {
      chain: 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1',
      chainName: 'SOLANA_DEVNET',
      address: '72JBejJFXrRKpQ69Hmaqr7vWJr6pdZXFEL6jt3sadsXU',
      type: 'uoa',
      exists: true,
      role: 'controller'
    }
  ]
}

// Example 2: Resolving CEA from Push Account (EOA) or smart contract
{
  accounts: [
    {
      chain: 'eip155:42101',
      chainName: 'PUSH_TESTNET_DONUT',
      address: '0x2Fd904d6f2C0b34d58426C8Ae9c5267E845CE98f',
      type: 'uoa',
      exists: true,
      role: 'controller'
    }
  ]
}

Field	Type	Description
`accounts`	`Array`	Array of account objects in the resolution chain
`chain`	`string`	Chain namespace identifier (e.g., `eip155:42101`, `solana:EtWTRABZaYq...`)
`chainName`	`string`	Human-readable chain constant name (e.g., `PUSH_TESTNET_DONUT`, `SOLANA_DEVNET`)
`address`	`string`	Account address on the chain
`type`	`string`	Account type: `uea`, `uoa`, or `cea`
`exists`	`boolean`	Whether the account exists on-chain
`role`	`string`	`controller` indicates the controlling account in the resolution chain

Live Playground: Resolve Controller Account

VIRTUAL NODE IDE

Signer Utilities

Create Universal Signer from Keypair

PushChain.utils.signer.toUniversalFromKeypair(keypair, {options}): Promise<UniversalSigner>

const universalSigner = await PushChain.utils.signer.toUniversalFromKeypair(
  keypair,
  {
    chain: PushChain.CONSTANTS.CHAIN.SOLANA_DEVNET,
    library: PushChain.CONSTANTS.LIBRARY.SOLANA_WEB3JS,
  }
);

TheseArgumentsare mandatory

Arguments	Type	Description
`keypair`	`Keypair`	A keypair object from one of the supported libraries (ethers v5/v6, viem, or a custom UniversalSignerSkeleton)
`options.chain`	`CHAIN`	The target chain for the signer. For example: `PushChain.CONSTANTS.CHAIN.PUSH_TESTNET_DONUT` PushChain.CONSTANTS.CHAIN `PushChain.CONSTANTS.CHAIN.PUSH_MAINNETPushChain.CONSTANTS.CHAIN.PUSH_TESTNETPushChain.CONSTANTS.CHAIN.PUSH_TESTNET_DONUTPushChain.CONSTANTS.CHAIN.PUSH_LOCALNETPushChain.CONSTANTS.CHAIN.ETHEREUM_MAINNETPushChain.CONSTANTS.CHAIN.ETHEREUM_SEPOLIAPushChain.CONSTANTS.CHAIN.SOLANA_MAINNETPushChain.CONSTANTS.CHAIN.SOLANA_TESTNETPushChain.CONSTANTS.CHAIN.SOLANA_DEVNET`
`options.library`	`LIBRARY`	The library to use for the signer. For example: `PushChain.CONSTANTS.LIBRARY.ETHEREUM_ETHERSV6` PushChain.CONSTANTS.LIBRARY `PushChain.CONSTANTS.LIBRARY.ETHEREUM_ETHERSV6PushChain.CONSTANTS.LIBRARY.ETHEREUM_VIEMPushChain.CONSTANTS.LIBRARY.SOLANA_WEB3JS`

Returns `UniversalSigner` <object>

// UniversalSigner object
{
  account: {
    address: '0xD173b7f04D539A5794e14030c4E172B2E3df92f3',
    chain: 'eip155:11155111'
  },
  signMessage: [Function: signMessage],
  signAndSendTransaction: [Function: signAndSendTransaction],
  signTypedData: [Function: signTypedData]
}

Live Playground: Create Universal Signer from Keypair

Ethers (v6)
Viem
Solana (Web3 JS)

VIRTUAL NODE IDE

Token Utilities

Get Moveable Tokens

PushChain.utils.tokens.getMoveableTokens(chainOrClient?): { tokens: [] }

Commonly used to get list of supported assets that can be moved across chains. See send universal transaction for more info.

// All supported moveable tokens across chains
const { tokens: allMoveable } = PushChain.utils.tokens.getMoveableTokens();

// Filtered for a specific chain
const { tokens: sepoliaMoveable } = PushChain.utils.tokens.getMoveableTokens(
  PushChain.CONSTANTS.CHAIN.ETHEREUM_SEPOLIA
);

TheseArgumentsare mandatory

Arguments	Type	Description
`chainOrClient`	`CHAIN \| PushChain`	Optional. A chain enum or an initialized client to filter tokens for that chain.

Returns `{ tokens }` <object>

// tokens object { tokens: [] }
{
  tokens: [
    { chain: 'eip155:11155111', symbol: 'ETH', decimals: 18, address: '0x...' },
    { chain: 'eip155:11155111', symbol: 'USDC', decimals: 6, address: '0x...' },
    // ...
  ]
}

Live Playground: List moveable tokens for a specific chain

VIRTUAL NODE IDE

Get Payable Tokens

PushChain.utils.tokens.getPayableTokens(chainOrClient?): { tokens: [] }

Commonly used to get list of supported assets to pay with (either for gas or token movement) across chains. See send universal transaction for more info.

// All supported payable tokens across chains
const { tokens: allPayable } = PushChain.utils.tokens.getPayableTokens();

// Filtered for a specific chain
const { tokens: solanaDevnetPayable } = PushChain.utils.tokens.getPayableTokens(
  PushChain.CONSTANTS.CHAIN.SOLANA_DEVNET
);

TheseArgumentsare mandatory

Arguments	Type	Description
`chainOrClient`	`CHAIN \| PushChain`	Optional. A chain enum or an initialized client to filter tokens for that chain.

Returns `{ tokens }` <object>

// tokens object { tokens: [] }
{
  tokens: [
    { chain: 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1', symbol: 'SOL', decimals: 9, address: 'So11111111111111111111111111111111111111112' },
    { chain: 'eip155:11155111', symbol: 'USDC', decimals: 6, address: '0x...' },
    // ...
  ]
}

Live Playground: List payable tokens for a specific chain

VIRTUAL NODE IDE

Get PRC20 Address

PushChain.utils.tokens.getPRC20Address(token): 0x${string}

Resolves the Push Chain synthetic PRC20 address for a supported origin-chain token. Accepts either a MoveableToken (for example from getMoveableTokens) or an object containing the origin chain and token address.

const prc20 = PushChain.utils.tokens.getPRC20Address(ethMoveableToken);

// Or with explicit chain/address input
const prc20Alt = PushChain.utils.tokens.getPRC20Address({
  chain: PushChain.CONSTANTS.CHAIN.ETHEREUM_SEPOLIA,
  address: ethMoveableToken.address,
});

TheseArgumentsare mandatory

Arguments	Type	Description
`token`	`MoveableToken \| { chain: string; address: string }`	Origin token info. Either pass a `MoveableToken` (e.g., from `pushChainClient.moveable.token.*`) or provide the origin chain plus token address.

Returns `prc20Address` <string>

// Synthetic PRC20 address on Push Chain
'0x...'

Live Playground: Map origin token to PRC20 on Push Chain

VIRTUAL NODE IDE

Conversion Utilities

Calculate Minimum Amount from Slippage

PushChain.utils.conversion.slippageToMinAmount(amount, { slippageBps }): string

const minOut = PushChain.utils.conversion.slippageToMinAmount('100000000', {
  slippageBps: 100, // 1%
});
// Returns: '99000000'

TheseArgumentsare mandatory

Arguments	Type	Description
`amount`	`string`	Input amount in smallest units (e.g., '100000000' for 100 USDC as it has 6 decimals).
`options.slippageBps`	`number` (integer)	Slippage in basis points. `100 = 1%`, `50 = 0.5%`.

Returns `minOut` <string>

// minOut `string` (in smallest units)
'99000000'

Live Playground: Calculate minimum amount out from slippage

VIRTUAL NODE IDE

Get Conversion Quote

pushChainClient.funds.getConversionQuote(amount, {options}): Promise<ConversionQuote>

Note: This function is available only after initializing the Push Chain client.

The function is used to get conversion quote especially when you want to pay with (from) one token, move as (to) another token. Used in send universal transaction for token movement across chains or to pay gas in other tokens instead of native token of the source chain.

Convention: from = the token you pay with (Payable), to = the token you move as (Moveable).

const quote = pushChainClient.funds.getConversionQuote('100000000', {
  from: PushChain.CONSTANTS.PAYABLE.TOKEN.ETHEREUM_SEPOLIA.WETH,
  to: PushChain.CONSTANTS.MOVEABLE.TOKEN.ETHEREUM_SEPOLIA.USDT,
});

// Returns: { "amountIn": "5000000000000000", "amountOut": "11813463066488417", "rate": 2362692613297.683, "route": [ "WETH", "USDT" ], "timestamp": 1758582899267 }

Arguments	Type	Description
`amount`	`string`	The string representation of the amount to parse. Can include decimals (e.g., "1.5", "420", "0.1").
`options.from`	`PushChain.CONSTANTS.PAYABLE.TOKEN`	The token you pay with. PushChain.CONSTANTS.PAYABLE.TOKEN `PushChain.CONSTANTS.PAYABLE.TOKEN.ETHEREUM_SEPOLIA.ETHPushChain.CONSTANTS.PAYABLE.TOKEN.ETHEREUM_SEPOLIA.USDTPushChain.CONSTANTS.PAYABLE.TOKEN.ETHEREUM_SEPOLIA.USDCPushChain.CONSTANTS.PAYABLE.TOKEN.ETHEREUM_SEPOLIA.WETHPushChain.CONSTANTS.PAYABLE.TOKEN.ETHEREUM_SEPOLIA.stETHPushChain.CONSTANTS.PAYABLE.TOKEN.ARBITRUM_SEPOLIA.ETHPushChain.CONSTANTS.PAYABLE.TOKEN.ARBITRUM_SEPOLIA.USDTPushChain.CONSTANTS.PAYABLE.TOKEN.ARBITRUM_SEPOLIA.USDCPushChain.CONSTANTS.PAYABLE.TOKEN.BASE_SEPOLIA.ETHPushChain.CONSTANTS.PAYABLE.TOKEN.BASE_SEPOLIA.USDTPushChain.CONSTANTS.PAYABLE.TOKEN.BASE_SEPOLIA.USDCPushChain.CONSTANTS.PAYABLE.TOKEN.BNB_TESTNET.BNBPushChain.CONSTANTS.PAYABLE.TOKEN.BNB_TESTNET.USDTPushChain.CONSTANTS.PAYABLE.TOKEN.SOLANA_DEVNET.SOLPushChain.CONSTANTS.PAYABLE.TOKEN.SOLANA_DEVNET.USDTPushChain.CONSTANTS.PAYABLE.TOKEN.SOLANA_DEVNET.USDC`
`options.to`	`PushChain.CONSTANTS.MOVEABLE.TOKEN`	The token you move as. PushChain.CONSTANTS.MOVEABLE.TOKEN `PushChain.CONSTANTS.MOVEABLE.TOKEN.ETHEREUM_SEPOLIA.ETHPushChain.CONSTANTS.MOVEABLE.TOKEN.ETHEREUM_SEPOLIA.USDTPushChain.CONSTANTS.MOVEABLE.TOKEN.ETHEREUM_SEPOLIA.USDCPushChain.CONSTANTS.MOVEABLE.TOKEN.ETHEREUM_SEPOLIA.WETHPushChain.CONSTANTS.MOVEABLE.TOKEN.ETHEREUM_SEPOLIA.stETHPushChain.CONSTANTS.MOVEABLE.TOKEN.ARBITRUM_SEPOLIA.ETHPushChain.CONSTANTS.MOVEABLE.TOKEN.ARBITRUM_SEPOLIA.USDTPushChain.CONSTANTS.MOVEABLE.TOKEN.ARBITRUM_SEPOLIA.USDCPushChain.CONSTANTS.MOVEABLE.TOKEN.ARBITRUM_SEPOLIA.WETHPushChain.CONSTANTS.MOVEABLE.TOKEN.BASE_SEPOLIA.ETHPushChain.CONSTANTS.MOVEABLE.TOKEN.BASE_SEPOLIA.USDTPushChain.CONSTANTS.MOVEABLE.TOKEN.BASE_SEPOLIA.USDCPushChain.CONSTANTS.MOVEABLE.TOKEN.BASE_SEPOLIA.WETHPushChain.CONSTANTS.MOVEABLE.TOKEN.BNB_TESTNET.ETHPushChain.CONSTANTS.MOVEABLE.TOKEN.BNB_TESTNET.USDTPushChain.CONSTANTS.MOVEABLE.TOKEN.SOLANA_DEVNET.SOLPushChain.CONSTANTS.MOVEABLE.TOKEN.SOLANA_DEVNET.USDTPushChain.CONSTANTS.MOVEABLE.TOKEN.SOLANA_DEVNET.USDCPushChain.CONSTANTS.MOVEABLE.TOKEN.PUSH_TESTNET_DONUT.pEthPushChain.CONSTANTS.MOVEABLE.TOKEN.PUSH_TESTNET_DONUT.pEthArbPushChain.CONSTANTS.MOVEABLE.TOKEN.PUSH_TESTNET_DONUT.pEthBasePushChain.CONSTANTS.MOVEABLE.TOKEN.PUSH_TESTNET_DONUT.pEthBnbPushChain.CONSTANTS.MOVEABLE.TOKEN.PUSH_TESTNET_DONUT.pSolPushChain.CONSTANTS.MOVEABLE.TOKEN.PUSH_TESTNET_DONUT.USDT.ethPushChain.CONSTANTS.MOVEABLE.TOKEN.PUSH_TESTNET_DONUT.USDT.arbPushChain.CONSTANTS.MOVEABLE.TOKEN.PUSH_TESTNET_DONUT.USDT.basePushChain.CONSTANTS.MOVEABLE.TOKEN.PUSH_TESTNET_DONUT.USDT.bnbPushChain.CONSTANTS.MOVEABLE.TOKEN.PUSH_TESTNET_DONUT.USDT.solPushChain.CONSTANTS.MOVEABLE.TOKEN.PUSH_TESTNET_DONUT.USDC.ethPushChain.CONSTANTS.MOVEABLE.TOKEN.PUSH_TESTNET_DONUT.USDC.arbPushChain.CONSTANTS.MOVEABLE.TOKEN.PUSH_TESTNET_DONUT.USDC.basePushChain.CONSTANTS.MOVEABLE.TOKEN.PUSH_TESTNET_DONUT.USDC.bnbPushChain.CONSTANTS.MOVEABLE.TOKEN.PUSH_TESTNET_DONUT.USDC.sol`

Supported chains

funds.getConversionQuote currently works on Ethereum Mainnet and Sepolia. Other origins will throw an error.

Returns `ConversionQuote` <object>

Field	Type	Description
`amountIn`	`string`	Input amount in smallest units
`amountOut`	`string`	Output amount in smallest units
`rate`	`number`	Normalized rate: tokenOut per tokenIn
`route`	`string[]`	Optional swap path (e.g., `["WETH","USDT"]`)
`timestamp`	`number`	Unix time (ms)

Live Playground: Quote WETH → USDT on Sepolia

VIRTUAL NODE IDE

Explorer Utilities

Get Transaction URL

pushChainClient.explorer.getTransactionUrl(txHash, { options? }): string

Note: This function is available only after initializing the Push Chain client.

Returns the explorer URL for a given transaction hash. By default, uses the chain from the initialized pushChainClient. When options.chain is provided, generates the explorer URL for that specific chain instead.

// Default: Uses client's chain (Push Chain)
const url = pushChainClient.explorer.getTransactionUrl(txHash);

// Override: Generate URL for external chain explorer
const sepoliaUrl = pushChainClient.explorer.getTransactionUrl(txHash, {
  chain: PushChain.CONSTANTS.CHAIN.ETHEREUM_SEPOLIA
});

TheseArgumentsare mandatory

Arguments	Type	Description
`txHash`	`string`	The transaction hash to convert to explorer URL.
`options.chain`	`CHAIN`	Optional. Override the chain for explorer URL generation. When provided, generates the URL for that chain's explorer instead of the client's chain. Use `PushChain.CONSTANTS.CHAIN` values. PushChain.CONSTANTS.CHAIN `PushChain.CONSTANTS.CHAIN.PUSH_MAINNETPushChain.CONSTANTS.CHAIN.PUSH_TESTNETPushChain.CONSTANTS.CHAIN.PUSH_TESTNET_DONUTPushChain.CONSTANTS.CHAIN.PUSH_LOCALNETPushChain.CONSTANTS.CHAIN.ETHEREUM_MAINNETPushChain.CONSTANTS.CHAIN.ETHEREUM_SEPOLIAPushChain.CONSTANTS.CHAIN.SOLANA_MAINNETPushChain.CONSTANTS.CHAIN.SOLANA_TESTNETPushChain.CONSTANTS.CHAIN.SOLANA_DEVNET`

Returns `url` <string>

// Push Chain transaction URL (default)
'https://donut.push.network/tx/0x828911db033c65de8faab4906cfcb7d13ce225c3cd283534d110414a5b78cf87'

// External chain transaction URL (when options.chain is provided)
'https://sepolia.etherscan.io/tx/0x828911db033c65de8faab4906cfcb7d13ce225c3cd283534d110414a5b78cf87'

Live Playground: Get Explorer URL for a transaction hash

VIRTUAL NODE IDE

List Explorer URLs

pushChainClient.explorer.listUrls({ options? }): { explorers: [] }

Note: This function is available only after initializing the Push Chain client.

Returns explorer URLs for a specific chain. By default, uses the chain from the initialized pushChainClient. When options.chain is provided, returns explorer URLs for that specific chain instead.

// Default: Uses client's chain
const result = pushChainClient.explorer.listUrls();

// Override: Get explorer URLs for specific chain
const sepoliaExplorers = pushChainClient.explorer.listUrls({
  chain: PushChain.CONSTANTS.CHAIN.ETHEREUM_SEPOLIA
});

TheseArgumentsare mandatory

Arguments	Type	Description
`options.chain`	`CHAIN`	Optional. Override the chain to get explorer URLs for. When provided, returns explorer URLs for that specific chain. Use `PushChain.CONSTANTS.CHAIN` values. PushChain.CONSTANTS.CHAIN `PushChain.CONSTANTS.CHAIN.PUSH_TESTNETPushChain.CONSTANTS.CHAIN.PUSH_TESTNET_DONUTPushChain.CONSTANTS.CHAIN.ETHEREUM_SEPOLIAPushChain.CONSTANTS.CHAIN.BNB_TESTNETPushChain.CONSTANTS.CHAIN.BASE_SEPOLIAPushChain.CONSTANTS.CHAIN.ARBITRUM_SEPOLIAPushChain.CONSTANTS.CHAIN.SOLANA_DEVNET`

Returns `{ explorers }` <object>

// explorers object
{
  explorers: [
    {
      chain: 'eip155:42101',
      chainName: 'PUSH_TESTNET_DONUT',
      urls: ['https://donut.push.network', 'https://scan.push.org']
    }
  ]
}

Live Playground: List Explorer URLs for a specific chain

VIRTUAL NODE IDE

List All Explorer URLs

pushChainClient.explorer.listAllUrls(): { explorers: [] }

Note: This function is available only after initializing the Push Chain client.

Returns explorer URLs for all supported chains in the current Push Network.

// ... Initialize Push Chain Client
const allExplorers = pushChainClient.explorer.listAllUrls();

Returns `{ explorers }` <object>

// explorers object with all supported chains
{
  explorers: [
    {
      chain: 'eip155:42101',
      chainName: 'PUSH_TESTNET_DONUT',
      urls: ['https://donut.push.network', 'https://scan.push.org']
    },
    {
      chain: 'eip155:11155111',
      chainName: 'ETHEREUM_SEPOLIA',
      urls: ['https://sepolia.etherscan.io']
    },
    {
      chain: 'eip155:421614',
      chainName: 'ARBITRUM_SEPOLIA',
      urls: ['https://sepolia.arbiscan.io']
    },
    // ... more chains
  ]
}

Live Playground: List All Explorer URLs for all supported chains

VIRTUAL NODE IDE

Deprecated Methods

Convert Origin to Executor Account

⚠️ Deprecated: This function is deprecated and will be removed in v6.0.0. Use deriveExecutorAccount instead.

PushChain.utils.account.convertOriginToExecutor(account, {options}): Promise<ExecutorAccountInfo>

Gives the deterministic executor account address for a given origin account (UOA).

Also helps in checking if a given origin account (UOA) has a universal executor account (UEA) deployed on Push Chain or a chain executor account (CEA) deployed on any external chain.

const info =
  await PushChain.utils.account.convertOriginToExecutor(universalAccount);

Deprecated Function	Replacement	Key Changes
`convertOriginToExecutor`	`deriveExecutorAccount`	• Parameter renamed: `onlyCompute` → `skipNetworkCheck` • Generic `account` parameter accepts string instead of UniversalAccount object • Clearer naming aligned with identity ↔ execution model

TheseArgumentsare mandatory

Arguments	Type	Default	Description
`account`	`UniversalAccount`	-	A UniversalAccount object containing chain and address information.
`options.onlyCompute`	`boolean`	`false`	Whether to check if the computed executor account is deployed. Set to `true` to include deployment status.

Returns `ExecutorAccountInfo` <object>

// ExecutorAccountInfo object
{
  address: '0x98cA97d2FB78B3C0597E2F78cd11868cACF423C5',
  deployed: true
}

Live Playground: Convert Origin Account to Universal Executor Account

VIRTUAL NODE IDE

Convert Executor Address to Origin Account

⚠️ Deprecated: This function is deprecated and will be removed in v6.0.0. Use resolveControllerAccount instead.

PushChain.utils.account.convertExecutorToOriginAccount(address): Promise<OriginAccountInfo>

Gives the origin account (UOA) for a given Push Chain address.

const { account, exists } = await PushChain.utils.account.convertExecutorToOriginAccount(pushChainAddress);

Deprecated Function	Replacement	Key Changes
`convertExecutorToOriginAccount`	`resolveControllerAccount`	• Same functionality with clearer naming • Part of unified identity ↔ execution model

TheseArgumentsare mandatory

Arguments	Type	Default	Description
`pushChainAddress`	`string`	-	Address of the account on Push Chain.

Returns `OriginAccountInfo` <object>

// OriginAccountInfo object
{
  account: {
    chain: 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1',
    address: 'FNDJWigdNWsmxXYGrFV2gCvioLYwXnsVxZ4stL33wFHf'
  },
  exists: true
}

Live Playground: Convert Executor Account to Origin Account

VIRTUAL NODE IDE

Next Steps

Dive into reading blockchain state
Harness our on-chain contract helpers to supercharge your app
Explore and abstract away wallet and any chain-related logic using UI Kit

Start building

Quick Start

Learn with tutorials

Explore Push Chain

Join Discord

Explore Examples

Utility Functions

Overview

Helper Utilities

Parse Units

Format Units

Encode Transaction Data

Chain Utilities

Get Chain Namespace from Chain Name

Get Chain Name from Chain Namespace

Get Supported Chains By Name

Get Supported Chains

Account Utilities

Convert to Universal Account

Convert to Chain-Agnostic Address

Convert from Chain-Agnostic to Universal Account

Derive Executor Account

Resolve Controller Account

Signer Utilities

Create Universal Signer from Keypair

Token Utilities

Get Moveable Tokens

Get Payable Tokens

Get PRC20 Address

Conversion Utilities

Calculate Minimum Amount from Slippage

Get Conversion Quote

Explorer Utilities

Get Transaction URL

List Explorer URLs

List All Explorer URLs

Deprecated Methods

Convert Origin to Executor Account

Convert Executor Address to Origin Account

Next Steps

Start building

Quick Start

Learn with tutorials

Explore Push Chain

Join Discord

Explore Examples

Overview​

Helper Utilities​

Parse Units​

Format Units​

Encode Transaction Data​

Chain Utilities​

Get Chain Namespace from Chain Name​

Get Chain Name from Chain Namespace​

Get Supported Chains By Name​

Get Supported Chains​

Account Utilities​

Convert to Universal Account​

Convert to Chain-Agnostic Address​

Convert from Chain-Agnostic to Universal Account​

Derive Executor Account​

Resolve Controller Account​

Signer Utilities​

Create Universal Signer from Keypair​

Token Utilities​

Get Moveable Tokens​

Get Payable Tokens​

Get PRC20 Address​

Conversion Utilities​

Calculate Minimum Amount from Slippage​

Get Conversion Quote​

Explorer Utilities​

Get Transaction URL​

List Explorer URLs​

List All Explorer URLs​

Deprecated Methods​

Convert Origin to Executor Account​

Convert Executor Address to Origin Account​

Next Steps​

Overview

Helper Utilities

Parse Units

Format Units

Encode Transaction Data

Chain Utilities

Get Chain Namespace from Chain Name

Get Chain Name from Chain Namespace

Get Supported Chains By Name

Get Supported Chains

Account Utilities

Convert to Universal Account

Convert to Chain-Agnostic Address

Convert from Chain-Agnostic to Universal Account

Derive Executor Account

Resolve Controller Account

Signer Utilities

Create Universal Signer from Keypair

Token Utilities

Get Moveable Tokens

Get Payable Tokens

Get PRC20 Address

Conversion Utilities

Calculate Minimum Amount from Slippage

Get Conversion Quote

Explorer Utilities

Get Transaction URL

List Explorer URLs

List All Explorer URLs

Deprecated Methods

Convert Origin to Executor Account

Convert Executor Address to Origin Account

Next Steps