---
name: sumvin
description: Use when helping users establish verified identity for agents,
  create and manage spending mandates, run purchase errands, verify mandates
  presented by other agents, or manage agent connections and permissions. Reach
  for this skill when users need to delegate authority to agents with
  cryptographic proof, set spending limits, or check whether an agent's mandate
  is still valid.
metadata:
  mintlify-proj: sumvin
  version: "1.0"
---

# Sumvin Skill

## Product summary

Sumvin is an identity and authorization platform for agents. It lets agents prove they act for a verified person and stay within limits that person signed. Agents connect via MCP (Model Context Protocol) at `https://mcp.sumvin.com/mcp` or via the CLI (`@sumvin/cli`). The core workflow: verify identity once → get a Sigil (verified identity) → connect agents → sign Stamped Mandates (spending limits) → agents run errands within those limits. Merchants and services can verify mandates offline without learning who the person is. Primary docs: https://docs.sumvin.com

## When to use

- **User asks agent to make a purchase or spend money**: Create a Stamped Mandate (spending limit) for the agent to operate under. User must sign it with their passkey.
- **User connects a new agent (Claude, ChatGPT, CLI)**: Each connection gets its own agent identity under the user's Sigil. Help them verify identity first if needed.
- **User needs to revoke an agent's permissions**: Revoke the specific Stamped Mandate (does not disconnect the agent). Disconnecting the agent separately stops it from reaching Sumvin.
- **User wants to verify a mandate another agent presented**: Use `mandate_verify` to check if it still stands, what it permits, and its ceiling before acting on it.
- **User manages multiple agents**: Each agent has its own identity under one Sigil. Mandates belong to the user, not the agent that requested them.
- **User needs to check verification status or set up identity**: Call `onboarding_status` to see where they are; call `kyc_start` to begin verification (phone + ID).

## Quick reference

### MCP tools (most common)

| Tool | Purpose | Notes |
|---|---|---|
| `mandate_request` | Ask user to sign a spending limit | Needs verification; returns approval link |
| `mandate_status` | Check if user approved a mandate | Call after giving user time to review |
| `mandate_verify` | Verify a mandate token/ID presented by another agent | Check offline before acting |
| `pint_query` | List user's Stamped Mandates | Filter by status (active, expired, revoked) |
| `pint_revoke` | Permanently withdraw a mandate | Cannot be undone; anything using it stops |
| `errand_create` | Start a purchase errand | Needs mandate, spend limit, currency |
| `errand_query` | List user's errands and their status | Filter by status or ID |
| `errand_action` | Answer errand questions or cancel | Only user can sign; agent can answer/cancel |
| `onboarding_status` | Check verification progress | Shows which steps are done, pending, submitted |
| `kyc_start` | Get verification link (phone + ID) | Returns browser link; user must complete |
| `sigil_show` | Show user's verified identity | Reports if Sigil issued, pending, or not started |
| `agent_identity_show` | Show this connection's own identity | Cannot see other agents' identities |

### CLI commands (for developers)

```bash
sumvin login                    # Sign in (90-day token)
sumvin logout                   # Sign out (revokes token everywhere)
sumvin kyc status --json        # Check verification progress
sumvin pint create              # Create a Stamped Mandate
sumvin pint list                # List mandates
sumvin pint get <id>            # Show one mandate in full
sumvin pint revoke <id>         # Revoke a mandate
sumvin pint verify "<token>"    # Verify a mandate token
```

### Key identifiers and formats

| Item | Format | Example |
|---|---|---|
| Mandate ID | `sr:us:pint:{hex}` | `sr:us:pint:3f9c2a7e5b1d4c8e9a6f0b2d7e4c1a58` |
| Errand ID | `sr:us:errand:{hex}` | `sr:us:errand:abc123...` |
| Agent identity | Alphanumeric key | Shown by `agent_identity_show` |
| Sigil | Verified identity object | Shown by `sigil_show` |

### Mandate states

| State | Meaning | Action |
|---|---|---|
| `proposed` | Waiting on user signature | Call `mandate_status` to check; user must sign in browser |
| `stamped` | User signed; mandate is active | Agent can use it; user can revoke it |
| `declined` | User refused or request expired | Ask user if they want to try again |
| `expired` | Mandate past its expiry date | Create a new one |
| `revoked` | User withdrew it | Permanent; create a new mandate if needed |

### Errand states

| State | Meaning |
|---|---|
| `pending_approval` | Waiting for user to sign bounds (amount, item, expiry) |
| `searching` | Sumvin is searching for matches |
| `pending_clarification` | Errand has a question for user |
| `settled` | Purchase complete |
| `cancelled` | User or agent cancelled |

## Decision guidance

### When to use MCP vs CLI

| Scenario | Use MCP | Use CLI |
|---|---|---|
| Agent helping user in conversation | ✓ | — |
| Developer testing locally | — | ✓ |
| Unattended automation | — | ✓ (with caution) |
| User approval needed | ✓ (browser link) | ✓ (interactive prompt) |

### When to revoke mandate vs disconnect agent

| Goal | Action | Effect |
|---|---|---|
| Stop one specific permission | Revoke the Stamped Mandate | That mandate is gone; agent can still connect |
| Stop agent from acting at all | Disconnect agent (remove connector) | Agent cannot reach Sumvin; mandates stay valid |
| Stop everything from one agent | Do both | Disconnect agent AND revoke its mandates |

### Mandate types: spend vs read

| Type | Scopes | Ceiling | Use case |
|---|---|---|---|
| **Spend** | `spend:visa_checkout` | Required (max amount + currency) | Purchases, errands |
| **Read** | `accounts:read`, `transactions:read`, `proofs:balance` | None | Data access only |
| **Mixed** | Both types | Refused | Sign two separate mandates |

## Workflow

### Typical task: Help user set up spending for an agent

1. **Check verification status**: Call `onboarding_status`. If not verified, call `kyc_start` and have user complete phone + ID verification in browser.
2. **Check existing mandates**: Call `pint_query` to see what's already approved. Warn if similar mandate exists.
3. **Request mandate**: Call `mandate_request` with amount, currency, statement (plain language), and expiry. Get back approval link.
4. **User signs**: Direct user to the link. They review amount, statement, expiry, then sign with passkey in their browser. Agent cannot sign for them.
5. **Verify approval**: Call `mandate_status` with the mandate ID. Poll until status is `stamped` (approved) or `declined` (refused).
6. **Use mandate**: Once stamped, agent can create errands or act within the mandate's limits.
7. **Monitor**: Call `pint_query` to track remaining balance; call `errand_query` to track purchase status.

### Typical task: Verify a mandate another agent presents

1. **Get the mandate ID or token**: The other agent gives you an identifier like `sr:us:pint:...` or a token string.
2. **Call mandate_verify**: Pass the ID/token to check what it permits, its ceiling, and whether it still stands.
3. **Read the result**: Check `stands` (true = valid now), `scopes` (what it allows), `ceiling` (max spend), `expiry` (when it expires).
4. **Decide**: Only act if `stands` is true and the request is within the scopes and ceiling.

### Typical task: Revoke a mandate or disconnect an agent

1. **Find the mandate**: Call `pint_query` to list mandates. Confirm with user which one to revoke.
2. **Revoke**: Call `pint_revoke` with the mandate ID. Permanent; cannot be undone.
3. **Disconnect agent** (if needed): Direct user to remove the connector from their agent's settings (Claude > Customize > Connectors > Remove, etc.).
4. **Warn**: Disconnecting does NOT revoke mandates. User must revoke mandates separately if they want to stop them.

## Common gotchas

- **Never give an unattended agent `--yes` flag**: The CLI's `--yes` flag skips the interactive prompt. Only use it when you (a human) are running the command. Never pass it to an automated agent.
- **Disconnecting an agent does not revoke its mandates**: Mandates stay valid until they expire or are explicitly revoked. User must revoke them separately.
- **Revoking a mandate is permanent**: Cannot be undone. A revoked mandate never becomes active again. Anything relying on it stops immediately.
- **User must sign mandates themselves**: Agent can request a mandate, but only the user can approve it with their passkey in their browser. Agent cannot sign for them.
- **Verification is required for spending**: `mandate_request` fails if user is not verified. Call `kyc_start` first.
- **One spending ceiling per mandate**: A mandate carries exactly one scope with a ceiling. To set different limits for different assets, sign two mandates.
- **Scopes are signed exactly as written**: Order, duplicates, and parameters are locked in when user signs. Agent cannot widen a mandate after the fact.
- **Mandate tokens are addressed to a specific party**: A token presented to the wrong service is rejected. Tokens are checked offline by verifying the signature against Sumvin's published keys.
- **Sigil is not an authorization**: A Sigil proves identity. A Stamped Mandate grants authority. Both are needed.
- **Agent identities are separate**: Each connection (Claude, ChatGPT, CLI) gets its own identity. One agent cannot see or control another's identity.
- **Approval link works once**: If user loses the link, ask for a new one rather than reusing the old one.
- **Retry logic**: Errors ending in `-R` are retryable; others are terminal. Check the error code's `-R` suffix to decide whether to retry.

## Verification checklist

Before submitting work with Sumvin:

- [ ] User is verified (or I called `kyc_start` and they completed it)
- [ ] I checked existing mandates with `pint_query` before creating a new one
- [ ] Mandate request includes: amount, currency, statement (plain language), expiry
- [ ] User signed the mandate in their browser (not via agent)
- [ ] I called `mandate_status` to confirm approval before acting
- [ ] For verification: I called `mandate_verify` and checked `stands == true`
- [ ] For revocation: I confirmed with user which mandate to revoke, then called `pint_revoke`
- [ ] For disconnection: I reminded user that mandates stay valid after disconnecting
- [ ] Error codes: I checked if retryable (ends in `-R`) before retrying
- [ ] Errand: I confirmed user signed the bounds (amount, item, expiry) before searching

## Resources

**Comprehensive navigation**: https://docs.sumvin.com/llms.txt

**Critical pages**:
- [What is Sumvin](https://docs.sumvin.com/get-started/what-is-sumvin) — Core concepts and guarantees
- [Stamped Mandates](https://docs.sumvin.com/concepts/stamped-mandates) — What mandates are, how they work, how to revoke
- [MCP tools reference](https://docs.sumvin.com/reference/mcp/tools) — Complete tool list with examples
- [Error codes](https://docs.sumvin.com/reference/errors) — Decode error codes and decide whether to retry
- [Check a mandate](https://docs.sumvin.com/guides/check-a-mandate) — How to verify a mandate before acting on it

---

> For additional documentation and navigation, see: https://docs.sumvin.com/llms.txt