Scopes

A scope says one thing an agent may do. Each scope belongs to a family, named by its domain. This page lists the families and what every scope in them grants. Needs a verified Sigil means the scope can only be used for a person who has completed verification. A mandate carrying it does nothing for an unverified account. Parameters are written as described in The mandate language. A parameter marked required must be present for the scope to be signed at all.

​

Sigil: facts about you

Attestations about the verified person behind the agent, and one read of the agent’s own identity. kyc_read parameters:

• doc_type: limit the read to one kind of document, such as passport or id_card.
• reason: why the details are shared. One of a fixed list.
• requestor: the provider that receives them. One of a fixed list.

Sharing your details with a provider needs a kyc_read scope that carries both reason and requestor. The lists grow as providers are added. The three attestations (kyc_status, proof_of_personhood, age_over_18) are the only scopes a mandate may carry when it is addressed to a website by its hostname. See Resources and conditions.

​

Spend: paying for things

Purchases, which run as errands. max on spend:visa_checkout is the most one checkout may charge, in the display unit of currency. See Spending ceilings. Scopes that spend a named asset, such as spend:execute, can appear more than once on a mandate, for example one per asset. Every one that matches the asset being moved applies, and the tightest limit wins. See Several spending scopes.

​

Errand: purchase tasks

Starting, reading and managing errands. errand:search parameters:

• time: how long the errand may keep searching, in seconds. 604800 is seven days. Sumvin also applies its own upper limit, and the shorter of the two wins.
• max: an optional purchase ceiling. It is not enforced, because this scope names no currency to measure it in. Put the ceiling that counts on spend:visa_checkout.

Starting an errand spends nothing. Paying needs a spend scope as well.

​

Accounts and transactions: open-banking data

Linking accounts and reading their data through Meld.

​

Limit reads to a date range

With from_date or to_date, every transaction read is held inside that range: the list of transactions, a single transaction, a receipt download, and the transaction_query tool on the connector. This holds whether or not the agent’s request names dates of its own, so an agent that asks for everything gets only what falls inside the range.

• A date filter outside the range is refused. A request for dates the range doesn’t cover is refused: with a 403 (PINT-403-001) over the API, and with a tool error naming the permitted range on MCP. With several ranges, a request that falls between two of them returns no transactions rather than being refused.
• A single transaction outside the range is refused. Fetching one by its id, or downloading its receipt, is refused with a 403.
• Several entries add up. A mandate can carry more than one transactions:read scope. A transaction is readable when it falls inside any of their ranges.
• An entry with no dates leaves reads unbounded. If any transactions:read scope states neither date, the mandate doesn’t limit which transactions the agent can read.

​

Proofs: facts about your money

Proving something about your money to someone else without showing them the figures. proofs:balance parameters:

• min: the amount being proven, in the display unit of currency. It follows the same rules as a spending ceiling: fractions up to the currency’s precision, positive only, written as a plain decimal. A min finer than the currency’s precision, such as min=1.001&currency=USD, is refused, never rounded. See Spending ceilings and Numbers.
• currency: the ISO 4217 code the amount is stated in, such as USD.
• timing: when the balance is checked. live checks it each time a proof is made, and is the default. snapshot checks the most recent balance on record. frozen checks it once and holds the answer for the life of the mandate.

​

Read mandates

An agent asking you directly for a mandate asks for one of two kinds:

• Spend: the spend scopes above, with exactly one spending ceiling.
• Read: any of accounts:read, transactions:read and proofs:balance. A read mandate spends nothing and carries no ceiling.

A request mixing the two kinds is refused. To grant both, sign two mandates. See Time limits for how long each lasts.

​

Mandates: asking for and checking mandates

mandates:read covers only your own requests. Checking a mandate that belongs to someone else always needs mandates:verify.

​

Onboarding: setting up your account

​

Your account

Reading what your Sumvin account holds. Your linked accounts and transactions are covered by the accounts and transactions family above.

​

Not listed here

The catalogue also holds scopes for products these docs don’t cover, and a few reserved names with nothing behind them yet. A mandate naming a scope that is not in the catalogue at all is refused.

​

Next