Skip to main content

Config and RPC Policy

Configuration precedence​

  1. Explicit createClient({...}) runtime config.
  2. Environment variable helpers (if your app maps env to runtime config).
  3. SDK defaults/presets.

Runtime mode requirements​

  • api mode:
    • requires api.baseUrl
  • contracts mode:
    • requires contracts.defaultNetwork + network RPC/contracts
  • hybrid mode:
    • combines API and contract configuration

Default RPC policy​

What this does: provides fast bootstrap with public RPC endpoints.

  • SDK presets include public-default RPC URLs.
  • In production, set dedicated provider URLs per network.
  • SDK warns when production-like environments rely on public defaults.

Expected result: local/dev setup works immediately, production remains configurable and explicit.

Production recommendation​

Use explicit contract network config:

const sdk = createClient({
  mode: 'contracts',
  contracts: {
    defaultNetwork: 'eip155:56',
    networks: {
      'eip155:56': {
        rpc: {
          http: [process.env.BNB_DEDICATED_RPC!],
          quality: 'recommended-production',
        },
        contracts: {
          router: process.env.BNB_ROUTER!,
          registry: process.env.BNB_REGISTRY!,
          sessionStore: process.env.BNB_SESSION_STORE!,
          subscriptions: process.env.BNB_SUBSCRIPTIONS!,
        },
      },
    },
  },
});

Common errors and fixes​

  • RPC timeout spikes: add failover endpoints.
  • Wrong chain selected: use CAIP-2 IDs (eip155:56, etc.) to avoid ambiguity.
  • Contract mismatch: keep addresses aligned with deployed environment.