wallet_status | Report holder DID/address/network + held VCs (client-supplied, or the local cache); optionally one token balance (token) or several in one call (tokens). Each balance carries balance (raw base units), decimals and display — the same amount in whole tokens with its symbol. Quote display; a raw count beside a ticker is wrong by orders of magnitude. When decimals is null, display is the raw base-unit count, not whole tokens: say the amount could not be converted. A token may be named by ticker or contract address, and a ZTP20 result also carries its contract address as tokenAddress — the value a policy needs, so it never has to be asked for | { heldCredentials?, token?, tokens? } | { holderDid, zetrixAddress, network, credentials, balances?, tokenBalance?, tokenBalances? } |
credential_preflight | Free. The first call for any credential — composes the quote, the balances and the spending cap into one answer, before a single application field is collected. Spends nothing, starts nothing. blockers lists every reason the wallet is not ready, at once; notChecked lists what preflight cannot know — agent-name availability is decided by myid at issuance, after payment, so a ready result is never a reservation. It also says when the wallet already holds a valid copy of the credential (alreadyHeld, with ready: false): it looks at the credentials the wallet has saved, locally and for free, before pricing anything, so the agent stops with "you already have one" instead of asking for an agent name. Buying another would replace it (one credential per template) and costs the fee; only when the user explicitly wants a replacement is it run again with replacing: true. An expired credential does not count, and a lookup that fails is reported in notChecked, never as "nothing is held". When a user asks for an AI Birthcert without saying Basic or Verified, every result carries a choice note: the agent checks both kinds, explains the difference, and asks which they prefer; if they want both, it issues them one after the other, Basic first. | { credential, agentName?, replacing? } | { credential, ready, fee?, balances, cap?, schema?, alreadyHeld?, unusedPayment?, blockers, notChecked, choice? } — unusedPayment: { agentName, linkOpen, note } (Verified only) means an earlier payment has not been used yet and the next link reuses it, so balance and spending limit do not gate and no fee is asked for |
prove_identity | Answer an x401 PROOF-REQUEST → return the PROOF-RESPONSE header to replay | { proofRequest, vc?, revealAttribute?, issuerKeys? } | { proofResponseHeader, verified, presentationId, credentialStatus } |
create_verification_qr | Create a link and a QR code that open this wallet's credential in the MyID wallet, for a human to verify the agent. Presents the credential to MBI — with no vc given, the Verified AI Birthcert if the wallet holds one, otherwise the Basic AI Birthcert, and if it holds neither it answers created: false and says to create one first. The link holds only the reference id, but that id grants access to whatever is revealed until it expires (5 minutes by default, up to 60), so by default it reveals only a standard minimal set (Verified: agentName, evidenceProvider, ownerVerified; Basic: agentUsername) — name other attributes with revealAttribute, and pass revealAll: true only when the user explicitly asks to reveal everything; show the link only to the human user. The QR code comes back as an image and as a PNG file (qrCodePath) that a chat channel such as WhatsApp can attach; a file is removed when the wallet starts and the next time a QR is made, once its link has expired. The file is on the wallet's own machine, so a client that runs the wallet remotely cannot read the path and gets the image block and the link instead. The agent is told never to send another image as the QR code, and to give the link and say so if it cannot attach one. When the credential has a saved pass design, the result also carries its path (vcPassImagePaths), so the agent can show both pictures, each captioned for what it is. A Basic credential does not mean the owner was verified, and the result says so. Needs MYID_VERIFY_LINK_TEMPLATE; without it the tool answers created: false before anything is created | { vc?, revealAttribute?, revealAll?, expiryMinutes? } | { created, link, referenceId, expiresAt, expiresInMinutes, revealed (the attribute paths, or "all"), credentialUsed, revealedByDefault, qrCodePngBase64 (sent as an image; absent with a qrError if it could not be drawn), message } or { created: false, reason } |
pay_and_fetch | Fetch a URL, auto-pay with x402 (self-pay via Wallet BE) on 402 | { url, method?, headers?, body? } | { status, body, paymentMade, amountPaid, amountPaidHuman, asset } |
subscribe_and_issue | Reuse a cached VC if still valid, else pay x402 → MBI issues → return the VC. Replacing a still-valid cached VC needs forceReissue: true and confirmReplaceExistingVc set to the exact vcId you were shown first — forceReissue alone only shows you the existing VC (issued: false), it never pays | { templateId, attributes, expirationDate?, dryRun?, forceReissue?, confirmReplaceExistingVc?, confirm? } (confirm is the quote from a needsConfirmation result, passed back unchanged, quoteId included (good for 10 minutes, only for that request, once); anything else, including true, returns { issued: false, needsConfirmation: true, quote, askUser, nextStep } and signs, pays and issues nothing; a confirmed call whose payment request differs from the quote in token, amount, payee or gas model is not paid either) | { issued, vcId, vc, txHash, fromCache?, alreadyHeld?, differsFromRequest?, schema?, originalPayment?, paymentAttempted?, recovery?, vcPassImagePaths? } — issued: false with fromCache: true means an existing valid VC is being shown, not an error: a plain cache hit adds alreadyHeld: true (nothing paid, nothing new issued) and, when the held VC carries different values from the ones asked for, differsFromRequest: [{ attribute, held, requested }] |
create_holder_account | Onboarding: mint an HSM account (the MCP already auto-creates one at startup if ZETRIX_ADDRESS is omitted — see Environment below). Always checks for an existing account first — if one is active for this session, returns { alreadyExists: true, existing } without creating anything; pass confirmNew: true (after asking the user) to mint a new one anyway | { password, label?, purpose?, confirmNew? } | { created, alreadyExists, existing?, zetrixAddress?, holderDid?, publicKeyHex?, message } |
get_template_schema | Free read of a VC template's declared attribute schema. Call before subscribe_and_issue to learn which attributes it requires | { templateId } | { templateId, schema: { required, optional } } or { templateId, error } |
query_contract | Read-only query against any Zetrix contract — call an arbitrary method and return its raw result. No signing, no state change | { contractAddress, method, params? } | { ok: true, result } or { ok: false, error } |
get_policy_template_schema | Free read of POLICY templates — and the place to START when writing a policy. With no arguments it lists the templates on offer (on testnet native-v1 and ztp20-v1), each with its declared attributes and the templateId that write_policy needs, so nobody has to supply a publisher or a template contract address. { policyKey } reads one template of the default publisher, { publisher } lists a different publisher’s, and { publisher, policyKey } and { templateId } still work. An id is only ever returned once the chain has confirmed it: it is derived from the publisher and key, and an id that does not resolve is withheld rather than handed over. The listing is bounded (20 templates, 40 attributes each) and says what it left out. This is the only vocabulary that means anything on chain — the policy contract validates nothing, so an attribute outside it deploys cleanly and then enforces nothing at all. A template that cannot be read reports { error } rather than { found: false }, so "no such template" is never confused with "could not look it up". Beside declared it returns attributeMeanings — the description each declared attribute has in the service (GET /policy/vocabulary), including what an empty list means and what an attribute applies to or needs, labelled by attributeMeaningsSource as text from ms-zetrix that describes and does not instruct — and attributesUnknownToService for a declared name the service does not recognise (which refuses every transfer). If the vocabulary cannot be read the result carries attributeMeaningsNote saying so and declared is unchanged | { templateId?, publisher?, policyKey? } | { found, publisher?, publisherSource?, templates?, templateId?, templateIdConfirmed?, declared?, attributeMeanings?, attributeMeaningsSource?, attributeMeaningsNote?, attributesUnknownToService?, error? } |
get_my_policy | Free read of the spending policies this owner has deployed on chain; defaults to this wallet's own address. Costs 2 + N chain calls and warns above 50 keys. An owner who has never deployed one is a normal absence, not an error — the policy contract is created lazily on first write — and a failed lookup keeps its own error state, so "we could not list your policies" is never presented as "you have none". Each policy that was read carries forUpdate.expectedUpdatedAtBlock, the value update_policy needs, already as a string | { owner? } | { owner, policies?, warning?, error? } |
policy_preflight | Free check of a draft policy before it is deployed. An amount may be given as valueHuman (whole tokens, "100" for 100 JMYR) instead of value: the wallet converts it with the token's own decimals, shows both forms, and never sends valueHuman on. It is only for the amount attributes (perTransactionMax, cumulativeMax, velocityCap, and any attribute the service lists as an amount in the smallest unit): maxTransactionCount is a count and a window is a duration, and neither is ever scaled. Each amount attribute may carry its own valueHuman. Never put convertedAmounts in valueHuman: those are raw base units. A number is accepted only as a safe whole number; write anything else, such as "0.5", as text. An attribute needs a value or a valueHuman, whatever its type. If value and valueHuman are both given they must agree, and amountUnit does not apply to a valueHuman. Two questions: is it well-formed (blockers lists every problem at once, so one round of fixes is enough — on a hostile draft with hundreds of faults the list is capped, and it says so on the last line), and — more important — does it MEAN what the user thinks (interpretation states in plain words what it actually does). Always show interpretation, including when ready is true: a valid policy can still mean something unintended — a spending cap with no window is a LIFETIME cap, not a monthly one. It also applies the write service’s scope rules, so a draft the service would refuse is refused here for free: assetScope must be exactly native or ztp20 (never a token symbol such as JMYR), a ztp20 policy needs a tokenAddress, and any amount or count cap needs an assetScope. A token symbol written where tokenAddress belongs is refused with the registered address to use, and a ztp20 draft with no tokenAddress names the registered ones. Every *Window must be a duration such as 7d, 12h or 30m (or ISO P7D) — week, a bare number or a value with spaces around it is refused, and interpretation states each window's period in words (1M is one minute, not one month) — and interpretation states what each amount means in whole tokens, because amounts are raw base units. A non-zero amount cap (perTransactionMax, cumulativeMax, velocityCap) under one whole token is refused unless amountUnit says what is meant: "whole" gives whole-token amounts ("1", "0.5") that the wallet converts by the token's decimals and returns in convertedAmounts, and "base" confirms a tiny raw value is intended. convertedAmounts is for showing the user — never send it back as the values; a "whole" draft whose every amount already looks raw is refused with both readings and the exact raw value for each. notChecked lists what could not be verified, including whether the policy would be enforced at all | { policyKey, attributes, validFromBlock?, validToBlock?, templateId?, publisher?, amountUnit? } | { policyKey, ready, declared?, blockers, interpretation, notChecked, convertedAmounts? } — declared is the template's own attribute names, present only when the template resolved; long results are bounded, and anything omitted is stated in notChecked rather than dropped silently |
check_policy_decision | Free — but NOT free of consequence. Ask whether a specific spend is permitted RIGHT NOW: the one policy question no chain read can answer, because a cap is measured against cumulative spend held off-chain. Three outcomes — permitted, refused, undetermined. undetermined is neither a refusal nor permission: it means nothing was evaluated (service unreachable, ledger stale, or none configured), and it is what every failure produces — no transport error, bad envelope or unknown verdict string can ever yield permitted. There is no step-up verdict; the decision service answers only allow or deny, so the wallet never reports that a human must approve a spend. A permitted answer reserves the owner’s budget for 15 minutes, with no way to release it early — so do not poll it, do not probe amounts (every allow along the way reserves again, and the owner’s next real payment can be refused by their own agent), and never retry automatically after a timeout: the call may have succeeded and reserved already. To find an amount that fits, read remaining from one answer and compute locally. requestKey is correlation only, not idempotency: repeating it does not deduplicate and each permitted answer reserves again. While the spend-ledger crawl is off, every decision answers undetermined / EVALUATION_UNAVAILABLE, which is correct behaviour rather than an outage. ignored is surfaced on a permitted answer too — it lists constraints the policy carries that the service could not enforce | { ownerAddress, asset, amount, policyKey?, recipientAddress?, method?, payTo?, paymentNonce?, requestKey? } | { outcome, summary, reasonCode?, policyKey?, enforced?, ignored?, remaining?, capacityReturnsAt?, reservationId?, notChecked } |
write_policy | Pays a real fee, and only with confirm: true (the user must have seen the interpretation and the price; without it the call returns the price and pays nothing). Deploy a spending policy on chain over x402. An amount may be given as valueHuman (whole tokens, "100" for 100 JMYR) instead of value: the wallet converts it with the token's own decimals, shows both forms, and never sends valueHuman on. It is only for the amount attributes (perTransactionMax, cumulativeMax, velocityCap, and any attribute the service lists as an amount in the smallest unit): maxTransactionCount is a count and a window is a duration, and neither is ever scaled. Each amount attribute may carry its own valueHuman. Never put convertedAmounts in valueHuman: those are raw base units. A number is accepted only as a safe whole number; write anything else, such as "0.5", as text. An attribute needs a value or a valueHuman, whatever its type. If value and valueHuman are both given they must agree, and amountUnit does not apply to a valueHuman. Three steps: a free pre-check, a payment that writes nothing, and a collect that finishes the write once the payment settles. Between the payment and the settlement a payment has been made and no policy exists — that window is normal, not a failure. On the sponsored path settling and submitted both mean a payment has been made: pass paymentReceipt to check_policy_write, never call this again. submitted carries a txHash and still is not a written policy — the block has not confirmed it. written is the only state where the policy exists. already_exists / refused come from the free pre-check, so nothing was paid; payment_refused says nothing either way about whether the fee was taken. receipt_void is the one state where paying again is right (payFresh). The fee goes through the same payment cap as every other paying tool, and the wallet never builds a blob, permit digest or canonical JSON — ms-zetrix signs with the owner’s own key. templateContractAddress is optional and best left out: the wallet uses the one Template contract it is configured for and refuses any other before any payment, so there is nothing for a user to supply. dryRun: true returns the price without paying — it runs every free check and stops at the quote (quoted): nothing is paid, collected or written to chain, and it never collects an already-paid write, because collecting signs and writes (it only keeps a local bookmark so check_policy_write can finish it). The quote also carries affordability — whether the wallet holds the quoted amount of the fee asset (plus some ZTX for gas, when the payer needs it) and whether the payment cap would refuse it, each shortfall named separately and a failed balance read reported as unknown, never as a yes. It does not estimate the network fee: a payment made in ZTX needs the amount plus that fee from one balance, so feeNotEstimated says when "affordable" means only "holds the amount". A quote is what the service asked for just now, not a promise the payment will be allowed: balances move and the cap is enforced again when paying. Who pays the gas is the user's choice (gasPayer): "sponsored" pays the fee in JMYR and the gas is covered (no ZTX needed), "self" costs no fee and only the network gas in ZTX. The wallet has no default for it: when the wallet can pay the gas itself, a call without gasPayer stops at needs_choice (nothing paid, whatever confirm says) with both options, what each costs and whether the wallet can pay it right now, so the user can decide; a value that is neither is refused before the service is contacted. Self-pay is on offer where the policy contracts are deployed (testnet today); elsewhere nothing changes and "self" is refused. A self-paid write is the owner's own createOrUpdatePolicy call on the Policy Registry, built here and signed through Wallet BE, and the policy service is never contacted. The wallet reads the chain first (a policy that already exists, or one that has changed since you read it, is refused for free), checks the ZTX balance covers the estimated gas plus a reserve (a balance or estimate it cannot read is not a yes), and reports written only when the chain then holds exactly what was sent: the same attributes, template and validity window, and for an update updatedAtBlock moved. Otherwise it reports submitted with the txHash: do not send it again, and get_my_policy shows when it lands. Wallet BE refusing to sign is a decision (policyDenied); its check failing is transient (policyCheckUnavailable). Nothing is sent when the node's own simulation rejects the call. Without confirm: true it quotes the gas and sends nothing. A self-paid send also needs maxGasRaw, the requiredRaw of the self option the user was shown (the most gas they agreed to): without it, or when the gas now costs more than it, nothing is signed and the refusal gives the current figure to show and what to call with, so the fee limit signed can never exceed what the user saw. A self-paid send is remembered until its outcome is settled: the transaction carries an expiry (60 ledgers past the current one), a small note (policy key, nonce, transaction hash, expiry) is written before it is submitted, and a later write or update for the same key is refused, with nothing sent, while the transaction could still land, and so is a sponsored write, the collect of an already-paid write and remove_policy (the self-paid transaction would replace the whole policy when it lands, so nothing else may write or remove in the meantime; nothing is paid or removed). The note holds the owner, policy key, operation, nonce, transaction hash, expiry and send time (no secret), is kept per network, and is removed only by its own transaction. Every confirmed write, collect or removal for a key in a process waits for the one in front of it for up to 15 seconds, and then refuses with nothing sent, paid, collected or removed, so a call never acts after its client could have given up. The note is cleared when the transaction is found on chain (landed or failed) or the ledger has passed its expiry, so an outcome that never arrived is settled in bounded time. A send is refused if the ledger number cannot be read or the note cannot be written, and a note that exists but cannot be read (unreadable, empty or damaged, as a crash can leave it) is never read as "no note": the call stops and names the file, which a person can delete once 60 ledgers (about 10 minutes) have passed since it was last changed, or once get_my_policy shows the write. A note is deleted only after at least 15 minutes and with the chain producing ledgers. With gasPayer "self" there is no paymentReceipt and check_policy_write does not apply: submitted means the network gas is spent (do not send it again; get_my_policy shows when it lands, and quote the txHash if it never does), unknown means it may be on chain (do not send it again; quote the nonce), and write_failed means the transaction was included and rejected (the gas is spent and nothing was written). The gas is spent even when the write fails on chain. The wallet signs with the fee ceiling it checked the balance against, and refuses (nothing signed) if the node's fresh estimate is above it. A pending paid write for the same policyKey blocks a self-paid one (finish it with check_policy_write first), and so does an attribute vocabulary that could not be read or that no source is configured for (the vocabulary comes from the policy service, so self-pay needs it), because a self-paid write has no service to catch what it would have. A receipt the service said failed does not hold a self-paid write back; one with an unresolved outcome does. When neither way of paying is available the answer is unavailable and names both reasons. A list attribute is capped at 500 entries and a policy at 64 attributes. A wallet that already has a policy can self-pay too: Wallet BE signs the owner's own Registry call. A Wallet BE older than that refuses it (UNSUPPORTED_OPERATION, a decision made before any policy is consulted), which is reported as final, not about the policy's limits, with no invitation to retry. A self-paid update is a whole-policy replacement that the contract does not compare with what was there, so another write by the same owner landing in the few seconds between the wallet's last chain read and the block that includes the transaction is overwritten (the wallet still reports written because its own content is there and updatedAtBlock moved). A self-paid write has not yet been run end to end against a live chain. | { policyKey, attributes, templateId, templateContractAddress?, validFromBlock?, validToBlock?, requestKey?, pollBudgetMs?, amountUnit?, dryRun?, confirm?, gasPayer?, maxGasRaw? } | { state, message, paymentReceipt?, policyKey?, txHash?, paid?, payFresh?, quote?, affordability?, gasOptions?, needsConfirmation?, policyDenied?, policyCheckUnavailable?, upstream? } |
update_policy | Pays a real fee, and only with confirm: true. Replace a deployed policy's attributes and validity window over x402. attributes is the full replacement set, not a patch. An amount may be given as valueHuman (whole tokens, "100" for 100 JMYR) instead of value: the wallet converts it with the token's own decimals, shows both forms, and never sends valueHuman on. It is only for the amount attributes (perTransactionMax, cumulativeMax, velocityCap, and any attribute the service lists as an amount in the smallest unit): maxTransactionCount is a count and a window is a duration, and neither is ever scaled. Each amount attribute may carry its own valueHuman. Never put convertedAmounts in valueHuman: those are raw base units. A number is accepted only as a safe whole number; write anything else, such as "0.5", as text. An attribute needs a value or a valueHuman, whatever its type. If value and valueHuman are both given they must agree, and amountUnit does not apply to a valueHuman. Read the policy first with get_my_policy and pass its forUpdate.expectedUpdatedAtBlock (a string): if the policy has changed since, the update is refused for free (modified). The policy keeps the template it already references — pass none — and its validity window is kept unless validFromBlock / validToBlock are given. The same three steps, states and dryRun as write_policy; check_policy_write finishes a paid update from its receipt. Free refusals, each saying nothing was paid: not_found, modified, template_unavailable, refused. written is the only state that means the policy was updated; submitted is not (the block has not confirmed it); On the sponsored path write_failed means the update was not applied, the policy is unchanged and a payment may have been taken. The fee goes through the same payment cap as every other paying tool. Who pays the gas is the user's choice (gasPayer): "sponsored" pays the fee in JMYR and the gas is covered (no ZTX needed), "self" costs no fee and only the network gas in ZTX. The wallet has no default for it: when the wallet can pay the gas itself, a call without gasPayer stops at needs_choice (nothing paid, whatever confirm says) with both options, what each costs and whether the wallet can pay it right now, so the user can decide; a value that is neither is refused before the service is contacted. Self-pay is on offer where the policy contracts are deployed (testnet today); elsewhere nothing changes and "self" is refused. A self-paid write is the owner's own createOrUpdatePolicy call on the Policy Registry, built here and signed through Wallet BE, and the policy service is never contacted. The wallet reads the chain first (a policy that already exists, or one that has changed since you read it, is refused for free), checks the ZTX balance covers the estimated gas plus a reserve (a balance or estimate it cannot read is not a yes), and reports written only when the chain then holds exactly what was sent: the same attributes, template and validity window, and for an update updatedAtBlock moved. Otherwise it reports submitted with the txHash: do not send it again, and get_my_policy shows when it lands. Wallet BE refusing to sign is a decision (policyDenied); its check failing is transient (policyCheckUnavailable). Nothing is sent when the node's own simulation rejects the call. Without confirm: true it quotes the gas and sends nothing. A self-paid send also needs maxGasRaw, the requiredRaw of the self option the user was shown (the most gas they agreed to): without it, or when the gas now costs more than it, nothing is signed and the refusal gives the current figure to show and what to call with, so the fee limit signed can never exceed what the user saw. A self-paid send is remembered until its outcome is settled: the transaction carries an expiry (60 ledgers past the current one), a small note (policy key, nonce, transaction hash, expiry) is written before it is submitted, and a later write or update for the same key is refused, with nothing sent, while the transaction could still land, and so is a sponsored write, the collect of an already-paid write and remove_policy (the self-paid transaction would replace the whole policy when it lands, so nothing else may write or remove in the meantime; nothing is paid or removed). The note holds the owner, policy key, operation, nonce, transaction hash, expiry and send time (no secret), is kept per network, and is removed only by its own transaction. Every confirmed write, collect or removal for a key in a process waits for the one in front of it for up to 15 seconds, and then refuses with nothing sent, paid, collected or removed, so a call never acts after its client could have given up. The note is cleared when the transaction is found on chain (landed or failed) or the ledger has passed its expiry, so an outcome that never arrived is settled in bounded time. A send is refused if the ledger number cannot be read or the note cannot be written, and a note that exists but cannot be read (unreadable, empty or damaged, as a crash can leave it) is never read as "no note": the call stops and names the file, which a person can delete once 60 ledgers (about 10 minutes) have passed since it was last changed, or once get_my_policy shows the write. A note is deleted only after at least 15 minutes and with the chain producing ledgers. With gasPayer "self" there is no paymentReceipt and check_policy_write does not apply: submitted means the network gas is spent (do not send it again; get_my_policy shows when it lands, and quote the txHash if it never does), unknown means it may be on chain (do not send it again; quote the nonce), and write_failed means the transaction was included and rejected (the gas is spent and nothing was written). The gas is spent even when the write fails on chain. The wallet signs with the fee ceiling it checked the balance against, and refuses (nothing signed) if the node's fresh estimate is above it. A pending paid write for the same policyKey blocks a self-paid one (finish it with check_policy_write first), and so does an attribute vocabulary that could not be read or that no source is configured for (the vocabulary comes from the policy service, so self-pay needs it), because a self-paid write has no service to catch what it would have. A receipt the service said failed does not hold a self-paid write back; one with an unresolved outcome does. When neither way of paying is available the answer is unavailable and names both reasons. A list attribute is capped at 500 entries and a policy at 64 attributes. A wallet that already has a policy can self-pay too: Wallet BE signs the owner's own Registry call. A Wallet BE older than that refuses it (UNSUPPORTED_OPERATION, a decision made before any policy is consulted), which is reported as final, not about the policy's limits, with no invitation to retry. A self-paid update is a whole-policy replacement that the contract does not compare with what was there, so another write by the same owner landing in the few seconds between the wallet's last chain read and the block that includes the transaction is overwritten (the wallet still reports written because its own content is there and updatedAtBlock moved). A self-paid write has not yet been run end to end against a live chain. | { policyKey, attributes, expectedUpdatedAtBlock, validFromBlock?, validToBlock?, amountUnit?, confirm?, dryRun?, gasPayer?, maxGasRaw?, pollBudgetMs? } | { state, message, paymentReceipt?, policyKey?, txHash?, paid?, payFresh?, quote?, affordability?, interpretation?, gasOptions?, needsConfirmation?, policyDenied?, policyCheckUnavailable?, upstream? } |
remove_policy | Free, but it lifts every limit the policy set — Wallet BE then signs spends of that asset without any limit — so nothing is sent without confirm: true. Without it you get needs_confirmation with what the policy currently limits. removed is the only state that means the policy is gone, and it is reported only when a chain read no longer holds it; submitted is a removal on its way, not a removed policy. Repeating the call never submits a second removal. not_found means there was nothing to remove (or it is already gone); in_progress means a paid update has not been collected yet (check_policy_write first); refused naming a self-paid transaction means an earlier self-paid update may still land and would bring the old policy back, so nothing was removed (wait until the ledger it names, or read the policy with get_my_policy) | { policyKey, confirm?, pollBudgetMs? } | { state, message, policyKey?, txHash?, currentAttributes? } |
check_policy_write | Free — never pays, on any path. Finish a policy write or update that has already been paid for, from its paymentReceipt (or the most recent pending one when omitted). This is the right answer to “did my policy get created?”; calling write_policy again is not. A receipt this wallet does not recognise does not mean the write failed — the service completes a paid write on its own, and asking to write the same policyKey again reports the truth for free before any payment. When a collect ends with an error that says nothing about the write (a gateway timeout, a 5xx), the wallet reads the chain itself (up to 45 seconds, less when the poll has already used part of its budget; each read is cut off at 10 seconds) and reports written only when the chain holds exactly the attributes that were submitted, under the same template (for an update, with updatedAtBlock moved). That covers every answer the wallet cannot read: a 5xx, a gateway page, the service's own "unknown", and any other status it does not recognise (a 4xx included); the service's own "the chain rejected it" is never second-guessed. check_policy_write looks at the chain first for a receipt that still carries what to verify, so a write that already landed costs no collect. A receipt stops being verified against the chain once the service has said its write failed, or once a newer paid write for the same policyKey has been made, and a receipt bought by another owner is never checked against this owner's policy. An error answer is returned apart in upstream: { status, detail } (control characters replaced, at most 200 characters) | { paymentReceipt?, pollBudgetMs? } | { state, message, paymentReceipt?, policyKey?, txHash?, paid?, payFresh?, upstream? } |
request_ai_birthcert_verification | Start a Verified AI Birthcert issuance session with myid (MyDigital ID owner verification) — distinct from subscribe_and_issue's self-declared Basic AI Birthcert. The price comes from the issuing service's quote, which creates nothing: when it says no payment is needed the session starts directly, with no price to confirm and paidThisCall false. Optional gasPayer ("sponsored" | "self") overrides the gas payer for this call only — precedence is per-call gasPayer > GAS_PREFERENCE config > sponsored hardcoded default. If a sponsored option is refused before any money moved, the wallet does not switch to paying gas itself on its own: it returns needsConfirmation with the self-pay price (its own token and amount, plus ZTX gas) to ask the user about, and pays it only once that quote is confirmed; it never offers a switch once payment is merely pending/indeterminate. dryRun: true quotes instead of paying: it asks the issuing service's quote, pays nothing, creates no session for the user, and returns { quote } — the asset, the amount, which side pays gas and, when the service says so, paymentRequired (false means it is not charging and the amount is only indicative). An issuing service without a quote is asked the old way, with a session request that answers 402 and carries a throwaway name, never the user's (a service that is not charging then makes a session nobody receives). Checks for an existing Verified AI Birthcert VC before paying: if this holder already has a still-valid one (found in the local cache, or resolved from a previously-issued session the cache never saw), nothing is paid and no session is started — you get { existingVerifiedVc: { vcId, validUntil }, message } instead; call again with confirmReplaceExistingVc set to exactly that vcId to replace it anyway. An existing VC that has already expired needs no confirmReplaceExistingVc (the payment still stops at the price like any other), and a result that went ahead carries replacedExpiredVc: { vcId, validUntil } naming the one it replaced. It can also refuse with { error } specifically because an already-issued credential exists but could not be confirmed as valid or expired — nothing is paid on that path either; relay error as given, which names the concrete next step | { agentName, agentPurpose?, evidenceAssuranceLevel?, ownerType?, ownerVerified?, gasPayer?, dryRun?, discardStuckReceiptAndPayFresh?, confirmReplaceExistingVc?, confirm? } (confirm is the quote from a needsConfirmation result, passed back unchanged, quoteId included (good for 10 minutes, only for that request, once); anything else, including true, returns { needsConfirmation: true, paidThisCall: false, quote, askUser, nextStep, message } and pays nothing; a confirmed call whose payment request differs from the quote in token, amount, payee or gas model is not paid either, and the quote's gasModel decides which option is paid; a call that pays nothing needs no confirm). Results carry nextStep (one of ask_user_to_confirm_payment, show_link_and_wait, wait_then_check, ask_user_whether_to_replace, tell_user_already_held, show_credential, collect_details, confirm_kind_then_collect_details, resolve_blockers, follow_message) and, when there is a question to ask, askUser |
check_ai_birthcert_verification | Free (never pays). Poll the most recently requested Verified AI Birthcert session; on status: "issued", also fetches, verifies, and caches the credential. While the session is still open it replays the stored verificationUrl alongside SSIVC's live expiresAt and the wallet's own expiresIn / expiresInSeconds (time left, worked out from the wallet clock, never from the agent's) — SSIVC issues the link only once, at creation, so this store is the only place it survives. That makes "where is my link?" answerable without touching the paid tool. No link is returned once status is "issued": the link is spent. If a prior payment is still clearing this tool advances it — it replays the saved receipt (never a new payment) and returns the live session once it settles, so "check back in a few minutes" genuinely progresses the flow | (none) | `{ status: "pending" |
clear_stuck_payment_receipt | Free, last resort, destructive. Discard a stuck Verified AI Birthcert payment receipt the wallet is holding and refusing to pay past — the supported replacement for deleting <stateDir>/ssivc-session.json by hand, which a hosted subscriber cannot do. Two steps by construction: with no argument it clears nothing and returns the receipt id plus a warning; clearing requires echoing that exact id back as confirmReceiptId, and a mismatch clears nothing. A receipt younger than SETTLEMENT_STUCK_AFTER_MS (24h by default) is refused on both steps. If the settlement completed in between — which is what happens when you follow the advice to call check_ai_birthcert_verification first — the receipt now belongs to a live, paid-for session, and the id alone no longer clears it: the tool hands back sessionId and verificationUrl instead, and only confirmDiscardLiveSession: true will discard them. The discarded payment is unrecoverable | { confirmReceiptId?, confirmDiscardLiveSession? } | { cleared, paymentReceipt?, requiresConfirmation?, sessionId?, verificationUrl?, message?, error? } |
transfer_token | Moves real funds, irreversible. Send native ZTX or any ZTP20 token to an address. token takes "ZTX", a registered symbol (no contract address needed) or a raw ZTP20 address; an unregistered symbol returns needsTokenAddress: true and signs nothing. Give amountHuman or amount — if both, they must agree, which is the cheapest way to catch a 1-vs-1000000 error. Nothing is signed without confirm: true, and the wallet never infers it. outcomeUnknown: true means the transaction may already be on chain — do not retry, check the reported nonce. policyDenied: true means the spending policy refused it (Wallet BE errorCode 1000033): a decision, not a failure, so retrying will not help. policyCheckUnavailable: true means Wallet BE could not complete the policy check (errorCode 1000034): nothing was signed or sent, it is transient, and trying again shortly is right | { token, to, amountHuman?, amount?, confirm?, dryRun? } | { sent, txHash?, nonce, token, asset, amount, amountHuman, decimals, fee, needsConfirmation?, needsTokenAddress?, outcomeUnknown?, policyDenied?, policyCheckUnavailable? } |