Quickstart

import { Connection, Keypair, PublicKey } from "@solana/web3.js";
import { ShugoClient, UNKNOWN_INIT_ID } from "@shugo-protocol/sdk";

const connection = new Connection("[https://api.devnet.solana.com](https://api.devnet.solana.com)", "confirmed");
const treasuryOwner = Keypair.fromSecretKey(/* ... */);
const agentPublicKey = new PublicKey("Agnt..."); // Ephemeral Agent Signer
const mint = new PublicKey("4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU"); // Devnet USDC

const shugo = new ShugoClient(connection, treasuryOwner);

// Create the delegation policy: Max 100 USDC per 216,000 slots (~24 hours)
const { txSignature, subscriptionAuthorityPda } = await shugo.createAllowance({
  mint,
  owner: treasuryOwner.publicKey,
  agentDelegate: agentPublicKey,
  velocityCapAmount: 100_000_000n, // 100 USDC (6 decimals)
  windowSlots: 216_000n,           // ~24 hours on Solana mainnet
  initId: UNKNOWN_INIT_ID,         // Sentinel for atomic same-slot initialization
});

console.log(`Shugo Authority configured at: ${subscriptionAuthorityPda.toBase58()}`);
console.log(`Transaction confirmed: ${txSignature}`);

import { Connection, Keypair, PublicKey } from "@solana/web3.js";
import { ShugoAgentSession } from "@shugo-protocol/sdk";

const connection = new Connection("[https://api.devnet.solana.com](https://api.devnet.solana.com)", "confirmed");
const agentKeypair = Keypair.fromSecretKey(/* agent operational key */);
const treasuryOwnerPubkey = new PublicKey("Trz...");
const recipientPubkey = new PublicKey("Vend...");
const mint = new PublicKey("4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU");

const session = new ShugoAgentSession(connection, agentKeypair);

// Move 15 USDC for an API query
const tx = await session.executeGuardedTransfer({
  treasuryOwner: treasuryOwnerPubkey,
  mint,
  recipient: recipientPubkey,
  amount: 15_000_000n,
});

console.log(`Transfer executed by agent: ${tx}`);

try {
  await session.executeGuardedTransfer({
    treasuryOwner: treasuryOwnerPubkey,
    mint,
    recipient: recipientPubkey,
    amount: 200_000_000n, // Exceeds the 100 USDC velocity cap
  });
} catch (err: any) {
  // Expected Error: SubscriptionsError::VelocityCapExceeded (0x1774)
  console.error("Guarded by Shugo:", err.message);
}