Scopes Reference

Scopes declare what a Purchase Intent (PINT) 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 . 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 PINT 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	`identity`, `spend`, `accounts`, `transactions`, `cards`, `personalization`, `perpetual`
`action`	Action within the domain	`read`, `execute`, `manage`, `link`, `search`, …
`?{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=plaid`, `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 PINT 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 + original PINT signature and payload headers (X-Pint-Signature, X-Pint-Payload).

In the MVP catalog, only sr:us:pint:spend:execute triggers Enhanced tier. All 13 other scopes are Standard. If a PINT carries any Enhanced-tier scope, the entire JWT is issued at Enhanced tier.

MVP Catalog

#	Scope	Domain	Grants	Required Params	Optional Params	Tier	KYC
1	`sr:us:pint:identity:kyc_status`	identity	Attest current KYC status	—	—	Std	✓
2	`sr:us:pint:identity:kyc_read`	identity	Read KYC applicant PII + documents	—	`doc_type`	Std	✓
3	`sr:us:pint:identity:proof_of_personhood`	identity	Attest user is a unique human	—	—	Std	✓
4	`sr:us:pint:identity:age_over_18`	identity	Attest user is 18 or older	—	—	Std	✓
5	`sr:us:pint:spend:execute`	spend	On-chain spend via Safe / IPA / strategy run	—	`max`, `asset`, `chain_id`	Enh	✓
6	`sr:us:pint:spend:ramp`	spend	Fiat on-ramp via Meld widget	—	`max`, `asset`, `currency`	Std	✓
7	`sr:us:pint:perpetual:search`	perpetual	Create IPA + enrol in perpetual search	`time`	`max`	Std	✓
8	`sr:us:pint:accounts:read`	accounts	Read linked bank accounts + balances	—	—	Std	—
9	`sr:us:pint:accounts:link`	accounts	Link bank accounts; exchange link / processor tokens	—	`provider`	Std	—
10	`sr:us:pint:accounts:transfer`	accounts	Fiat → wallet transfer (reserved, no enforcement site yet)	—	`max`, `asset`, `currency`	Std	✓
11	`sr:us:pint:transactions:read`	transactions	Read transaction history + receipts	—	`from_date`, `to_date`	Std	—
12	`sr:us:pint:personalization:read`	personalisation	Read insights, rules, budgets	—	—	Std	—
13	`sr:us:pint:cards:read`	cards	Read card details (last4, brand, status)	—	—	Std	✓
14	`sr:us:pint:cards:manage`	cards	Freeze/unfreeze card; change funding wallet	—	—	Std	✓

Scope Details

Identity

identity:kyc_status

Scope: sr:us:pint:identity:kyc_status Endpoint gated: GET /v0/kyc/status 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.

identity:kyc_read

Scope: sr:us:pint:identity:kyc_read Endpoint gated: SIS /v0/users/{id}/kyc + /document Optional params: doc_type (e.g. passport, id_card) 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.

identity:proof_of_personhood

Scope: sr:us:pint:identity:proof_of_personhood Surface: JWT attestation claim 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.

identity:age_over_18

Scope: sr:us:pint:identity:age_over_18 Surface: JWT attestation claim 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

spend:execute

Scope: 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 Tier: Enhanced · KYC required: ✓Authorises on-chain spend on behalf of the user. This is the only scope that triggers Enhanced verification — partners must verify the original PINT signature, not just the JWT. When max + asset are set, the API enforces them against the actual transaction amount and asset at execution time.Example: sr:us:pint:spend:execute?max=10000000&asset=USDC@sei&chain_id=1329

spend:ramp

Scope: sr:us:pint:spend:ramp Endpoint gated: POST /v0/ramp/sessions (Meld on-ramp widget) Optional params: max, asset, currency Tier: Standard · KYC required: ✓Authorises a fiat-to-crypto ramp session via the Meld widget. max and currency are enforced against the ramp session request when present.Example: sr:us:pint:spend:ramp?max=50000&currency=USD

Perpetual

perpetual:search

Scope: sr:us:pint:perpetual: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: ✓Authorises the creation of an Intelligent Purchase Authorisation (IPA) and enrolment into perpetual search 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.Example: sr:us:pint:perpetual:search?time=2592000&max=5000000 (30-day window, $5 USDC cap)

Accounts

accounts:read

Scope: sr:us:pint:accounts:read Endpoint gated: GET /v0/accounts/ 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.

accounts:link

Scope: sr:us:pint:accounts:link Endpoints gated: POST /v0/accounts/link, POST /v0/accounts/link/exchange, POST /v0/bank-linking/accounts/{account_id}/processor-token Optional params: provider (choices: plaid, meld) Tier: Standard · KYC required: —Link a new bank account via an open-banking provider. When provider is set, the API rejects attempts to exchange link tokens from other providers.Example: sr:us:pint:accounts:link?provider=plaid

accounts:transfer

Scope: 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

transactions:read

Scope: 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: —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.Example: sr:us:pint:transactions:read?from_date=1704067200&to_date=1735603200

Personalisation

personalization:read

Scope: sr:us:pint:personalization:read Endpoints gated: /v0/insights/, /v0/rules/, /v0/budgets/ Tier: Standard · KYC required: —Read AI-generated insights, user-defined rules, and budgets. No parameters — scope presence alone grants access to the full personalisation read surface.

Cards

cards:read

Scope: sr:us:pint:cards:read Endpoints gated: GET /v0/cards/, GET /v0/cards/{card_id} 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.

cards:manage

Scope: sr:us:pint:cards:manage Endpoints gated: POST /v0/cards/{card_id}/freeze, POST /v0/cards/{card_id}/unfreeze, POST /v0/cards/{card_id}/lost, POST /v0/cards/{card_id}/stolen, POST /v0/cards/{card_id}/activate; funding wallet change 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). The PurchaseIntentPayload.scopes validator runs every scope string through parse_pint_scope at token exchange. Malformed grammar, unknown scope names, and malformed params are rejected before the PINT is persisted.
Enforcement time (semantic). When a request carries a PINT token, the route handler for the gated endpoint reads the parsed scope from pint.scopes_parsed and 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.

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

Scope Combinations

A single PINT can request multiple scopes:

{
  "scopes": [
    "sr:us:pint:identity: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.

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:wallets:read`	Deferred
`sr:us:pint:personalization:write`	Deferred
`sr:us:pint:chat:read`	Deferred
`sr:us:pint:chat:write`	Deferred
`sr:us:pint:identity:lookup`	Deferred

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)

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

Identity & PINTs

Verifier Guide

API Reference

Grammar

Parameter Conventions

Verification Tier Mapping

MVP Catalog

Scope Details

Identity

identity:kyc_status

identity:kyc_read

identity:proof_of_personhood

identity:age_over_18

Spend

spend:execute

spend:ramp

Perpetual

perpetual:search

Accounts

accounts:read

accounts:link

accounts:transfer

Transactions

transactions:read

Personalisation

personalization:read

Cards

cards:read

cards:manage

Scope Validation

Error Codes

Scope Combinations

Post-MVP Scopes

Reserved for future releases

Registered but no enforcement site yet

Identity & PINTs

Verifier Guide

API Reference

​Grammar

​Parameter Conventions

​Verification Tier Mapping

​MVP Catalog

​Scope Details

​Identity

identity:kyc_status

identity:kyc_read

identity:proof_of_personhood

identity:age_over_18

​Spend

spend:execute

spend:ramp

​Perpetual

perpetual:search

​Accounts

accounts:read

accounts:link

accounts:transfer

​Transactions

transactions:read

​Personalisation

personalization:read

​Cards

cards:read

cards:manage

​Scope Validation

​Error Codes

​Scope Combinations

​Post-MVP Scopes

​Reserved for future releases

​Registered but no enforcement site yet

Grammar

Parameter Conventions

Verification Tier Mapping

MVP Catalog

Scope Details

Identity

Spend

Perpetual

Accounts

Transactions

Personalisation

Cards

Scope Validation

Error Codes

Scope Combinations

Post-MVP Scopes

Reserved for future releases

Registered but no enforcement site yet