DOCS/ v1

DOCS/Setup Guide

Setup Guide

Five steps from zero to live blockchain data. Follow them in order — each one builds on the last.

STEP 1

Get your API key

Every SDK call is authenticated with an API key. Go to dashboard → API Keys → click Create key. Copy it immediately — it will not be shown again.

awz_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxKey format — never commit this to Git

⚠️

Never commit your API key to Git or paste it directly in source files. Store it as an environment variable and ensure .env is in your .gitignore.

STEP 2

Install the right package

Pick your track below. You can install more packages any time — they are fully independent.

TRACK ANode.js · scripts · backend · Vite (non-React)

Core SDK only. Works in Node 18+, Deno, Bun, Edge runtimes, and browser bundles.

CORE SDK

$npm install @awarizon/web3

TRACK BReact · Next.js · Vite React (requires React 18+)

Installs the core SDK and the React hooks package together. One command, everything you need.

SDK + REACT HOOKS

$npm install @awarizon/web3 @awarizon/react

TRACK CExpo · React Native (Expo SDK 49+ or bare RN 0.74+)

Adds secure wallet key storage (iOS Keychain / Android Keystore) and mobile-optimised wallet hooks.

MOBILE

$npm install @awarizon/react-native expo-secure-store

STEP 3

Store your key as an environment variable

Create a .env file in your project root and add your key. Your framework loads it automatically.

.env · Node.js, Vite, scripts

# Loaded via process.env — never sent to the browser
AWARIZON_API_KEY=awz_live_...

.env.local · Next.js

# NEXT_PUBLIC_ exposes the value to browser bundles.
NEXT_PUBLIC_AWARIZON_API_KEY=awz_live_...

💡

Create a .env.example file with placeholder values and commit that instead. Other developers will know which variables are required without seeing the real key.

STEP 4A

Initialize — Node.js / Scripts / Backend

Create the SDK instance once in a shared file and export it. Every other file imports from there — the connection pool is reused automatically.

lib/awarizon.ts

import { AwarizonWeb3 } from "@awarizon/web3"

export const awarizon = new AwarizonWeb3({
  chain:  "base",                          // the EVM chain to connect to
  apiKey: process.env.AWARIZON_API_KEY!,   // loaded from .env
})

💡

Not sure which chain to pick? Start with "base-sepolia" — it is a free test network where transactions cost no real money. Switch to "base" when you are ready for production.

"base"BaseRecommended for new projects

"base-sepolia"Base TestnetFree — no real funds

"ethereum"EthereumMainnet

"sepolia"SepoliaEthereum testnet

"polygon"PolygonPoS mainnet

"arbitrum"Arbitrum OneL2

"optimism"OptimismL2

"bnb"BNB ChainBSC

"avalanche"AvalancheC-Chain

STEP 4B

Initialize — React / Next.js

React uses a Provider pattern. You create the SDK instance once and wrap your app with AwarizonProvider — every hook in every component automatically gets access to it.

1 of 3 — Create the SDK instance

lib/awarizon.ts

import { AwarizonWeb3 } from "@awarizon/web3"

// Create OUTSIDE of any component — never recreated on re-renders
export const awarizon = new AwarizonWeb3({
  chain:  "base",
  apiKey: process.env.NEXT_PUBLIC_AWARIZON_API_KEY!,
})

2 of 3 — Create a Providers wrapper (Next.js App Router needs "use client")

components/Providers.tsx

"use client"
import { AwarizonProvider } from "@awarizon/react"
import { awarizon } from "@/lib/awarizon"

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <AwarizonProvider awarizon={awarizon}>
      {children}
    </AwarizonProvider>
  )
}

3 of 3 — Add the Provider to your root layout

app/layout.tsx

import { Providers } from "@/components/Providers"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  )
}

STEP 5

Make your first call

Reading blockchain data requires no wallet and no gas. You can query any contract on any chain right now, instantly.

Node.js / Script

scripts/check-balance.ts

import { awarizon } from "./lib/awarizon"

// USDC on Base mainnet — no ABI file needed
const usdc = await awarizon.erc20("0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913")

const symbol   = await usdc.symbol()   // "USDC"
const decimals = await usdc.decimals() // 6
const raw       = await usdc.balanceOf("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045")
const formatted = Number(raw) / 10 ** decimals

console.log(`Balance: ${formatted} ${symbol}`)  // "Balance: 1234.56 USDC"

React component

components/USDCBalance.tsx

import { useToken } from "@awarizon/react"
import { useState, useEffect } from "react"

const USDC_BASE = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"

export function USDCBalance({ wallet }: { wallet: `0x${string}` }) {
  const { symbol, decimals, balanceOf, isLoading } = useToken(USDC_BASE)
  const [balance, setBalance] = useState<string>("…")

  useEffect(() => {
    if (decimals === null) return
    balanceOf(wallet).then(raw => setBalance((Number(raw) / 10 ** decimals).toFixed(2)))
  }, [wallet, balanceOf, decimals])

  if (isLoading) return <p>Loading token…</p>
  return <p>Balance: {balance} {symbol}</p>
}

💡

Token amounts are always raw integers on-chain. 1 USDC is 1_000_000n because USDC has 6 decimals. Always divide by 10 ** decimals before displaying to users.

ℹ️

To send transactions (transfers, minting, staking) you also need a wallet connected. See the Writing transactions section below for the full write flow.

←

create-awarizon-app

Quick Start

→