2. Gateway SDK: Reading Ledger State

Overview

The Gateway SDK is a TypeScript client for the Radix Gateway API. It lets you query account balances, read component state, look up transaction history, and submit transactions — all the read/write operations your dApp frontend needs.

npm install @radixdlt/babylon-gateway-api-sdk

Setup

import { GatewayApiClient, RadixNetwork } from '@radixdlt/babylon-gateway-api-sdk'
 
const gatewayApi = GatewayApiClient.initialize({
  networkId: RadixNetwork.Mainnet,  // or RadixNetwork.Stokenet
  applicationName: 'My dApp',
  applicationVersion: '1.0.0',
  applicationDappDefinitionAddress: 'account_rdx...'
})

The SDK connects to the Radix Foundation's public Gateway by default. For production dApps with high traffic, consider running your own Gateway node or using a third-party provider.

Common Queries

Account Balances

const details = await gatewayApi.state.getEntityDetailsVaultAggregated(
  'account_rdx1c956...'  // account address
)
// details.fungible_resources — token balances
// details.non_fungible_resources — NFT holdings

Component State

const component = await gatewayApi.state.getEntityDetailsVaultAggregated(
  'component_rdx1cp...'  // component address
)
// Read state, vaults, metadata

Entity Metadata

const metadata = await gatewayApi.state.getAllEntityMetadata(
  'resource_rdx1t...'  // any entity address
)
// Returns: name, symbol, description, icon_url, etc.

Transaction Status

const status = await gatewayApi.transaction.getStatus(
  'txid_rdx1...'  // intent hash from sendTransaction
)
// status.intent_status: "CommittedSuccess" | "CommittedFailure" | "Pending" | ...

Historical State

Query state at a specific point in time by passing at_ledger_state:

const historicalDetails = await gatewayApi.state.innerClient.stateEntityDetails({
  stateEntityDetailsRequest: {
    addresses: ['account_rdx1...']
    at_ledger_state: { state_version: 12345678 }
  }
})

External Links

Difficulty:	Intermediate
Language:	TypeScript
Prerequisites:	Radix dApp Toolkit
Est. Time:	20 minutes

Gateway SDK
Difficulty	Intermediate
Est. Time	20 minutes
Prerequisites	Radix dApp Toolkit
Language	TypeScript
NPM	@radixdlt/babylon-gateway-api-sdk

Author:Hydrate...

Updated:2d ago

Created:Feb 22, 2026

Revisions:1

Setup

import { GatewayApiClient, RadixNetwork } from '@radixdlt/babylon-gateway-api-sdk'
 
const gatewayApi = GatewayApiClient.initialize({
  networkId: RadixNetwork.Mainnet,  // or RadixNetwork.Stokenet
  applicationName: 'My dApp',
  applicationVersion: '1.0.0',
  applicationDappDefinitionAddress: 'account_rdx...'
})

The SDK connects to the Radix Foundation's public Gateway by default. For production dApps with high traffic, consider running your own Gateway node or using a third-party provider.

Common Queries

Account Balances

const details = await gatewayApi.state.getEntityDetailsVaultAggregated(
  'account_rdx1c956...'  // account address
)
// details.fungible_resources — token balances
// details.non_fungible_resources — NFT holdings

Component State

const component = await gatewayApi.state.getEntityDetailsVaultAggregated(
  'component_rdx1cp...'  // component address
)
// Read state, vaults, metadata

Entity Metadata

const metadata = await gatewayApi.state.getAllEntityMetadata(
  'resource_rdx1t...'  // any entity address
)
// Returns: name, symbol, description, icon_url, etc.

const historicalDetails = await gatewayApi.state.innerClient.stateEntityDetails({ stateEntityDetailsRequest: { addresses: ['account_rdx1...'] at_ledger_state: { state_version: 12345678 } } })