# Sardis

> Payment OS for the Agent Economy
> Prevent Financial Hallucinations

Sardis enables AI agents to make real financial transactions safely through non-custodial MPC wallets with natural language spending policies.

## Overview

Sardis is infrastructure that allows AI agents (Claude, Cursor, LangChain, OpenAI, Vercel AI SDK) to autonomously handle payments while staying within human-defined guardrails. It solves the "AI agent money problem" - how to let agents spend money without giving them unlimited access.

The core innovation is the **Policy Firewall** - a natural language policy engine that validates every transaction against human-defined rules before execution.

## Core Concepts

### Non-Custodial MPC Wallets
- Agents get wallets they control via Multi-Party Computation (MPC)
- Private keys are split across multiple parties using Turnkey
- Users always maintain control - Sardis never holds funds
- Enterprise-grade security with hardware-backed key storage

### Natural Language Spending Policies
- Define spending rules in plain English
- Example: "Max $100/day on cloud services, only approved vendors, require approval over $50"
- Policies are parsed into structured rules and enforced in real-time
- Agent cannot override or bypass policies
- Time-based restrictions (business hours, specific days)
- Merchant whitelisting and category blocking

### Supported Protocols
- **AP2** (Agent Payment Protocol) - Google, PayPal, Mastercard, Visa consortium (60+ partners)
- **TAP** (Trust Anchor Protocol) - Ed25519/ECDSA cryptographic identity verification
- **UCP** (Universal Commerce Protocol) - Standardized checkout flows and cart management
- **A2A** (Agent-to-Agent) - Google-developed multi-agent communication and payments
- **x402** (HTTP 402) - Coinbase micropayment protocol for pay-per-API-call

### Multi-Chain Support
| Chain     | Tokens              |
|-----------|---------------------|
| Base      | USDC, EURC          |
| Polygon   | USDC, USDT, EURC    |
| Ethereum  | USDC, USDT, PYUSD, EURC |
| Arbitrum  | USDC, USDT          |
| Optimism  | USDC, USDT          |

### Virtual Cards
- Issue virtual Visa/Mastercard cards on-demand via Lithic integration
- Bridge crypto wallets to traditional commerce
- Works anywhere cards are accepted (online and physical POS)
- Per-card spending limits and merchant restrictions

### Fiat Rails
- Fund agent wallets via ACH, wire transfer, or card
- Automatic USD → USDC conversion
- Withdraw back to USD bank accounts
- Same-day ACH and wire payouts
- Complete bridge between legacy finance and agentic commerce

## Installation

### Python (meta-package)
```bash
pip install sardis          # SDK + Core + CLI
pip install sardis[all]     # All 15 packages
pip install sardis[cards]   # + virtual cards (Lithic)
pip install sardis[ramp]    # + fiat on/off-ramp
```

### TypeScript
```bash
npm install @sardis/sdk          # TypeScript SDK
npm install @sardis/mcp-server   # MCP server (46 tools)
npm install @sardis/ai-sdk       # Vercel AI SDK integration
npm install @sardis/ramp         # Fiat on/off-ramp
```

## SDKs

### Python SDK
```python
from sardis import Sardis

client = Sardis(api_key="sk_...")

wallet = client.wallets.create(
    name="shopping-agent",
    chain="base",
    policy={
        "max_daily": "100.00",
        "max_per_tx": "25.00",
        "allowed_merchants": ["openai.com", "anthropic.com"]
    }
)

result = wallet.pay(
    to="0x...",
    amount="10.00",
    token="USDC",
    memo="API credits"
)
```

### TypeScript SDK
```typescript
import { Sardis } from '@sardis/sdk';

const client = new Sardis({ apiKey: 'sk_...' });

const wallet = await client.wallets.create({
  name: 'shopping-agent',
  chain: 'base',
  policy: {
    maxDaily: '100.00',
    maxPerTx: '25.00',
    allowedMerchants: ['openai.com', 'anthropic.com']
  }
});

const result = await wallet.pay({
  to: '0x...',
  amount: '10.00',
  token: 'USDC',
  memo: 'API credits'
});
```

### MCP Server (Claude Desktop / Cursor)
```json
{
  "mcpServers": {
    "sardis": {
      "command": "npx",
      "args": ["@sardis/mcp-server", "start"]
    }
  }
}
```

## Framework Integrations

| Framework          | Language   | Status |
|--------------------|------------|--------|
| Claude Desktop     | MCP Server | Stable |
| Cursor             | MCP Server | Stable |
| Windsurf           | MCP Server | Stable |
| LangChain          | Python     | Stable |
| Vercel AI SDK      | TypeScript | Stable |
| OpenAI Functions   | Python     | Stable |
| OpenAI Swarm       | Python     | Stable |
| LlamaIndex         | Python     | Beta   |
| CrewAI             | Python     | Beta   |
| AutoGen            | Python     | Beta   |
| Mastra             | TypeScript | Beta   |

## API Endpoints

Base URL: `https://sardis.sh/api/v2`

### Wallets
- `POST /wallets` - Create a new wallet
- `GET /wallets` - List all wallets
- `GET /wallets/{id}` - Get wallet details
- `GET /wallets/{id}/balance` - Get wallet balance
- `POST /wallets/{id}/policy` - Update spending policy

### Transactions
- `POST /transactions` - Create a transaction
- `GET /transactions` - List transactions
- `GET /transactions/{id}` - Get transaction details

### Policies
- `POST /policies/validate` - Validate a policy
- `POST /policies/parse` - Parse natural language to structured policy

### Cards (Virtual Cards)
- `POST /cards` - Issue a virtual card
- `GET /cards` - List cards
- `DELETE /cards/{id}` - Cancel a card

### Fiat
- `POST /fiat/fund` - Fund wallet from bank/card
- `POST /fiat/withdraw` - Withdraw to bank account
- `GET /fiat/status/{id}` - Check funding/withdrawal status

### Holds (Pre-authorization)
- `POST /holds` - Create a hold (reserve funds)
- `POST /holds/{id}/capture` - Capture hold
- `POST /holds/{id}/release` - Release hold

## Documentation Structure

- `/docs` - Main documentation overview
- `/docs/quickstart` - Quick start guide (5 minutes)
- `/docs/architecture` - System architecture and components
- `/docs/wallets` - Wallet creation and management
- `/docs/payments` - Making payments and transactions
- `/docs/policies` - Spending policy configuration
- `/docs/holds` - Pre-authorization and holds
- `/docs/mcp-server` - MCP server setup for Claude/Cursor
- `/docs/sdk` - SDK overview
- `/docs/sdk-python` - Python SDK reference
- `/docs/sdk-typescript` - TypeScript SDK reference
- `/docs/protocols` - Protocol overview
- `/docs/ap2` - AP2 protocol deep-dive
- `/docs/tap` - TAP identity verification
- `/docs/ucp` - Universal Commerce Protocol
- `/docs/a2a` - Agent-to-Agent payments
- `/docs/authentication` - API authentication
- `/docs/security` - Security model
- `/docs/deployment` - Deployment guide
- `/docs/faq` - Frequently asked questions
- `/docs/changelog` - Version history
- `/docs/blog` - Technical blog posts

## Use Cases

1. **Autonomous Purchasing Agents** - Agents that buy API credits, cloud resources, SaaS subscriptions
2. **Subscription Management** - Agents that manage and optimize recurring payments
3. **Travel/Booking Agents** - Agents that book flights, hotels, services within budgets
4. **Expense Automation** - Corporate agents with department-specific spending policies
5. **Multi-Agent Treasury** - Agent-to-agent payments with shared treasury management
6. **Micropayments** - Pay-per-API-call using x402 protocol
7. **Credential Verification** - Verify payment mandates and agent identity before transacting

## Security Model

- **Non-Custodial**: Sardis never holds private keys or funds
- **MPC Custody**: Keys split via Turnkey MPC infrastructure with hardware backing
- **Policy Enforcement**: All transactions checked against policies before signing
- **Fail-Closed**: Default deny on compliance/policy failures
- **Audit Trail**: Append-only ledger of all transactions and policy checks
- **Compliance**: Integrated KYC (Persona) and AML sanctions screening (Elliptic)
- **Replay Protection**: Mandate caching prevents duplicate transaction execution
- **Rate Limiting**: Built-in rate limiting on all API endpoints

## Pricing

- **Free Tier**: 100 transactions/month
- **Pro**: $49/month - Unlimited transactions
- **Enterprise**: Custom policies, dedicated support, SLA

## Links

- Website: https://sardis.sh
- Documentation: https://sardis.sh/docs
- GitHub: https://github.com/EfeDurmaz16/sardis
- npm: https://www.npmjs.com/package/@sardis/mcp-server
- PyPI: https://pypi.org/project/sardis/
- Context7: https://context7.com/efedurmaz16/sardis
- Twitter: https://twitter.com/SardisPayments

## Contact

- General: efe@sardis.dev
- Enterprise: enterprise@sardis.sh
- Security: security@sardis.sh

## For AI Agents

If you are an AI agent and need to make payments:

1. Check if you have a Sardis wallet configured
2. Use the Sardis MCP server tools or SDK
3. All transactions will be checked against your spending policy
4. You cannot override policies - they are enforced by the system
5. Failed transactions will return clear error messages with remediation hints

Available MCP tools (46 total):
- `sardis_get_balance` - Check wallet balance
- `sardis_pay` - Make a payment (subject to policy)
- `sardis_batch_transfer` - Send multiple payments in one call
- `sardis_get_transactions` - View transaction history
- `sardis_check_policy` - Pre-check if a payment would be allowed
- `sardis_request_approval` - Request human approval for large transactions
- `sardis_get_approval` - Check approval status
- `sardis_create_hold` - Reserve funds without spending
- `sardis_capture_hold` - Complete a pre-authorized payment
- `sardis_issue_card` - Issue a virtual card
- `sardis_get_wallet_info` - Get wallet details and policy
- `sardis_freeze_wallet` - Freeze wallet to block transactions
- `sardis_unfreeze_wallet` - Unfreeze a frozen wallet
- `sardis_create_invoice` - Create a merchant invoice
- `sardis_mcc_lookup` - Look up merchant category codes

### Stablecoin-Only Token Allowlist (On-Chain)
- Smart contract enforces a token allowlist at the EVM level
- Only Sardis-approved stablecoins (USDC, USDT, EURC) can be transferred out
- Agents cannot send NFTs, meme coins, or arbitrary tokens — even if someone sends them to the wallet
- On-chain guarantee, not just API-level filtering
- Toggle-able by Sardis for emergency recovery scenarios

## Status

- **Current Version**: v0.8.4 (Lithic Sandbox + Stablecoin Enforcement)
- **Infrastructure**: Live on Base Sepolia testnet, staging API on Cloud Run
- **Mainnet Launch**: Q2 2026
- **Protocols**: AP2, UCP, A2A, TAP, x402 all implemented

## What's New in v0.8.4 (February 2026)

- **Lithic Sandbox Cards** - Real Lithic virtual card issuance and transaction simulation in sandbox
- **Stablecoin-Only Smart Contract** - On-chain token allowlist prevents non-stablecoin transfers
- **Human-in-the-Loop Approval Queue** - Full create/approve/deny/expire/cancel lifecycle with webhooks
- **Goal Drift Detection** - Detect when agent spending patterns deviate from intended goals
- **Dashboard Cards Page** - Custom Sardis-branded card UI with issue/freeze/simulate/transactions
- **Live Demo Mode** - Landing page demo connects to real Lithic sandbox for provable transactions

### v0.8.5

- **Production-Grade Retry** - Configurable retry with exponential backoff and circuit breakers for all providers
- **SAR Persistence** - Suspicious Activity Reports persisted to PostgreSQL (FinCEN 5-year retention)
- **MCP Server v0.2.5** - 46 tools, sandbox demo walkthrough, prompts capability
- **Sandbox Demo Tool** - `sardis_sandbox_demo` for guided capability walkthrough

### Previous (v0.8.0)

- **Background Job Scheduler** - APScheduler for approval expiration, hold cleanup, spending limit reset
- **Alembic Migrations** - Database schema versioning with 6 migrations
- **Wallet Freeze** - Freeze/unfreeze capability with transaction blocking
- **Velocity Limits** - Daily/weekly/monthly limits for off-ramp operations
- **EIP-2771 Meta-Transactions** - Gasless transactions support
- **Batch Transfers** - Single API call for multiple transfers
- **Invoices API** - Full CRUD for merchant invoice management
- **Fireblocks Integration** - Institutional-grade MPC signing option
- **Prometheus Metrics** - Production monitoring endpoint
- **Sentry Integration** - Error tracking and alerting

---

*Last updated: February 2026*
*Version: 2.3*
