Skip to main content
A connected agent doesn’t see everything Sumvin can do. It sees a fixed set of tools, chosen for the account holder’s own errands and identity — never budgets, card controls, or anything that isn’t the agent’s to touch. The account holder manages those in the Sumvin app or the CLI instead. Someone with no Sumvin account yet sees the same tools, but every one of them needs an account first. Calling any of them returns a refusal that carries a sign-up link to hand to the person — see Refusals. Each tool is either Read (returns information, changes nothing) or Write (starts or changes something). Most tools work for anyone with an account; a few need the account holder’s identity to be verified first — those are marked below.

​
Getting started

ReadShow where the account holder has got to in setting up their account: which steps are done, which are next, and how far the key they sign with has got. Reading it changes nothing.Each stage reads current (the one to do next), pending (still ahead), submitted (handed in and waiting on a review), completed, or skipped (waived for this account). The identity stage can also read retry: the reviewer asked for the ID capture again. The account holder retakes it on the verification page they already have open, and their phone stays confirmed. If that page is closed, call kyc_start for a fresh link.Each stage also carries recorded_at: when it reached its status, in epoch milliseconds. It’s null while the stage is open, or when no time was recorded.While the account holder still owes a signing key, the answer carries signing_key_url: the browser page where they create and bind that key themselves. Your agent hands it to them to open; there’s nothing it can call to bind the key on their behalf.
Try asking your agent: “Where am I up to with Sumvin?”

​
Identity

ReadShow the account holder’s Sigil — their verified identity. Reports whether it’s been issued yet, is being issued right now, or hasn’t started. Not having one yet is a normal answer, not a problem.
Try asking your agent: “Show me my Sigil.”

​
Stamped Mandates

A Stamped Mandate is a signed authorisation for what one agent may do. These tools cover the spending kind — how much an agent may spend, and until when — because that’s what the mandate tools support today. These tools still show their internal name, pint, in two places: it’s the same object as a Stamped Mandate, and the rename is in progress.
Write · Needs verificationAsk the account holder to authorise spending, and get the link that lets them review and sign it. This doesn’t grant anything by itself — only the account holder can sign, on their own page, and an agent can’t do that for them. Needs a wallet and a verified identity first; if either is missing, this says which one and where to go next.
Try asking your agent: “Set up a spending limit of $50 for groceries this week.”

​
Payment methods

An errand pays with the card the account holder has added. These tools let an agent check that a card is ready and, when it isn’t, send the account holder to the page where they add one. The card is always entered on that page, by the account holder — never in the conversation.
ReadList the cards the account holder has added and whether each is ready. A card can pay for an errand only once it shows as verified. Card numbers are never shown — only the last four digits.
Try asking your agent: “Is my card ready for purchases?”

​
Errands

An errand is a long-running purchase task the account holder asked their agent to make, run within a Stamped Mandate.
WriteStart a new errand from what the account holder asked for, in their own words. Starting an errand begins the search for what they want — it doesn’t authorise any spending on its own.
Try asking your agent: “Reorder my usual coffee beans.”

​
Account

ReadRead the account holder’s linked accounts.
Try asking your agent: “What accounts do I have linked?”

​
Server

Read · No account neededReport the build identity of the Sumvin server this connection has reached. Useful for confirming the connection is live before trying anything else.
Try asking your agent: “Are you connected to Sumvin?”