Installation

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

   Get test GLM from the Braga faucet — Braga uses GLM as its native gas token.

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

   npm

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

   Bun

   bun run hello.ts

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'