# Attesso - Payment Infrastructure for AI Agents

> Attesso enables AI agents to make purchases on behalf of users. Standing mandates with WebAuthn passkey authorization. JIT ephemeral card issuance. No app required.

## Overview

Attesso is payment infrastructure for the AI agent economy. It solves "How do AI agents pay for things?" by introducing:

1. **Standing Mandates**: Long-lived spending policies signed with WebAuthn passkeys (FaceID/TouchID). No charge at creation.
2. **JIT Card Issuance**: Ephemeral virtual cards issued on-demand with auth-hold and 5-minute TTL. Auto-destroyed after use.
3. **Guardrails**: Amount limits, MCC filtering, instant revocation.

## Installation

```bash
npm install @attesso/sdk
```

## How It Works

```
1. Agent → POST /v1/mandate-requests       → creates authorization link
2. User opens link → FaceID/WebAuthn        → mandate created (no charge)
3. Agent has mandate_id (long-lived policy)  → monitors for deals
4. Agent → POST /v1/mandates/:id/issue      → auth-hold + ephemeral card (5min TTL)
5. Agent uses card at merchant checkout
6. Stripe authorization webhook             → auto-capture → card destroyed
7. If TTL expires unused                    → hold released → mandate back to active
```

## SDK Usage

```typescript
import { AttessoClient } from '@attesso/sdk';

const attesso = new AttessoClient({
  apiKey: process.env.ATTESSO_API_KEY
});

// Get an existing mandate
const mandate = await attesso.getMandate(mandateId);
console.log(`Budget: $${mandate.spendingLimit / 100}`);

// Issue an ephemeral card when ready to buy
const card = await attesso.issueCard(mandateId, {
  amount: 34700,      // $347.00 in cents
  ttlSeconds: 300,    // 5 minutes
});

// card.number, card.cvc, card.expMonth, card.expYear
// Use at merchant checkout, auto-captured on authorization
```

## Vercel AI SDK Integration

```typescript
import { generateText } from 'ai';
import { attesso } from '@attesso/sdk/vercel';

const result = await generateText({
  model: openai('gpt-4o'),
  tools: attesso.tools({ mandateId }),
  prompt: 'Book me a flight to NYC under $500',
});
```

Available tools:
- `attesso_get_mandate` - Read mandate details and spending limit
- `attesso_issue_card` - Issue ephemeral card with auth-hold
- `attesso_get_card` - Check card status
- `attesso_revoke_mandate` - Revoke a mandate

## MCP Server

```json
{
  "mcpServers": {
    "attesso": {
      "command": "npx",
      "args": ["-y", "@attesso/mcp"],
      "env": { "ATTESSO_API_KEY": "sk_test_..." }
    }
  }
}
```

Same 4 tools as Vercel AI SDK: `attesso_get_mandate`, `attesso_issue_card`, `attesso_get_card`, `attesso_revoke_mandate`.

## SDK Methods

- `attesso.getMandate(mandateId)` - Get mandate details
- `attesso.issueCard(mandateId, { amount, ttlSeconds })` - Issue ephemeral card
- `attesso.getPayment(paymentId)` - Get payment details
- `attesso.createMandateRequest({ ... })` - Create mandate request (returns approval URL)
- `attesso.getMandateRequest(requestId)` - Check mandate request status
- `attesso.cancelMandateRequest(requestId)` - Cancel pending request

## API Endpoints

### Issue Card
```
POST /v1/mandates/:id/issue
Authorization: Bearer sk_test_...

{
  "amount": 34700,
  "ttlSeconds": 300
}
```

Response:
```json
{
  "id": "card_abc123",
  "mandateId": "mandate_xyz",
  "number": "4242424242421234",
  "cvc": "123",
  "expMonth": 12,
  "expYear": 2027,
  "amount": 34700,
  "status": "active",
  "expiresAt": "2026-01-15T10:35:00Z"
}
```

### Create Mandate Request
```
POST /v1/mandate-requests
Authorization: Bearer sk_test_...

{
  "amount": 50000,
  "description": "Travel booking agent",
  "allowedMccCodes": ["3000-3299", "4511"],
  "feeMode": "markup"
}
```

### Other Endpoints
- `GET /v1/mandates/:id` - Get mandate
- `GET /v1/cards/:id` - Get card
- `DELETE /v1/mandates/:id` - Revoke mandate
- `GET /v1/mandate-requests/:id` - Get mandate request
- `POST /v1/mandates/preview-fees` - Preview fee calculation

## Fee Modes

- **Markup** (default): Fees added on top. Input amount = agent spending limit.
- **Inclusive**: Fees deducted from amount. Input amount = what user is charged.

## Security Model

CRITICAL: Agents CANNOT authorize funds. Only users can via passkey authentication.

- Authorization requires WebAuthn passkey (hardware-backed)
- Passkeys use device Secure Enclave (Apple) or TPM (Windows/Android)
- Cross-device auth via QR code uses phone's hardware security
- Agents can only: issueCard() (within approved mandate limits)
- All cards require valid mandate with amount within spending limit

## Error Codes

| Code | Description |
|------|-------------|
| `MANDATE_NOT_FOUND` | Mandate ID doesn't exist |
| `MANDATE_REVOKED` | User revoked the spending mandate |
| `MANDATE_EXPIRED` | Mandate has passed its expiration date |
| `AMOUNT_EXCEEDS_LIMIT` | Card amount exceeds mandate spending limit |
| `MERCHANT_NOT_ALLOWED` | MCC not in mandate's allowed categories |
| `CARD_NOT_FOUND` | Card ID doesn't exist |
| `CARD_EXPIRED` | Card TTL has expired |
| `INVALID_AMOUNT` | Amount must be a positive integer (in cents) |
| `AUTHORIZATION_FAILED` | Card declined or insufficient funds |
| `WEBAUTHN_VERIFICATION_FAILED` | Passkey signature verification failed |

## Links

- Docs: https://www.attesso.com/docs
- Dashboard: https://www.attesso.com
- API Base URL: https://api.attesso.com/v1

---
Built for the agent economy. Hardware-secured. No app required.