JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 223
  • Score
    100M100P100Q99681F
  • License MIT

Official TypeScript SDK for the Sardis stablecoin execution layer - Enable AI agents to execute programmable payments using stablecoins

Package Exports

  • @sardis/sdk
  • @sardis/sdk/browser
  • @sardis/sdk/integrations/index
  • @sardis/sdk/integrations/langchain
  • @sardis/sdk/integrations/openai
  • @sardis/sdk/integrations/vercel-ai
  • @sardis/sdk/package.json

Readme

Sardis TypeScript SDK

npm version npm downloads License: MIT TypeScript

The official TypeScript SDK for the Sardis stablecoin execution layer. Enables AI agents to execute programmable payments using stablecoins across multiple chains.

Table of Contents

Installation

npm install @sardis/sdk
# or
yarn add @sardis/sdk
# or
pnpm add @sardis/sdk

Quick Start

import { SardisClient } from '@sardis/sdk';

const client = new SardisClient({
  apiKey: 'your-api-key',
});

// Check API health
const health = await client.health();
console.log(`API Status: ${health.status}`);

// Execute a payment mandate
const result = await client.payments.executeMandate({
  mandate_id: 'mandate_123',
  subject: 'wallet_abc',
  destination: '0x...',
  amount_minor: 10000000, // $10.00 USDC (6 decimals)
  token: 'USDC',
  chain: 'base',
});
console.log(`Payment executed: ${result.tx_hash}`);

Features

Payments

Execute single mandates or full AP2 payment bundles:

// Execute AP2 bundle (Intent → Cart → Payment)
const result = await client.payments.executeAP2(
  intentMandate,
  cartMandate,
  paymentMandate
);

Holds (Pre-Authorization)

Create, capture, and void pre-authorization holds:

// Create a hold
const hold = await client.holds.create({
  wallet_id: 'wallet_123',
  amount: '100.00',
  token: 'USDC',
  merchant_id: 'merchant_456',
  duration_hours: 24,
});

// Capture the hold (complete payment)
const captured = await client.holds.capture(hold.hold_id, '95.00');

// Or void the hold (cancel)
await client.holds.void(hold.hold_id);

Webhooks

Manage webhook subscriptions for real-time events:

// Create a webhook subscription
const webhook = await client.webhooks.create({
  url: 'https://your-server.com/webhooks',
  events: ['payment.completed', 'hold.captured'],
});

// List deliveries
const deliveries = await client.webhooks.listDeliveries(webhook.id);

Marketplace (A2A)

Discover and interact with agent-to-agent services:

// List available services
const services = await client.marketplace.listServices({
  category: 'ai',
});

// Create an offer
const offer = await client.marketplace.createOffer({
  service_id: 'service_123',
  consumer_agent_id: 'agent_456',
  total_amount: '50.00',
});

// Accept an offer (as provider)
await client.marketplace.acceptOffer(offer.id);

Transactions

Get gas estimates and transaction status:

// Estimate gas
const estimate = await client.transactions.estimateGas({
  chain: 'base',
  to_address: '0x...',
  amount: '100.00',
  token: 'USDC',
});
console.log(`Estimated cost: ${estimate.estimated_cost_wei} wei`);

// Check transaction status
const status = await client.transactions.getStatus('0x...', 'base');

Ledger

Query the append-only ledger:

// List ledger entries
const entries = await client.ledger.listEntries({ wallet_id: 'wallet_123' });

// Verify an entry
const verification = await client.ledger.verifyEntry('tx_123');

Error Handling

The SDK provides typed exceptions for common error cases:

import {
  SardisError,
  APIError,
  AuthenticationError,
  RateLimitError,
  InsufficientBalanceError,
} from '@sardis/sdk';

try {
  const result = await client.payments.executeMandate(mandate);
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited, retry after ${error.retryAfter} seconds`);
  } else if (error instanceof InsufficientBalanceError) {
    console.error(`Need ${error.required} ${error.currency}, have ${error.available}`);
  } else if (error instanceof APIError) {
    console.error(`API error [${error.code}]: ${error.message}`);
  }
}

Configuration

const client = new SardisClient({
  baseUrl: 'https://api.sardis.sh', // API base URL (optional)
  apiKey: 'sk_live_...',                  // Your API key (required)
  timeout: 30000,                         // Request timeout in ms (optional)
  maxRetries: 3,                          // Max retry attempts (optional)
});

Agents

Create and manage AI agents with spending policies:

// Create an agent
const agent = await client.agents.create({
  name: 'Invoice Processing Agent',
  description: 'Processes invoices and pays vendors',
  spending_limits: {
    per_transaction: '500.00',
    daily: '5000.00',
    monthly: '50000.00',
  },
  policy: {
    blocked_categories: ['gambling', 'adult'],
    approval_threshold: '1000.00',
  },
});

// Update spending limits
await client.agents.update(agent.id, {
  spending_limits: { daily: '10000.00' },
});

// List agents
const agents = await client.agents.list({ is_active: true, limit: 50 });

Wallets

Manage non-custodial MPC wallets:

// Create a wallet for an agent
const wallet = await client.wallets.create({
  agent_id: agent.id,
  mpc_provider: 'turnkey', // or 'fireblocks'
  limit_per_tx: '500.00',
  limit_total: '10000.00',
});

// Get wallet balance (read from chain)
const balance = await client.wallets.getBalance(wallet.id, 'base', 'USDC');
console.log(`Balance: ${balance.balance} USDC`);

// Set chain address
await client.wallets.setAddress(wallet.id, 'base', '0x...');

Policies (Natural Language → Deterministic Enforcement)

LLMs help write policies, but Sardis uses deterministic code to enforce them.

// Preview what the system understood (human-in-the-loop)
const preview = await client.policies.preview(
  "Max $100 per transaction, block gambling",
  "agent_demo_001"
);
console.log(preview.parsed);

// Apply policy to agent
const applied = await client.policies.apply(
  "Max $100 per transaction, block gambling",
  "agent_demo_001"
);
console.log(applied.policy_id);

Cards (Virtual Cards + Simulated Purchase Demo)

// Issue a virtual card (Lithic-backed)
const card = await client.cards.issue({
  wallet_id: wallet.id,
  limit_per_tx: "100.00",
});

// Simulate a purchase (e.g. gambling MCC -> policy deny + optional auto-freeze)
const result = await client.cards.simulatePurchase(card.card_id, {
  amount: "25.00",
  currency: "USD",
  merchant_name: "Demo Casino",
  mcc_code: "7995",
});
console.log(result.policy, result.transaction);

// Show card transactions
const txs = await client.cards.transactions(card.card_id, 20);
console.log(txs.length);

Stablecoin Transfers (Agent is Sender)

This is intended to be called by an agent process using an API key:

const tx = await client.wallets.transfer(wallet.id, {
  destination: "0x000000000000000000000000000000000000dEaD",
  amount: "1.00",
  token: "USDC",
  chain: "base_sepolia",
  domain: "localhost",
  memo: "demo stablecoin transfer",
});
console.log(tx.tx_hash);

Supported Chains

Chain Mainnet Testnet
Base base base_sepolia
Polygon polygon polygon_amoy
Ethereum ethereum ethereum_sepolia
Arbitrum arbitrum arbitrum_sepolia
Optimism optimism optimism_sepolia

Note: Solana support is planned but not yet implemented.

Supported Tokens

  • USDC - USD Coin (Circle)
  • USDT - Tether USD
  • PYUSD - PayPal USD
  • EURC - Euro Coin (Circle)

TypeScript Support

This SDK is written in TypeScript and provides full type definitions for all API responses.

import type {
  Chain,
  Token,
  MPCProvider,
  Payment,
  Hold,
  Webhook,
  Service,
  GasEstimate,
  Agent,
  Wallet,
  WalletBalance,
} from '@sardis/sdk';

// Type-safe chain selection
const chain: Chain = 'base';
const token: Token = 'USDC';

Framework Integrations

LangChain.js

import { SardisToolkit } from '@sardis/sdk/integrations/langchain';

const toolkit = new SardisToolkit({ client });
const tools = toolkit.getTools();

// Use with LangChain agent
const agent = createOpenAIFunctionsAgent({ llm, tools, prompt });

Vercel AI SDK

import { sardisTools } from '@sardis/sdk/integrations/vercel-ai';

const tools = sardisTools(client);

// Use with Vercel AI
const { text } = await generateText({
  model: openai('gpt-4'),
  tools,
  messages,
});

OpenAI Function Calling

import { sardisFunctions, handleSardisCall } from '@sardis/sdk/integrations/openai';

// Get function definitions
const functions = sardisFunctions(client);

// Handle function calls
const result = await handleSardisCall(client, functionName, args);

Browser Usage

The SDK includes a browser-optimized bundle:

<!-- Via CDN -->
<script src="https://unpkg.com/@sardis/sdk@latest/dist/browser/sardis.umd.min.js"></script>
<script>
  const client = new Sardis.SardisClient({
    apiKey: 'your-api-key',
  });
</script>

Or import the browser bundle directly:

import { SardisClient } from '@sardis/sdk/browser';

Requirements

  • Node.js 18.0.0 or higher
  • TypeScript 4.7+ (optional, for type definitions)

Contributing

We welcome contributions! Please see our Contributing Guide for details.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Support

License

MIT - see LICENSE for details.