Agent SDK

The SinaiAgent class wraps AksumKit in an interface designed for autonomous agents. Every method returns a structured JSON response and never throws exceptions, making it safe for unsupervised operation.

Installation

npm install @sinai-standard/agent-sdk

Quick Start

import { SinaiAgent } from "@sinai-standard/agent-sdk";
 
const agent = await SinaiAgent.connect({
  network: "devnet",
  privateKey: process.env.SINAI_PRIVATE_KEY,
});
 
// Create a compliant token
const result = await agent.createToken({
  name: "RegFund",
  symbol: "RGF",
  decimals: 6,
  initialSupply: 1_000_000,
});
 
if (result.success) {
  console.log("Mint address:", result.data.mint);
} else {
  console.log("Failed:", result.error);
}

`SinaiAgent.connect()`

Factory method that creates a connected agent instance.

const agent = await SinaiAgent.connect({
  network: "devnet" | "mainnet-beta",
  privateKey: string,       // Base58-encoded private key
  rpcUrl?: string,          // Custom RPC endpoint
});

Returns { success: true, data: SinaiAgent } or { success: false, error: string }.

Response Format

Every method returns an AgentResult object:

// On success
{
  success: true,
  data: { /* method-specific data */ }
}
 
// On failure
{
  success: false,
  error: "Human-readable error message"
}

This means agents can use simple if (result.success) checks instead of try/catch blocks. No method ever throws an exception.

Methods

Token Operations

`createToken(params)`

const result = await agent.createToken({
  name: string,
  symbol: string,
  decimals: number,
  initialSupply: number,
  hooks?: {
    allowlist?: boolean,    // default: true
    tax?: { basisPoints: number, maxFee: number },
    holdPeriod?: { seconds: number },
    maxBalance?: { amount: number },
  },
});
// result.data: { mint: string, signature: string }

`mintTokens(params)`

const result = await agent.mintTokens({
  mint: string,
  destination: string,
  amount: number,
});
// result.data: { signature: string, newBalance: number }

`transferTokens(params)`

const result = await agent.transferTokens({
  mint: string,
  from: string,
  to: string,
  amount: number,
});
// result.data: { signature: string }

`burnTokens(params)`

const result = await agent.burnTokens({
  mint: string,
  source: string,
  amount: number,
});
// result.data: { signature: string, remainingBalance: number }

`getTokenInfo(mint)`

const result = await agent.getTokenInfo(mint);
// result.data: {
//   name: string, symbol: string, decimals: number,
//   supply: number, hooks: string[], authority: string
// }

Allowlist Management

`addToAllowlist(params)`

const result = await agent.addToAllowlist({
  mint: string,
  wallet: string,
});
// result.data: { signature: string }

`removeFromAllowlist(params)`

const result = await agent.removeFromAllowlist({
  mint: string,
  wallet: string,
});
// result.data: { signature: string }

`checkAllowlist(params)`

const result = await agent.checkAllowlist({
  mint: string,
  wallet: string,
});
// result.data: { allowed: boolean }

Compliance

`getComplianceStatus(params)`

const result = await agent.getComplianceStatus({
  mint: string,
  wallet: string,
});
// result.data: {
//   allowed: boolean,
//   holdPeriodMet: boolean,
//   balanceBelowMax: boolean,
//   canReceiveTransfer: boolean,
//   details: string
// }

Error Handling

SinaiAgent catches all exceptions internally and returns them as structured errors. This is critical for autonomous agents that cannot recover from unhandled throws.

// Traditional SDK — can throw
try {
  const tx = await aksumKit.mintTokens(mint, dest, amount);
} catch (e) {
  // Agent must handle every possible error type
}
 
// Agent SDK — never throws
const result = await agent.mintTokens({ mint, destination, amount });
if (!result.success) {
  // result.error is always a string
  console.log(result.error);
  // "Wallet not on allowlist for mint 7xKp...3mNq"
}

Common error messages:

Error	Cause
`"Wallet not on allowlist"`	Recipient is not KYC-approved
`"Hold period not met"`	Recipient's hold period has not elapsed
`"Balance would exceed maximum"`	Transfer would exceed the `maxBalance` cap
`"Insufficient balance"`	Source wallet lacks sufficient tokens
`"Invalid mint address"`	The provided mint address is not valid
`"Not authorized"`	The agent's wallet is not the token authority

Full Flow Example

import { SinaiAgent } from "@sinai-standard/agent-sdk";
 
async function issueComplianceToken() {
  // 1. Connect
  const agent = await SinaiAgent.connect({
    network: "devnet",
    privateKey: process.env.SINAI_PRIVATE_KEY,
  });
  if (!agent.success) return console.error(agent.error);
 
  const sinai = agent.data;
 
  // 2. Create token with compliance hooks
  const token = await sinai.createToken({
    name: "Treasury Bond",
    symbol: "TBOND",
    decimals: 6,
    initialSupply: 10_000_000,
    hooks: {
      allowlist: true,
      tax: { basisPoints: 50, maxFee: 1000 },
      holdPeriod: { seconds: 86400 },
      maxBalance: { amount: 1_000_000 },
    },
  });
  if (!token.success) return console.error(token.error);
 
  const mint = token.data.mint;
  console.log("Token created:", mint);
 
  // 3. Add investor to allowlist
  const investor = "9aB4...xY2z";
  const allow = await sinai.addToAllowlist({ mint, wallet: investor });
  if (!allow.success) return console.error(allow.error);
 
  // 4. Check compliance before minting
  const status = await sinai.getComplianceStatus({ mint, wallet: investor });
  if (!status.success) return console.error(status.error);
 
  if (!status.data.canReceiveTransfer) {
    return console.error("Investor cannot receive:", status.data.details);
  }
 
  // 5. Mint tokens to investor
  const mint_tx = await sinai.mintTokens({
    mint,
    destination: investor,
    amount: 500_000,
  });
  if (!mint_tx.success) return console.error(mint_tx.error);
 
  console.log("Minted 500,000 TBOND to investor:", mint_tx.data.signature);
}

Comparison with Raw AksumKit

Feature	`SinaiAgent`	`AksumKit`
Error handling	Never throws, returns `{ success, error }`	Throws exceptions
Response format	JSON-friendly objects	Solana transaction objects
Setup	`SinaiAgent.connect()`	Manual `Connection` + `Keypair` setup
Compliance checks	Built-in `getComplianceStatus`	Manual multi-step queries
Best for	Autonomous agents, LLM tool calls	Human developers, complex flows

Agent SDK

On this page