Scopes Reference - Sumvin API

Scopes declare what a authorises. Each scope is an -format capability string carried in the signed PurchaseIntent.scopes array and surfaced to partner integrations as the scopes claim on the exchanged . A Stamped Mandate is delivered over the API as a PINT (header x-sumvin-pint-token); the scope catalog below carries the same identifiers whether you read it as a Stamped Mandate or as its underlying PINT. The scope grammar is a specialisation of the broader Sumvin Resource Identifier family — same sr:{region}:… scheme, different shape. Scopes support per-scope parameters (amount caps, asset, provider, time windows) as URL query strings, giving partners fine-grained capability envelopes without expanding the scope vocabulary.

Every scope in this catalog maps one-to-one to an existing authenticated user-facing capability in the Sumvin API. When a Stamped Mandate carrying a scope is exchanged for a JWT, the scopes claim is exactly what the partner sees.

Grammar

sr:{region}:pint:{domain}:{action}[?{key}={value}&{key}={value}]

Segment	Description	Examples
`sr`	SRI scheme prefix	always `sr`
`region`	Geographic region code	`us`, `eu`, `gb`
`pint`	Literal disambiguator — marks this as a scope SRI (see SRI reference)	always `pint`
`domain`	Capability domain	`sigil`, `spend`, `errand`, `accounts`, `transactions`, `personalization`, `assets`, `budgets`, `pints`, `rules`, `strategies`, `wallets`, `cli`, `cards`
`action`	Action within the domain	`read`, `execute`, `manage`, `link`, `search`, `revoke`, …
`?{k=v}…`	Optional parameters (amount caps, asset, provider, time)	`?max=10000000&asset=USDC@sei`

Exactly five fixed segments — scheme, region, pint, domain, action. Query params are optional and delimited by ? with & between pairs.

Parameter Conventions

Convention	Form	Example
Numeric caps	Base units of the referenced asset	`max=10000000` = 10 USDC (6 decimals)
Asset + chain context	`SYMBOL@context` where context is a chain slug or `fiat`	`asset=USDC@sei`, `asset=USD@fiat`
Provider choice	Lowercase alphanumeric, drawn from a fixed enum	`provider=meld`
Timestamps	Unix seconds	`from_date=1720000000`
Time windows	Unix seconds (window length)	`time=2592000` (30 days)

Values containing &, =, or whitespace must be percent-encoded. The scope string is always signed verbatim as part of the Stamped Mandate payload, so any encoding applied at sign time is preserved end-to-end.

Verification Tier Mapping

Scopes drive the verification tier of the exchanged JWT.

Standard (Tier 1) — JWT alone is sufficient. Partner validates JWT signature, audience, expiry.
Enhanced (Tier 2) — JWT + the original Stamped Mandate signature and payload headers (X-Pint-Signature, X-Pint-Payload).

Enhanced tier is reserved for the spend scopes that move value: sr:us:pint:spend:execute, sr:us:pint:spend:visa_checkout, and sr:us:pint:spend:card. Every other scope in the catalog is Standard. If a Stamped Mandate carries any Enhanced-tier scope, the entire JWT is issued at Enhanced tier. Read the Tier column of the catalog below as authoritative rather than memorising the list — it is generated from the same registry the API enforces.

Scope catalog

Every scope below is live in the registry. Requesting one that is not listed here is rejected at token exchange with PINT-400-004.

Scope	Domain	Grants	Required params	Optional params	Tier	KYC
`sr:us:pint:sigil:kyc_status`	sigil	Attests the user’s current KYC verification status (registered — no enforcement site yet)	—	—	Std	✓
`sr:us:pint:sigil:kyc_read`	sigil	Read full KYC applicant PII and documents	—	`doc_type`, `reason`, `requestor`	Std	✓
`sr:us:pint:sigil:proof_of_personhood`	sigil	Attests the user is a unique human (registered — no enforcement site yet)	—	—	Std	✓
`sr:us:pint:sigil:age_over_18`	sigil	Attests the user is 18 or older (registered — no enforcement site yet)	—	—	Std	✓
`sr:us:pint:spend:execute`	spend	On-chain spend via Safe/bundler, IPA auto-execute, or strategy run PINT link	—	`max`, `asset`, `chain_id`, `recipient`	Enh	✓
`sr:us:pint:spend:ramp`	spend	Fiat on-ramp via Meld widget	—	`max`, `asset`, `currency`	Std	✓
`sr:us:pint:spend:visa_checkout`	spend	Card checkout on the Visa Intelligent Commerce rail, fiat-capped per approval	`max`, `currency`	—	Enh	✓
`sr:us:pint:spend:card`	spend	Pins a card checkout approval to a specific enrolled card	`id`	—	Enh	✓
`sr:us:pint:errand:search`	errand	Create an Errand: enrol in long-running scoped purchase search	`time`	`max`	Std	✓
`sr:us:pint:errand:triage`	errand	Open an Errand from an accepted insight	—	—	Std	✓
`sr:us:pint:errand:task`	errand	Open an Errand from an assistant task	—	—	Std	✓
`sr:us:pint:errand:insights`	errand	Open an Errand from a generated insight	—	—	Std	✓
`sr:us:pint:errand:read`	errand	Read Errand list, detail, and event history	—	—	Std	—
`sr:us:pint:errand:manage`	errand	Clarify, decide on, or cancel an existing Errand	—	—	Std	—
`sr:us:pint:accounts:read`	accounts	Read linked bank accounts and balances	—	—	Std	—
`sr:us:pint:accounts:link`	accounts	Link bank accounts; exchange link tokens; issue processor tokens	—	`provider`	Std	—
`sr:us:pint:accounts:transfer`	accounts	Fiat transfer to wallet (reserved — no enforcement site yet)	—	`max`, `asset`, `currency`	Std	✓
`sr:us:pint:transactions:read`	transactions	Read transaction history, details, and receipts	—	`from_date`, `to_date`	Std	—
`sr:us:pint:personalization:read`	personalization	Read insights, rules, and budgets (registered — no enforcement site yet)	—	—	Std	—
`sr:us:pint:assets:read`	assets	Read the assets held across the user’s wallets, with balances and prices	—	—	Std	—
`sr:us:pint:budgets:read`	budgets	Read the user’s spending budgets and how much of each has been used	—	—	Std	—
`sr:us:pint:budgets:manage`	budgets	Create, change, and delete the user’s spending budgets	—	—	Std	—
`sr:us:pint:pints:read`	pints	Read the approvals the user has granted, including what each one permits	—	—	Std	—
`sr:us:pint:pints:revoke`	pints	Revoke an approval the user has granted. Revoking is permanent and withdraws every credential issued from that approval	—	—	Std	—
`sr:us:pint:rules:read`	rules	Read the rules the user has set for how their money is handled	—	—	Std	—
`sr:us:pint:rules:manage`	rules	Create, change, and delete the rules the user has set	—	—	Std	—
`sr:us:pint:strategies:read`	strategies	Read the strategy catalogue, the strategies the user has enrolled in, and the history of their runs	—	—	Std	—
`sr:us:pint:strategies:manage`	strategies	Enrol the user in a strategy, change one they are enrolled in, and act on the tasks a strategy run raises	—	—	Std	—
`sr:us:pint:wallets:read`	wallets	Read the user’s wallets, including addresses, chains, and nicknames	—	—	Std	—
`sr:us:pint:wallets:manage`	wallets	Change wallet settings such as the nickname and which wallet is primary	—	—	Std	—
`sr:us:pint:cli:delegate_sign`	cli	Marks a mandate signed by the developer’s local key via the CLI	—	—	Std	—
`sr:us:pint:cli:add_signer`	cli	Marks a mandate that adds a signing key to the user’s Safe	—	—	Std	—
`sr:us:pint:cards:read`	cards	Read card details (last4, brand, status)	—	—	Std	✓
`sr:us:pint:cards:manage`	cards	Freeze/unfreeze card; change funding wallet	—	—	Std	✓

Scope Details

This section expands the scopes with parameter enforcement or a documented endpoint surface. Scopes not expanded here take no parameters — the catalog row above is the whole contract.

Sigil

Sigil is the identity domain. The older sr:us:pint:identity:* names for these four scopes are deprecated aliases.

`sr:us:pint:sigil:kyc_status`

Endpoint gated: GET /v0/kyc/status
Params: none
Tier: Standard · KYC required: ✓

Attests the user’s current KYC verification status. The JWT’s kyc_status claim carries the canonical value (pending, verified, rejected, …) for partners to read directly.

`sr:us:pint:sigil:kyc_read`

Endpoint gated: SIS /v0/users/{id}/kyc + /document
Optional params: doc_type (e.g. passport, id_card), reason (choices: onramp), requestor (choices: mercuryo)
Tier: Standard · KYC required: ✓

Grants SIS partners dual-authenticated read access to the user’s KYC applicant PII and document images. See Getting User KYC Data for the full SIS flow.

`sr:us:pint:sigil:proof_of_personhood`

Surface: JWT attestation claim
Params: none
Tier: Standard · KYC required: ✓

Attests the user is a unique, KYC-verified human. Partners can consume this as a binary gate without needing the underlying KYC details.

`sr:us:pint:sigil:age_over_18`

Surface: JWT attestation claim
Params: none
Tier: Standard · KYC required: ✓

Attests the user is 18 or older. Commonly used for age-gated content and services that need a boolean signal without the user’s date of birth.

Spend

`sr:us:pint:spend:execute`

Endpoints gated: POST /v0/safe/rpc, IPA auto-execute, strategy run PINT linking
Optional params: max (base units), asset (SYMBOL@context), chain_id, recipient (comma-separated allowed addresses)
Tier: Enhanced · KYC required: ✓
Example: sr:us:pint:spend:execute?max=10000000&asset=USDC@sei&chain_id=1329

Authorises on-chain spend on behalf of the user. Enhanced tier — partners must verify the original Stamped Mandate signature, not just the JWT. When max + asset are set, the API enforces them against the actual transaction amount and asset at execution time.

`sr:us:pint:spend:ramp`

Endpoint gated: POST /v0/ramp/sessions (hosted on-ramp widget)
Optional params: max, asset, currency
Tier: Standard · KYC required: ✓
Example: sr:us:pint:spend:ramp?max=50000&currency=USD

Authorises a fiat-to-crypto ramp session via the hosted on-ramp widget. max and currency are enforced against the ramp session request when present.

`sr:us:pint:spend:visa_checkout`

Required params: max (fiat minor units), currency (ISO-4217)
Tier: Enhanced · KYC required: ✓
Example: sr:us:pint:spend:visa_checkout?max=25000&currency=USD ($250.00 ceiling)

Authorises a card checkout on the Visa Intelligent Commerce rail. Both params are required — an approval carrying this scope always names its fiat ceiling and currency.

`sr:us:pint:spend:card`

Required params: id (external id of the enrolled card)
Tier: Enhanced · KYC required: ✓

Pins a card checkout approval to one specific enrolled card. An approval without this scope leaves the card to be chosen when the purchase is made.

Errand

`sr:us:pint:errand:search`

Endpoints gated: POST /v0/user/ipa/, IPA strategy enrolment
Required params: time (window length in unix seconds)
Optional params: max (base-unit purchase ceiling)
Tier: Standard · KYC required: ✓
Example: sr:us:pint:errand:search?time=2592000&max=5000000 (30-day window, $5 USDC cap)

Authorises the creation of an Intelligent Purchase Authorisation (IPA) and enrolment into Errand strategies. The time param is required on the scope string. API-side enforcement of time against the IPA’s lifecycle window is deferred pending the IPA schema gaining an explicit window field — today the scope’s presence is validated but the window is not yet bound. The older name sr:us:pint:perpetual:search is a deprecated alias for this scope.

Opening an Errand from an existing signal

Three scopes cover the other entry points into an Errand. None takes parameters; all are Standard tier and require KYC.

Scope	Opens an Errand from
`sr:us:pint:errand:triage`	an accepted insight
`sr:us:pint:errand:task`	an assistant task
`sr:us:pint:errand:insights`	a generated insight

Reading and steering an Errand

sr:us:pint:errand:read grants read access to the Errand list, detail, and event history. sr:us:pint:errand:manage grants the clarify, decide, and cancel operations on an existing Errand. Both are Standard tier and neither requires KYC — an agent can follow and steer an Errand without the verification needed to open one.

Accounts

`sr:us:pint:accounts:read`

Endpoint gated: GET /v0/accounts/
Params: none
Tier: Standard · KYC required: —

Read the user’s linked bank accounts and current balances. Used by delegated agent flows that need account context without the ability to initiate movement.

`sr:us:pint:accounts:link`

Endpoints gated: POST /v0/accounts/link, POST /v0/bank-linking/accounts/{account_id}/processor-token
Optional params: provider (choices: meld)
Tier: Standard · KYC required: —
Example: sr:us:pint:accounts:link?provider=meld

Link a new bank account via the hosted bank-linking provider.

`sr:us:pint:accounts:transfer`

Endpoint gated: (reserved — route TBD)
Optional params: max, asset, currency
Tier: Standard · KYC required: ✓

Reserved. The registry entry and parser support are in place so partner clients can begin requesting this scope, but there is no enforcement site in the current release — the transfer route is not yet live.

Transactions

`sr:us:pint:transactions:read`

Endpoints gated: GET /v0/transactions/, GET /v0/transactions/{transaction_id}, GET /v0/transactions/{external_id}/receipt
Optional params: from_date, to_date (unix seconds)
Tier: Standard · KYC required: —
Example: sr:us:pint:transactions:read?from_date=1704067200&to_date=1735603200

Read transaction history and receipts. When from_date / to_date are set, the API enforces them by rejecting any listing or detail request for a transaction outside the declared window.

Personalisation

`sr:us:pint:personalization:read`

Endpoint gated: (none yet — see registered but no enforcement site yet)
Params: none
Tier: Standard · KYC required: —

Covers AI-generated insights, user-defined rules, and budgets. The scope is registered and parses successfully, but no route enforces it today. The finer-grained sr:us:pint:rules:* and sr:us:pint:budgets:* scopes cover the same surface.

Personal finance data

These scopes cover the user’s own money surface. None takes parameters, all are Standard tier, and none requires KYC.

Scope	Grants
`sr:us:pint:assets:read`	Read the assets held across the user’s wallets, with balances and prices
`sr:us:pint:budgets:read`	Read the user’s spending budgets and how much of each has been used
`sr:us:pint:budgets:manage`	Create, change, and delete the user’s spending budgets
`sr:us:pint:rules:read`	Read the rules the user has set for how their money is handled
`sr:us:pint:rules:manage`	Create, change, and delete the rules the user has set
`sr:us:pint:strategies:read`	Read the strategy catalogue, the strategies the user has enrolled in, and the history of their runs
`sr:us:pint:strategies:manage`	Enrol the user in a strategy, change one they are enrolled in, and act on the tasks a strategy run raises
`sr:us:pint:wallets:read`	Read the user’s wallets, including addresses, chains, and nicknames
`sr:us:pint:wallets:manage`	Change wallet settings such as the nickname and which wallet is primary

sr:us:pint:strategies:manage enrols the user and acts on run tasks. It does not authorise value movement — a strategy run that spends still needs sr:us:pint:spend:execute, which is Enhanced tier.

Approvals

These scopes let a holder inspect and withdraw the user’s own approvals. Both are Standard tier, take no parameters, and require no KYC.

sr:us:pint:pints:read — read the approvals the user has granted, including what each one permits.
sr:us:pint:pints:revoke — revoke an approval the user has granted. Revoking is permanent and withdraws every credential issued from that approval.

Revoking is permanent and withdraws every credential issued from that approval. See Revocation for what a verifier observes after a revoke.

CLI

Two provenance markers used by the Sumvin CLI. Both are Standard tier, take no parameters, and require no KYC. Each records who signed the mandate, and PINT exchange rejects any mandate whose marker disagrees with its signer.

sr:us:pint:cli:delegate_sign — marks a mandate signed by the developer’s local key via the CLI (caller-supplied signature). Exchange rejects the marker when the mandate was server-agent-signed.
sr:us:pint:cli:add_signer — marks a mandate that adds a signing key to the user’s Safe. Exchange rejects the marker unless the mandate was server-agent-signed.

A signer change alters who can authorise on the Safe from then on, so add_signer is never accepted on a locally-signed mandate. A mandate carrying it without a server agent signature is refused at token exchange with PINT-422-003.

Cards

`sr:us:pint:cards:read`

Endpoints gated: GET /v0/card/, GET /v0/card/{card_id}
Params: none
Tier: Standard · KYC required: ✓

Read card details (last4, brand, status, funding wallet). Does not expose the card PAN or CVV — those are only surfaced via a separate, short-lived session.

`sr:us:pint:cards:manage`

Endpoints gated: POST /v0/card/{card_id}/freeze, POST /v0/card/{card_id}/unfreeze, POST /v0/card/{card_id}/lost, POST /v0/card/{card_id}/stolen, POST /v0/card/{card_id}/activate; funding wallet change
Params: none
Tier: Standard · KYC required: ✓

State-change operations on an existing card. Excludes card creation and excludes any spend flow — sr:us:pint:cards:manage is strictly about card lifecycle, not value transfer.

Scope Validation

Scopes are validated at two points:

Creation time (schema). When a Stamped Mandate is created at token exchange, every scope string is parsed and validated. Malformed grammar, unknown scope names, and malformed params are rejected before the Stamped Mandate is persisted.
Enforcement time (semantic). When a request carries a PINT token, the gated endpoint enforces per-param limits (amount caps, asset match, provider match, date range, …) against the actual request.

Validation at both layers prevents malformed scopes from entering the system and prevents legitimate scopes from being used outside their declared envelope.

Error Codes

Status	Code	When
400	`PINT-400-003`	Scope parameter is malformed or violates its declared type / range (e.g. `max=abc`, `provider=stripe`). `detail` names the offending scope and param.
400	`PINT-400-004`	Scope name is not in the registry (not a recognised MVP scope). `detail` echoes the offending scope string.
400	`PINT-400-005`	Scope string does not conform to the grammar (wrong segment count, wrong scheme, malformed query). `detail` echoes the offending scope string.
403	`PINT-403-001`	The signer is not authorised for a requested scope, or the request omits a PINT token but carries a scope-gated endpoint invocation.
422	`PINT-422-003`	A CLI provenance marker disagrees with who signed the mandate — `cli:delegate_sign` on a server-agent-signed mandate, or `cli:add_signer` on one that is not.

All error responses follow RFC 7807 Problem Details. See Errors for the full error catalog.

Scope Combinations

A single Stamped Mandate can request multiple scopes:

{
  "scopes": [
    "sr:us:pint:sigil:kyc_status",
    "sr:us:pint:spend:execute?max=10000000&asset=USDC@sei&chain_id=1329"
  ]
}

The resulting JWT will carry both scopes in its scopes claim, and the verification tier is the highest tier present — if any scope is Enhanced, the entire JWT is issued at Enhanced tier. Two scopes with the same name but different params (e.g. sr:us:pint:spend:execute?max=100000000 and sr:us:pint:spend:execute?max=200000000) are treated as distinct capability envelopes — both are retained in the signed array. Exact duplicates are collapsed.

Deprecated aliases

Five scope names remain in the registry only so that already-issued Stamped Mandates keep working. They parse and enforce exactly like their canonical counterpart, but new integrations should request the canonical name.

Deprecated alias	Canonical scope
`sr:us:pint:perpetual:search`	`sr:us:pint:errand:search`
`sr:us:pint:identity:kyc_status`	`sr:us:pint:sigil:kyc_status`
`sr:us:pint:identity:kyc_read`	`sr:us:pint:sigil:kyc_read`
`sr:us:pint:identity:proof_of_personhood`	`sr:us:pint:sigil:proof_of_personhood`
`sr:us:pint:identity:age_over_18`	`sr:us:pint:sigil:age_over_18`

A verifier reading the scopes claim may still receive a deprecated alias from an in-flight credential. Treat an alias and its canonical scope as the same capability.

Post-MVP Scopes

The following scopes are not yet generally available. They fall into two categories.

Reserved for future releases

These scopes are not in the registry today. Requesting any of them during token exchange is rejected with PINT-400-004.

Scope	Status
`sr:us:pint:personalization:write`	Deferred
`sr:us:pint:chat:read`	Deferred
`sr:us:pint:chat:write`	Deferred
`sr:us:pint:identity:lookup`	Deferred

Wildcard scopes such as sr:us:pint:sigil:* are not part of the grammar. Every scope is requested by its exact name.

Registered but no enforcement site yet

These scopes are in the registry — requesting them parses successfully and they appear in the issued JWT — but no API endpoint consumes them yet.

Scope	Status
`sr:us:pint:accounts:transfer`	Registered, enforcement pending route landing (fiat → wallet transfer route not yet live)
`sr:us:pint:personalization:read`	Registered; insight, rule, and budget routes remain gated by user status only
`sr:us:pint:sigil:kyc_status`	Registered; no endpoint consumes it. `sigil:kyc_read` is the only Sigil scope with an enforcement site
`sr:us:pint:sigil:proof_of_personhood`	Registered; no endpoint consumes it
`sr:us:pint:sigil:age_over_18`	Registered; no endpoint consumes it

Holding one of these scopes is not evidence that anything checked it. Do not treat the presence of an attestation scope in a token as an attestation — the claim it names is not verified at any endpoint today.

Scope definitions are versioned alongside the EIP-712 specification. See EIP-712 & Purchase Intents for the canonical type definitions and SRI for the underlying URI family.

​Grammar

​Parameter Conventions

​Verification Tier Mapping

​Scope catalog

​Scope Details

​Sigil

​sr:us:pint:sigil:kyc_status

​sr:us:pint:sigil:kyc_read

​sr:us:pint:sigil:proof_of_personhood

​sr:us:pint:sigil:age_over_18

​Spend

​sr:us:pint:spend:execute

​sr:us:pint:spend:ramp

​sr:us:pint:spend:visa_checkout

​sr:us:pint:spend:card

​Errand

​sr:us:pint:errand:search

​Opening an Errand from an existing signal

​Reading and steering an Errand

​Accounts

​sr:us:pint:accounts:read

​sr:us:pint:accounts:link

​sr:us:pint:accounts:transfer

​Transactions

​sr:us:pint:transactions:read

​Personalisation

​sr:us:pint:personalization:read

​Personal finance data

​Approvals

​CLI

​Cards

​sr:us:pint:cards:read

​sr:us:pint:cards:manage

​Scope Validation

​Error Codes

​Scope Combinations

​Deprecated aliases

​Post-MVP Scopes

​Reserved for future releases

​Registered but no enforcement site yet

Grammar

Parameter Conventions

Verification Tier Mapping

Scope catalog

Scope Details

Sigil

`sr:us:pint:sigil:kyc_status`

`sr:us:pint:sigil:kyc_read`

`sr:us:pint:sigil:proof_of_personhood`

`sr:us:pint:sigil:age_over_18`

Spend

`sr:us:pint:spend:execute`

`sr:us:pint:spend:ramp`

`sr:us:pint:spend:visa_checkout`

`sr:us:pint:spend:card`

Errand

`sr:us:pint:errand:search`

Opening an Errand from an existing signal

Reading and steering an Errand

Accounts

`sr:us:pint:accounts:read`

`sr:us:pint:accounts:link`

`sr:us:pint:accounts:transfer`

Transactions

`sr:us:pint:transactions:read`

Personalisation

`sr:us:pint:personalization:read`

Personal finance data

Approvals

CLI

Cards

`sr:us:pint:cards:read`

`sr:us:pint:cards:manage`

Scope Validation

Error Codes

Scope Combinations

Deprecated aliases

Post-MVP Scopes

Reserved for future releases

Registered but no enforcement site yet