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.

Install the SDK

npm

npm install @arkiv-network/sdk

Bun

bun add @arkiv-network/sdk

Client Setup

WalletClient (read/write)

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

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

const walletClient = createWalletClient({
  chain: kaolin,
  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, http } from "@arkiv-network/sdk"
import { kaolin } from "@arkiv-network/sdk/chains"

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

Hello, World!

1. Create your project

   npm

   mkdir hello-arkiv && cd hello-arkiv
   npm init -y
   npm install @arkiv-network/sdk dotenv typescript

   Bun

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

2. Add your private key

   .env

   PRIVATE_KEY=0xYOUR_PRIVATE_KEY_HERE

   Get test ETH from the Kaolin Faucet.

3. Write your first entity

   hello.ts

   import { createWalletClient, createPublicClient, http } from '@arkiv-network/sdk';
   import { stringToPayload } from '@arkiv-network/sdk/utils';
   import { kaolin } from '@arkiv-network/sdk/chains';
   import { privateKeyToAccount } from '@arkiv-network/sdk/accounts';
   import { config } from 'dotenv';
   
   config({ path: '.env' });
   
   const walletClient = createWalletClient({
     chain: kaolin,
     transport: http(),
     account: privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`),
   });
   
   const publicClient = createPublicClient({
     chain: kaolin,
     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 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, http } from 'https://esm.sh/@arkiv-network/sdk@0.6.0?target=es2022&bundle-deps'
import { eq } from 'https://esm.sh/@arkiv-network/sdk@0.6.0/query?target=es2022&bundle-deps'
import { kaolin } from 'https://esm.sh/@arkiv-network/sdk@0.6.0/chains?target=es2022&bundle-deps'