Installation

This guide targets the Tiramisu testnet. Check Networks for current testnets and faucets.

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 watching, and payload encoding.

The SDK builds on viem. It declares viem as a peer dependency. 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)

WalletClient needs a private key. Use it to create, patch, and delete entities:

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

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

Caution

Keep your private key in environment variables. Do not hardcode it.

PublicClient (read-only)

PublicClient needs no private key. Use it for queries. It is safe for frontend use:

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

const publicClient = createPublicClient({
  chain: tiramisu,
  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. Get test GLM from the faucet.

3. Write your first entity

   hello.ts

   import { createWalletClient, createPublicClient, ExpirationTime } from '@arkiv-network/sdk';
   import { stringToPayload } from '@arkiv-network/sdk/utils';
   import { tiramisu } from '@arkiv-network/sdk/chains';
   import { http } from 'viem';
   import { privateKeyToAccount } from 'viem/accounts';
   
   const walletClient = createWalletClient({
     chain: tiramisu,
     transport: http(),
     account: privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`),
   });
   
   const publicClient = createPublicClient({
     chain: tiramisu,
     transport: http(),
   });
   
   // Create an entity
   const { entityKey, txHash } = await walletClient.createEntity({
     payload: stringToPayload('Hello, Arkiv!'),
     contentType: 'text/plain',
     attributes: { type: 'greeting' },
     expires: ExpirationTime.fromHours(1),
   });
   
   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

Tip

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

Note

Arkiv stores all entities in a shared database. Tag your data with a unique project attribute. Then your queries return only 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 { tiramisu } from 'https://esm.sh/@arkiv-network/sdk/chains?target=es2022&bundle-deps'
import { http } from 'https://esm.sh/viem?target=es2022'