> For the complete documentation index, see [llms.txt](https://docs.bloxchain.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bloxchain.app/developers/sdk-setup.md).

# 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

```bash
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](/resources/releases.md).

## Environment variables

```bash
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:

```typescript
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](/protocol-reference/api-reference/meta-transactions.md).

## Check that a key can act

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

```typescript
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](/platform-guide/operate/my-access.md).

## 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](/resources/releases.md).        |
| Wrong chain errors        | The `chain` passed to the SDK must match the RPC and the account's network.                         |

## Related

* [Developer quickstart](/get-started/developer-quickstart.md)
* [SDK core patterns](/developers/sdk-setup/sdk-core-patterns.md)
* [Protocol getting started](/protocol-reference/getting-started.md)
* [API reference](/protocol-reference/api-reference.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.bloxchain.app/developers/sdk-setup.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.