Installation

Caution

Braga was retired at 23:59 CET on 12 August 2026 — see the Braga page for the full story. You can still install the SDK and read through the code below, but you can’t run it against a public network until the next testnet arrives in September 2026. A limited devnet is available in the meantime — ask about access on Discord.

Arkiv provides an official TypeScript/JavaScript SDK — @arkiv-network/sdk — that works in Node.js, Bun, and the browser. It handles client creation, queries, mutations, event subscriptions, and payload encoding.

The SDK builds on viem and declares it as a peer dependency, so install viem alongside the SDK.

Install the SDK

npm

npm install @arkiv-network/sdk viem

Bun

bun add @arkiv-network/sdk viem

Client Setup

WalletClient (read/write)

Requires a private key. Use for creating, updating, and deleting entities:

import { createWalletClient } from "@arkiv-network/sdk"
import { braga } from "@arkiv-network/sdk/chains"
import { http } from "viem"
import { privateKeyToAccount } from "viem/accounts"

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

Caution

Keep your private key in environment variables. Never hardcode it.

PublicClient (read-only)

No private key needed. Use for queries — safe for frontend use:

import { createPublicClient } from "@arkiv-network/sdk"
import { braga } from "@arkiv-network/sdk/chains"
import { http } from "viem"

const publicClient = createPublicClient({
  chain: braga,
  transport: http(),
})

Hello, World!

1. Create your project

   npm

   mkdir hello-arkiv && cd hello-arkiv
   npm init -y
   npm pkg set type=module
   npm install @arkiv-network/sdk viem typescript

   Bun

   mkdir hello-arkiv && cd hello-arkiv
   bun init -y
   bun add @arkiv-network/sdk viem

2. Add your private key

   .env

   PRIVATE_KEY=0xYOUR_PRIVATE_KEY_HERE

   Arkiv chains use GLM as the native gas token. The Braga faucet went offline when Braga was retired on 12 August 2026 — see the Braga page for what’s next.

3. Write your first entity

   hello.ts

   import { createWalletClient, createPublicClient } from '@arkiv-network/sdk';
   import { stringToPayload } from '@arkiv-network/sdk/utils';
   import { braga } from '@arkiv-network/sdk/chains';
   import { http } from 'viem';
   import { privateKeyToAccount } from 'viem/accounts';
   
   const walletClient = createWalletClient({
     chain: braga,
     transport: http(),
     account: privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`),
   });
   
   const publicClient = createPublicClient({
     chain: braga,
     transport: http(),
   });
   
   // Create an entity
   const { entityKey, txHash } = await walletClient.createEntity({
     payload: stringToPayload('Hello, Arkiv!'),
     contentType: 'text/plain',
     attributes: [{ key: 'type', value: 'greeting' }],
     expiresIn: 3600,
   });
   
   console.log('Entity created:', entityKey);
   console.log('Transaction:', txHash);
   
   // Read it back
   const entity = await publicClient.getEntity(entityKey);
   console.log('Retrieved:', entity.toText());

4. Run it

   Run it with:

   npm

   npx tsx --env-file=.env hello.ts

   Bun

   bun run hello.ts

   With Braga retired, this script has nowhere to send its transaction until the next public testnet ships.

Tip

Most real applications store JSON data. Use jsonToPayload instead of stringToPayload for structured data — see Mutating Data for details.

Note

All entities in Arkiv are stored in a shared database. Tag your data with a unique project attribute so your queries only return your app’s entities. See Best Practices.

Browser Usage (CDN)

For static HTML/JS pages without a bundler:

import { createPublicClient } from 'https://esm.sh/@arkiv-network/sdk?target=es2022&bundle-deps'
import { eq } from 'https://esm.sh/@arkiv-network/sdk/query?target=es2022&bundle-deps'
import { braga } from 'https://esm.sh/@arkiv-network/sdk/chains?target=es2022&bundle-deps'
import { http } from 'https://esm.sh/viem?target=es2022'