SDK setup and authentication

Install @bloxchain/sdk, pin it to a Protocol release, and connect it to Ethereum with the right keys.

You need: Node.js 18.20 or later, an RPC URL on Sepolia, a wallet key for writes

Before you start

• The SDK does not use Bloxchain API keys. "Authentication" means two things: how your code reaches an Ethereum RPC, and which wallet signs governed operations.
• Sign-in on bloxchain.app is separate from the SDK. It is how you reach organization features on the Platform, including alerts on Pro; it grants no on-chain rights and issues no keys for contract calls.
• Permissions live on chain. A key can only do what its address is allowed to do in the account's roles and actions.

Install

npm install @bloxchain/sdk viem
# optional: ABIs and artifacts aligned with the same release
npm install @bloxchain/contracts

Package	Purpose
@bloxchain/sdk	Typed wrappers (SecureOwnable, RuntimeRBAC, GuardController, BaseStateMachine), meta-transaction signer, definition helpers
@bloxchain/contracts	ABIs and deployment artifacts for the same release (optional)
viem	Ethereum clients used by the SDK (PublicClient, WalletClient)

Pin versions

Pin @bloxchain/sdk and @bloxchain/contracts to exact versions that match the Protocol release your accounts were deployed from. Mismatched ABIs fail in confusing ways. Where to find the current versions and how npm versions relate to the on-chain contract version: Releases and compatibility.

Environment variables

RPC_URL=https://...            # Sepolia RPC endpoint
ACCOUNT_ADDRESS=0x...          # the smart account (the governed contract), not your business-logic contract
PRIVATE_KEY=0x...              # development only; see key handling below

Never commit .env files. Use a dedicated test key on Sepolia.

Public client versus wallet client

Client	Use for	Key needed
PublicClient	Reading owner, roles, time lock, pending requests, receipts and logs	No
WalletClient	Posting requests, approving, submitting meta-transactions	Yes

Every SDK class takes a PublicClient, an optional WalletClient, the account address and the chain:

import { SecureOwnable } from '@bloxchain/sdk';
import { createPublicClient, createWalletClient, http } from 'viem';
import { sepolia } from 'viem/chains';
import { privateKeyToAccount } from 'viem/accounts';

const publicClient = createPublicClient({ chain: sepolia, transport: http(process.env.RPC_URL) });

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const walletClient = createWalletClient({ account, chain: sepolia, transport: http(process.env.RPC_URL) });

const accountAddress = process.env.ACCOUNT_ADDRESS as `0x${string}`;

// Read-only: pass undefined for the wallet client
const reader = new SecureOwnable(publicClient, undefined, accountAddress, sepolia);

// Read and write
const writer = new SecureOwnable(publicClient, walletClient, accountAddress, sepolia);

Signer keys versus broadcaster keys

Governed operations separate the address that authorises from the address that submits.

Key	Holds	What it does	Where it usually lives
Signer (owner, approver or a custom role)	A role with request or approval permission	Posts a request, approves on chain, or signs an approval or one-signature request off chain	A wallet a person controls, ideally hardware
Broadcaster	The protected Broadcaster role (1 to 3 addresses)	Submits signed meta-transactions and pays gas. Cannot approve anything by itself.	A service or relay you run

A backend that only submits should hold a Broadcaster key. A backend that must also approve is holding an approver key and should be treated as such. The protected Owner and Recovery keys should not be automation keys at all.

Key handling in development and production

Development (Sepolia)

• Use throwaway keys funded with test ETH.
• Keep keys in environment variables or a local secret file outside version control.

Production (when mainnet deploys open)

• Keep keys in a secret store or hardware signer, not in .env files or CI logs.
• Use different keys for requester, approver and broadcaster roles when your policy separates them.
• Give the broadcaster service the Broadcaster role only. Do not reuse Owner or Recovery keys in services.
• Rotate a compromised signer off its role through a governed role change; there is no global "revoke all signatures" switch. See Meta-transactions.

Check that a key can act

Before automating, confirm the address holds the role the action needs:

import { RuntimeRBAC } from '@bloxchain/sdk';

const rbac = new RuntimeRBAC(publicClient, undefined, accountAddress, sepolia);
const roles = await rbac.getWalletRoles(account.address);
console.log('Role hashes for this key:', roles);

In the Platform, open the same account and check My access with the same wallet. See My access.

Troubleshooting

Symptom	Fix
Reads work, writes revert	The key lacks the role or the action's permission for that step. Check roles, gates and allowlists.
ABI decode errors	SDK version does not match the deployed release. Pin per Releases.
Wrong chain errors	The chain passed to the SDK must match the RPC and the account's network.

Related

• Developer quickstart
• SDK core patterns
• Protocol getting started
• API reference