@bbuilders/djeon402-sdk-client

Browser SDK for DJEON402 token with React hooks and Vue composables support.

What's New in 2.0

Breaking changes:

• rpcUrl is required for any chain other than Base (8453) — the constructor now throws instead of silently creating a broken client
• kyc.getRemainingLimit returns { remaining, remainingRaw, userAddress } (was { address, remainingLimit })
• kyc.checkDailyLimit now returns the real allow/deny boolean (simulates first, records on-chain only when allowed; caller must be KYC admin or approved provider)
• Token decimals are 6 (USDC/x402 convention)

New:

• signTransferWithWallet / signReceiveWithWallet accept valueRaw (base units) in addition to human-readable amount
• fetchWithPayment is x402 v2 conformant: base-unit amounts, on-chain EIP-712 domain, PAYMENT-SIGNATURE payload shape

Features

• ✅ React Hooks - Ready-to-use hooks with wagmi integration
• ✅ Vue Composables - Vue 3 Composition API support
• ✅ TypeScript - Full type safety
• ✅ Wallet Integration - MetaMask, WalletConnect, etc.
• ✅ No Private Keys - Secure wallet-based signing
• ✅ x402 Gasless - Sign gasless transfer authorizations
• ✅ x402 v2 HTTP - fetchWithPayment auto-handles 402 Payment Required

Units

The token uses 6 decimals (USDC/x402 convention, $1 = 1_000_000 base units). Human-readable amount params ("5" = 5 tokens) are converted internally; x402 v2 requirement amounts are base units and are handled automatically by fetchWithPayment.

Installation

# npm
npm install @bbuilders/djeon402-sdk-client viem wagmi

# pnpm
pnpm add @bbuilders/djeon402-sdk-client viem wagmi

# yarn
yarn add @bbuilders/djeon402-sdk-client viem wagmi

Quick Start

React + wagmi

1. Setup Provider

import { Djeon402Provider } from '@bbuilders/djeon402-sdk-client/react';
import { WagmiProvider, createConfig, http } from 'wagmi';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

// Configuration constants
const DJEON402_CONTRACT = '0x...';
const KYC_REGISTRY = '0x....';
const CHAIN_ID = 31337;

const config = createConfig({
  chains: [/* your chains */],
  transports: {
    /* your transports */
  },
});

const queryClient = new QueryClient();

function App() {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <Djeon402Provider
          config={{
            contractAddress: DJEON402_CONTRACT,
            kycRegistryAddress: KYC_REGISTRY,
            chainId: CHAIN_ID,
          }}
        >
          <YourApp />
        </Djeon402Provider>
      </QueryClientProvider>
    </WagmiProvider>
  );
}

2. Use Hooks

import { useAccount } from 'wagmi';
import { useBalance, useTransfer } from '@bbuilders/djeon402-sdk-client/react';

// Test account addresses
const RECIPIENT_ADDRESS = '0x...';

// Transfer amount constant
const TRANSFER_AMOUNT = '100';

function TokenDashboard() {
  const { address } = useAccount();
  const { data: balance, isLoading } = useBalance(address);
  const { transfer, isLoading: isTransferring } = useTransfer();

  const handleTransfer = async () => {
    await transfer({
      to: RECIPIENT_ADDRESS,
      amount: TRANSFER_AMOUNT,
    });
  };

  return (
    <div>
      <p>Balance: {balance?.balance}</p>
      <button onClick={handleTransfer} disabled={isTransferring}>
        Send {TRANSFER_AMOUNT} Tokens
      </button>
    </div>
  );
}

Vue 3

1. Setup Provider

<script setup lang="ts">
import { provideDjeon402 } from '@bbuilders/djeon402-sdk-client/vue';

// Configuration constants
const DJEON402_CONTRACT = '0x....';
const KYC_REGISTRY = '0x....';
const RPC_URL = 'http://localhost:8545';
const CHAIN_ID = 31337;

provideDjeon402({
  contractAddress: DJEON402_CONTRACT,
  kycRegistryAddress: KYC_REGISTRY,
  chainId: CHAIN_ID,
  rpcUrl: RPC_URL,
});
</script>

<template>
  <YourApp />
</template>

2. Use Composables

<script setup lang="ts">
import { ref, computed } from 'vue';
import { useBalance, useTransfer } from '@bbuilders/djeon402-sdk-client/vue';
import { useWalletClient } from '@wagmi/vue';

// Test account addresses
const RECIPIENT_ADDRESS = '0x.....';

// Transfer amount constant
const TRANSFER_AMOUNT = '100';

const { data: walletClient } = useWalletClient();
const address = computed(() => walletClient.value?.account?.address);

const { data: balance, isLoading } = useBalance(address);
const { transfer, isLoading: isTransferring } = useTransfer(walletClient);

const handleTransfer = async () => {
  await transfer(RECIPIENT_ADDRESS, TRANSFER_AMOUNT);
};
</script>

<template>
  <div>
    <p>Balance: {{ balance?.balance }}</p>
    <button @click="handleTransfer" :disabled="isTransferring">
      Send {{ TRANSFER_AMOUNT }} Tokens
    </button>
  </div>
</template>

Vanilla JavaScript

import { Djeon402ClientSDK } from '@bbuilders/djeon402-sdk-client';
import { createWalletClient, custom } from 'viem';

// Configuration constants
const DJEON402_CONTRACT = '0x....';
const RECIPIENT_ADDRESS = '0x....';
const RPC_URL = 'http://localhost:8545';
const CHAIN_ID = 31337;
const TRANSFER_AMOUNT = '100';

// Create SDK instance
const sdk = new Djeon402ClientSDK({
  contractAddress: DJEON402_CONTRACT,
  chainId: CHAIN_ID,
  rpcUrl: RPC_URL,
});

// Get token info
const info = await sdk.token.getInfo();
console.log(info);

// Create wallet client from browser wallet (MetaMask)
const walletClient = createWalletClient({
  chain: sdk.getChain(),
  transport: custom(window.ethereum),
});

// Transfer tokens
const result = await sdk.token.transfer({
  walletClient,
  to: RECIPIENT_ADDRESS,
  amount: TRANSFER_AMOUNT,
});

API Reference

React Hooks

All hooks require Djeon402Provider to be set up in your app.

• useTokenInfo() - Get token information
• useBalance(address) - Get balance of an address
• useTransfer() - Transfer tokens
• useApprove() - Approve spending
• useX402Transfer() - Sign gasless transfer authorization
• useX402Receive() - Sign gasless receive authorization
• useKYCData(address) - Get KYC data
• useIsBlacklisted(address) - Check blacklist status

Vue Composables

Same API as React hooks, compatible with Vue 3 reactivity.

• useTokenInfo(), useBalance(), useTransfer(), useApprove()
• useX402Transfer(walletClient) - Sign gasless transfer
• useX402Receive(walletClient) - Sign gasless receive
• useKYCData(), useIsBlacklisted()

SDK Config

new Djeon402ClientSDK({
  contractAddress: '0x...',
  chainId: 31337,
  rpcUrl: 'http://localhost:8545', // REQUIRED for any chain other than Base (8453)
  kycRegistryAddress: '0x...',     // optional; required for sdk.kyc
});

Core SDK Modules

• sdk.token - ERC-20 operations
• sdk.admin - Admin functions
• sdk.kyc - KYC management
  • getData(address) / isKYCValid(address) / getLevelLimit(level) - reads
  • getRemainingLimit(address) → { remaining, remainingRaw, userAddress }
  • verify / updateKYC / revokeKYC / setDailyLimit / setLevelLimit - admin writes
  • checkDailyLimit({ walletClient, userAddress, amountUSD }) - state-mutating: simulates first and returns the real allow/deny boolean; records the spend on-chain only when allowed. Caller must be the KYC admin or an approved provider.
• sdk.x402 - Gasless transfers (sign, execute, receive, cancel, fetchWithPayment)
  • signTransferWithWallet / signReceiveWithWallet accept either a human-readable amount ("5") or valueRaw (bigint base units, takes precedence). The EIP-712 domain (name, chainId) is read live from the contract — never hardcoded.

Examples

Gasless Payment (x402)

import { useX402Transfer } from '@bbuilders/djeon402-sdk-client/react';

// Merchant configuration
const MERCHANT_ADDRESS = '0xMerchantAddress...';
const PAYMENT_AMOUNT = '99.99';

function CheckoutButton() {
  const { signTransfer } = useX402Transfer();

  const handlePayment = async () => {
    // User signs authorization (no gas needed!)
    const authorization = await signTransfer({
      to: MERCHANT_ADDRESS,
      amount: PAYMENT_AMOUNT,
    });

    // Send to backend for execution
    await fetch('/api/relay-payment', {
      method: 'POST',
      body: JSON.stringify({ authorization }),
    });
  };

  return <button onClick={handlePayment}>Pay ${PAYMENT_AMOUNT}</button>;
}

Receive Authorization (Payee-Initiated)

import { useX402Receive } from '@bbuilders/djeon402-sdk-client/react';

function ReceiveButton() {
  const { signReceive } = useX402Receive();

  const handleReceive = async () => {
    // Receiver signs to pull funds from sender
    const authorization = await signReceive({
      from: '0xSender...',
      amount: '50',
    });

    // Send to backend for execution
    await fetch('/api/relay/execute-receive', {
      method: 'POST',
      body: JSON.stringify({ authorization }),
    });
  };

  return <button onClick={handleReceive}>Receive 50 Tokens</button>;
}

Auto-Handle 402 Payment Required (x402 v2)

import { Djeon402ClientSDK } from '@bbuilders/djeon402-sdk-client';

const sdk = new Djeon402ClientSDK({
  contractAddress: '0x...',
  chainId: 31337,
  rpcUrl: 'http://localhost:8545',
});

// Implements the x402 v2 client flow in one call:
// 1. Detects 402 + PAYMENT-REQUIRED header (base64 PaymentRequired JSON)
// 2. Signs an EIP-3009 authorization for accepts[0] — the base-unit
//    `amount` and the on-chain EIP-712 domain are handled automatically
// 3. Retries with the PAYMENT-SIGNATURE header
//    ({ x402Version, resource, accepted, payload: { signature, authorization } })
// On success the response carries a PAYMENT-RESPONSE header with the
// settlement result (transaction hash, success flag).
const response = await sdk.x402.fetchWithPayment(walletClient, '/api/content/article-1');

Check KYC Before Transfer

import { useAccount } from 'wagmi';
import { useKYCData, useTransfer } from '@bbuilders/djeon402-sdk-client/react';

// Transfer configuration
const RECIPIENT_ADDRESS = '0xRecipientAddress...';
const TRANSFER_AMOUNT = '1000';

function SecureTransfer() {
  const { address } = useAccount();
  const { data: kyc } = useKYCData(address);
  const { transfer } = useTransfer();

  const handleTransfer = async () => {
    if (!kyc?.isActive || kyc.level === 0) {
      alert('Please complete KYC verification first');
      return;
    }

    await transfer({
      to: RECIPIENT_ADDRESS,
      amount: TRANSFER_AMOUNT
    });
  };

  return (
    <div>
      <p>KYC Status: {kyc?.levelName}</p>
      <button onClick={handleTransfer}>Transfer</button>
    </div>
  );
}

Requirements

• React >= 18.0.0 (for React hooks)
• Vue >= 3.0.0 (for Vue composables)
• wagmi ^2.0.0
• viem ^2.0.0
• @tanstack/react-query ^5.0.0 (for React)

Related Packages

• @bbuilders/djeon402-contracts - Smart Contracts (Solidity / Foundry)
• @bbuilders/djeon402-core - Core types and utilities
• @bbuilders/djeon402-sdk-node - Node.js/Backend SDK

License

MIT