npm package: @sardis/sdk
Description: Official TypeScript SDK for the Sardis stablecoin execution layer - Enable AI agents to execute programmable payments using stablecoins
Author: Sardis
Latest version: 1.1.0

# Sardis TypeScript SDK

[![npm version](https://img.shields.io/npm/v/@sardis/sdk.svg)](https://www.npmjs.com/package/@sardis/sdk)
[![npm downloads](https://img.shields.io/npm/dm/@sardis/sdk.svg)](https://www.npmjs.com/package/@sardis/sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)

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](#installation)
- [Quick Start](#quick-start)
- [Features](#features)
- [Error Handling](#error-handling)
- [Configuration](#configuration)
- [Agents](#agents)
- [Wallets](#wallets)
- [Supported Chains](#supported-chains)
- [Supported Tokens](#supported-tokens)
- [TypeScript Support](#typescript-support)
- [Framework Integrations](#framework-integrations)
- [Browser Usage](#browser-usage)
- [Contributing](#contributing)
- [License](#license)

## Installation

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

## Quick Start

```typescript
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:

```typescript
// 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:

```typescript
// 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:

```typescript
// 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:

```typescript
// 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:

```typescript
// 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:

```typescript
// 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:

```typescript
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

```typescript
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:

```typescript
// 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:

```typescript
// Create a wallet for an agent
const wallet = await client.wallets.create({
  agent_id: agent.id,
  mpc_provider: 'turnkey',
  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.

```typescript
// 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)

```typescript
// Issue a virtual card (Stripe Issuing)
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:

```typescript
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 |
|-------|---------|---------|
| Arc (Circle L1) | `arc` | `arc_testnet` |
| Base | `base` | `base_sepolia` |
| Polygon | `polygon` | `polygon_amoy` |
| Ethereum | `ethereum` | `ethereum_sepolia` |
| Arbitrum | `arbitrum` | `arbitrum_sepolia` |
| Optimism | `optimism` | `optimism_sepolia` |

## 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.

```typescript
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

```typescript
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

```typescript
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

```typescript
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:

```html
<!-- 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:

```typescript
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](https://github.com/sardis-network/sardis-sdk-js/blob/main/CONTRIBUTING.md) 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

- [Documentation](https://docs.sardis.sh)
- [GitHub Issues](https://github.com/sardis-network/sardis-sdk-js/issues)
- [Discord Community](https://discord.gg/XMA9JwDJ)

## License

MIT - see [LICENSE](./LICENSE) for details.