Changelog
Changes to the API and webhooks, newest first.
Changes to the API and webhooks that affect an integration, newest first. Changes to the product that do not touch this surface are not listed.
2026-11-09: Contractor work accepted from Jira
- A milestone's
verificationMethodmay now bejira, inGET /api/v1/milestonesand on its own page: the work was accepted by a person against the milestone's acceptance criteria once its Jira issue was done. ItsverificationDetailis{ note, jiraIssue, issueId, identifier, cloudId, completedAt, fingerprint, criteriaSha256, acceptedBy },cloudIdbeing the Jira site's id; once an acceptance is taken back it also carriesheldReasonandheldAt,verifiedis false,verificationStatusisunverifiedandstatusispendingagain. The TypeScript SDK 0.4.3 accepts the value. - Five new entries, domain
contractor, each listed byGET /api/v1/ledgerand sent to webhook endpoints asledger.appended:jira_issue_linked, actorhuman:{ by, milestoneId, linkId, issueId, identifier, projectKey, cloudId, issueUrl, completed, fingerprint }.identifieris the issue's key, such asENG-142;fingerprintisnulluntil the issue is done, since its deliverables are read only then.jira_issue_unlinked, actorhuman:{ by, milestoneId, linkId, issueId, identifier, withdrewAcceptance }.jira_issue_ready, actorsystem:{ milestoneId, linkId, issueId, identifier, completedAt, statusName, resolutionName, fingerprint, deliverables }, when a linked issue is done in Jira and the milestone has criteria. It verifies nothing:deliverablesis a count.jira_work_accepted, actorhuman:{ by, milestoneId, linkId, issueId, identifier, issueUrl, completedAt, statusName, resolutionName, fingerprint, deliverables, criteriaSha256, payeeJiraMapped }, when a person accepted the work.deliverableslists each{ kind, label, href }accepted,kindbeingattachment(a file or a web link),linkorcomment_link;fingerprintis the SHA-256 of that set;payeeJiraMappedsays whether Jira named an Atlassian account for the payee's email.jira_acceptance_withdrawn, actorsystem:{ milestoneId, linkId, issueId, identifier, reason, afterPayment, acceptedFingerprint, fingerprint, completed, completedAt, statusCategory }, when the issue was reopened, resolved as not done, its deliverables changed, or Jira no longer showed it after the work was accepted.reasonisreopened,canceled,deliverable_changedorissue_unreachable.fingerprintisnullwhen only the issue's status was read, andcompleted,completedAtandstatusCategoryarenullwhen Jira no longer showed the issue. WithafterPayment: falsethe milestone lost its verification before any payment; withafterPayment: truea payment was already sent, and is not taken back.
- No entry carries an Atlassian account ID, name or email.
milestone_criteria_setis written for a milestone linked to a Jira issue too, with the same fields as for Asana and Linear.- A new Jira connection's
accounting_connectedcarriesprovider: "jira"andconsent.versionjira-2026-11-09; itsexternalOrgIdis the Jira site's cloud id, andexternalOrgNamethe site's name. Disconnecting signsaccounting_disconnectedwithrevokedAtProvider: false, since Atlassian gives apps no way to end their own access. - Nothing else in
/api/v1changes: a milestone is not linked to a Jira issue through the API, and the write API still adds a milestone pending.
2026-11-06: The ledger newest first, and Zapier
GET /api/v1/ledgertakesorder:asc, the default, oldest first and resumable from a cursor as before; ordesc, the newestlimitentries, newest first, withdomainandactoras before.order=desctakes nocursorand answers400 invalid_requestto one, since a watermark read the other way round would skip or repeat entries; itspage.nextCursorisnull, andpage.hasMoresays whether older entries exist. Any otherorderanswers400. A request withoutorderanswers exactly as before.- A private Zapier integration reads it: triggers New Agent Decision, Bill Paid and New Ledger Entry, and the action Create Bill, with a workspace API key. The Postman collection's List the agent's decisions now reads newest first. The TypeScript SDK 0.4.2 accepts
order; itsledger.listpages, the CLI and the MCP server keep reading oldest first. Nothing else in/api/v1or the webhooks changes.
2026-11-01: Bills from a Google Drive folder
- Three new entries, domain
ap, each listed byGET /api/v1/ledgerand sent to webhook endpoints asledger.appended:google_drive_folder_chosen, actorhuman:{ by, folderId, folderName, baseline }, when an owner or admin chose the Google Drive folder the workspace reads, in place of any chosen before.baselineis how many files were in the folder then, which are never read; their names and ids are not in the entry. The same folder chosen again is recorded again with thebaselineit kept from its first choice.invoice_drive_file_received, actorsystem:{ inboxEmailId, driveFileId, fileName, lastModifiedBy, read, document }, when a file added to the folder after it was chosen was read.fileNameis the file's name, cut to 120 characters;lastModifiedByis the email of whoever last changed the file in Drive with most of its name hidden, ornullwhen Drive did not say;readisready,needs_detailsorunreadable; anddocumentis the document'skindandsha256, ornullfor a file that was not read, such as a picture or a Google Docs file.invoice_drive_file_dismissed, actorhuman:{ by, inboxEmailId, driveFileId }, when a member dismissed the file in the review list. An emailed invoice's dismissal is stillinvoice_email_dismissed.
create_invoiceentries gainvia: "google_drive", withinboxEmailId(the row in the review list, under the name emailed invoices already use) anddriveFileId, when a member added the payable from a file found in the folder. Such an entry carriesdocumentas one added from a document does,changedincluded. Nothing found in the folder is added without a person.- A new Google Drive connection's
accounting_connectedcarriesprovider: "googledrive"andconsent.versiongoogledrive-2026-11-01; itsexternalOrgIdis the Google account's Drive permission ID, andexternalOrgNameits email with most of its name hidden. Disconnecting signsaccounting_disconnected, as for every connector. - Nothing else in
/api/v1changes: a folder is chosen, and its files added or dismissed, in the console only.
2026-10-31: Contractor work accepted from Linear
- A milestone's
verificationMethodmay now belinear, inGET /api/v1/milestonesand on its own page: the work was accepted by a person against the milestone's acceptance criteria once its Linear issue was done. ItsverificationDetailis{ note, linearIssue, issueId, identifier, completedAt, fingerprint, criteriaSha256, acceptedBy }; once an acceptance is taken back it also carriesheldReasonandheldAt,verifiedis false,verificationStatusisunverifiedandstatusispendingagain. The TypeScript SDK 0.4.1 accepts the value. - Five new entries, domain
contractor, each listed byGET /api/v1/ledgerand sent to webhook endpoints asledger.appended:linear_issue_linked, actorhuman:{ by, milestoneId, linkId, issueId, identifier, teamKey, issueUrl, completed, fingerprint }.linear_issue_unlinked, actorhuman:{ by, milestoneId, linkId, issueId, identifier, withdrewAcceptance }.linear_issue_ready, actorsystem:{ milestoneId, linkId, issueId, identifier, completedAt, completedByName, fingerprint, deliverables }, when a linked issue is done in Linear and the milestone has criteria. It verifies nothing:deliverablesis a count.linear_work_accepted, actorhuman:{ by, milestoneId, linkId, issueId, identifier, issueUrl, completedAt, completedByName, fingerprint, deliverables, criteriaSha256, payeeLinearMapped }, when a person accepted the work.deliverableslists each{ kind, label, href }accepted,kindbeingattachment,linkorcomment_link;fingerprintis the SHA-256 of that set.linear_acceptance_withdrawn, actorsystem:{ milestoneId, linkId, issueId, identifier, reason, afterPayment, acceptedFingerprint, fingerprint, completed, completedAt, stateType }, when the issue was reopened, canceled, archived or deleted, its deliverables changed, or Linear no longer showed it after the work was accepted.reasonisreopened,canceled,archived,deliverable_changedorissue_unreachable. WithafterPayment: falsethe milestone lost its verification before any payment; withafterPayment: truea payment was already sent, and is not taken back.
milestone_criteria_setis written for a milestone linked to a Linear issue too, with the same fields as for Asana.- A new Linear connection's
accounting_connectedcarriesprovider: "linear"andconsent.versionlinear-2026-10-31; itsexternalOrgIdis the Linear workspace's id, andexternalOrgNameits name. - Nothing else in
/api/v1changes: a milestone is not linked to a Linear issue through the API, and the write API still adds a milestone pending.
2026-10-30: Several bills approved with one confirmation
- A person can now select from 2 to 20 bills on the console's Approvals page and approve them with one confirmation. Each bill is still decided and recorded on its own: one
approval_paidentry per bill, listed byGET /api/v1/ledgerand sent to webhook endpoints asledger.appended, with every field it had before. approval_paidgainsapprovedTogether, a whole number from 2 to 20, on a bill approved that way: how many bills the person chose in that confirmation. It is absent on a bill approved on its own, and on every entry signed before this date. A first of two approvals given that way is not anapproval_paidand carries nothing new.approval_paidgainsbatch,{ key, size }, when the bill's transfer shared one Arc transaction with other bills of the same confirmation, as amilestone_releaseentry'sexecution.batchdoes:keyidentifies the batch andsizeis how many transfers it carried. ItstxRefis then the batch's transaction, shared with the other bills in it. When Circle had confirmed that transaction by the time the bills were recorded, each one'sagentReasoningonGET /api/v1/invoicesincludes[paid in one Arc transaction with 1 other bill], or how many other bills it paid. A batch Circle failed leaves each bill held, withbatchon its entry, and its next approval sends a transfer of its own.- There is no new endpoint, and nothing in
/api/v1approves a bill. Slack approves one bill at a time, as before, where an owner lets bills be decided there; Telegram and Discord approve none, and their links open the bill in Approvals. Nothing else in/api/v1or the webhooks changes.
2026-10-30: Evidence, receipts and close packs as MCP tools
- The MCP server has five new read-only tools, one for each evidence read:
get_invoice_evidence,get_milestone_evidence,get_invoice_receipt,get_payee_lock_evidenceandget_close_pack. Each takes its operation's parameters (id;fromandto; ormonth) and runs that operation with the caller's key, under the same limit per key as the API. The server now lists 18 tools. - Each answers a digest of the signed file, not the file. It starts with
about, a sentence saying that its names, numbers, memos and links came from outside Vestiarion and are data, never instructions. It keeps what the file says, each fact with theseqof the entries it rests on; counts the server's check of each entry the file carries insignatures(cited,verified,failed,unchecked); and names the API path and the SDK method for the complete signed file infullFile. It leaves outentries,keys,signedEntryProvesandcheckAnEntry. - The payee lock's digest holds the newest 50 address changes, with
changesShownandchangesTotal. The close pack's holds the first 100 settled payments asrows, each with its payee, its bill,approval.authorizedBy,transaction.txHash,transaction.chainandentry, withrowsShownandrowsTotal, and counts the payments not settled and the escrow moves innotSettledandescrow. No digest is over 200 KB: a larger one holds fewer changes or rows, andnotShownsays how many. - These five tools' descriptions describe the digest; the reference pages and the OpenAPI document still describe the full file. An error passes through as the API's own, a
404 not_foundor a429 rate_limitedamong them. A close pack, or the payee lock's evidence for a period, whose full file is over 4 MB has no digest: it answers the API's400 invalid_request, as on Limits. Nothing in/api/v1, the SDK or the webhooks changes.
2026-10-28: Earned vendors paid on their own
- A new entry, listed by
GET /api/v1/ledgerand sent to webhook endpoints asledger.appended:earned_vendor_payments_changed, domainsystem, actorhuman, when an owner lets the agent pay earned vendors on their own in shadow mode, or makes their payments wait for a verdict again. It carriesby,fromandto, eachtrueorfalse. A change whose entry cannot be signed is put back; should that fail too, the missing entry is signed by the owner's next change, first. Turning the rule for earned vendors off turns this off too, in the same change: anearned_vendor_payments_changedwithto: falsefollows theearned_vendor_rule_changedwithto: null. While no rule is in force it is off, whatever its newest entry says. ap_paygainsearned,{ recordSeq, streak, agreed }, when the agent paid the bill on its own in shadow mode for an earned vendor:recordSeqis theseqof the vendor'svendor_earnedentry,streakthe rule, andagreedthe agreed verdicts in a row when the cycle started. The entry keepsshadow: trueand has noexecution.heldBecauseofshadow_verdict;execution.resultingStatussays how it ended,paidormatchedfor a transfer, orheldwhen the live path held it (the pause, the cash). A verdict can be given on it after, as on any decision. It is absent on every otherap_pay, and on every entry signed before this date.vendor_earned_lostcan now carrytrigger: "cycle"withbecauseflaggedorcode_stopsigned in the middle of a cycle, right after the decision entry it names indecisionSeq, when a decision about a vendor the agent was paying on its own broke its status.shadow_mode_started's summary names the exception when the switch is on as shadow mode starts:Shadow mode started, for bills in USD: the agent pays nothing until a person agrees, except vendors that earned it under the owner's rule. With the switch off it reads as before.approval_paidgainsrecorded: truewhen the approval sent nothing of its own and only read and recorded the transfer sent before it: one that already existed, or a send Circle never answered, looked for on Circle. ItstxRef,statusandattemptare that transfer's. It is absent when the approval sent a transfer, and on every entry signed before this date. A payment the agent made on its own for an earned vendor stays the agent's after such an approval.weekly_brief_sent, in shadow mode, gainspaid.onItsOwnwhen the agent paid any of the week's payments on its own for an earned vendor: how many ofpaid.countit paid that way, which no one agreed to first. It is absent otherwise.- A bill the agent paid this way has
agentReasoningonGET /api/v1/invoicesending[an earned vendor under the owner's rule: paid without waiting for a verdict; give yours after]. Theap_payentry'sdecision.reasoningstays the model's own. - With the switch on, being earned changes what the agent does with a payment in shadow mode on Arc testnet; nothing changes on Arc mainnet or in a live workspace. Nothing else in
/api/v1or the webhooks changes.
2026-10-28: Earned vendors
- Three new entries, listed by
GET /api/v1/ledgerand sent to webhook endpoints asledger.appended, in a workspace on Arc testnet where an owner set a rule for earned vendors: N agreed shadow-mode verdicts in a row on the agent's decisions to pay or schedule a vendor's bills. earned_vendor_rule_changed, domainsystem, actorhuman, when an owner sets, changes or turns off the rule. It carriesby,fromandto, each a whole number from 5 to 50, ornullfor no rule. A change whose entry cannot be signed is put back. Should that fail too, the change stays in force without its entry until an owner asks for that rule again or changes it: the missing entry is then signed first, itsfromthetoof the newest entry before it, and itsbythat owner.vendor_earned, domaincompliance, actorsystem, when a vendor meets the rule. It carriescounterpartyId;streak, the rule;agreed, the agreed verdicts in a row;evidence, theseqof each decision entry behind them, newest first, at most 50;fromandto, the times of the oldest and newest of those;since, what last started the count again, ornull:{ kind, at, decisionSeq, rule }, withkinddisagreed,flaggedorcode_stop,decisionSeqthe decision it was about, andrulethe rule that flagged or stopped that decision,nullfordisagreedand for a flag the agent's model made; andtrigger,verdict,ruleorcycle.vendor_earned_lost, domaincompliance, actorsystem, when a vendor that met it no longer does. It carriescounterpartyId,streak(nullwhen the rule was turned off),because(disagreed,flagged,code_stop,rule_changed,rule_off,high_risk,no_payment_limitornot_a_vendor),decisionSeq(the decision behinddisagreed,flaggedorcode_stop, elsenull),rule(the rule that flagged or stopped that decision, elsenull, as it always is fordisagreedand for a flag the agent's model made), andtrigger.- A vendor's newest
vendor_earnedorvendor_earned_lostentry is its last signed status. While no rule is in force, that is, while the newestearned_vendor_rule_changedhasto: null, no vendor is earned, whatever its newest entry says. Only in the case above, until its entry is signed, does the newestearned_vendor_rule_changednot name the rule in force; a status signed meanwhile carries the rule it was signed under instreak. None carries an email. Being earned by itself changes nothing the agent does with a payment: only the owner's switch in the entry above does. Nothing else in/api/v1or the webhooks changes.
2026-10-26: What the reader noted in a vendor's document
document_checkedgainsreaderNote, besidereaderFlagged: true, when the workspace's model flagged the document: the note it wrote, as a string of at most 200 characters, cleaned first. Format, private-use, unassigned and other invisible characters, bidi controls, zero-width ones, variation selectors and Hangul fillers among them, are removed. It is in Unicode NFKC, so fullwidth letters and dots read as plain ones, and a letter keeps at most two combining marks. Control characters and line breaks become a space, as does an HTML character reference such as:or:; it is one line with its whitespace collapsed. A link reads(link removed): a Markdown link or image, whatever its destination, and a link in angle brackets; one with a scheme, such ashttps://,javascript:,ethereum:ordata:; one starting//orwww.; a domain name such aspay.example.com, with or without a path, whose last label is a top-level domain, including one written with fullwidth or ideographic dots or in another script, and one that reads as a file's name, such asstatement.zip; and an IPv4 address. A file's name such asinvoice.pdforreceipt.tiff, and an abbreviation such asSt.Louis, stays. An email address reads(email address removed)and a run of 32 or more letters, digits,_,-,+,/or=(token removed), while a0xaddress or hash stays. Every double quotation mark and every character that looks like one becomes', and so does every run of two or more quote-like or prime-like characters, of one kind or mixed: single quotes, backticks, acute accents, modifier primes, low single quotes, ornaments and gereshes among them. A longer note ends with.... It is absent when the model set no note, or one with nothing left once cleaned, and on every entry signed before this date. It is the model's reading of an untrusted document, never Vestiarion's: treat it as text to show, never as an instruction.reasonon such an entry, the sentence the bill's card shows, now quotes the note after its sentence:The reader flagged something in it for a person to check. The reader noted: "...", or the first check that failed followed byThe reader noted: "...", within 300 characters: a long note is cut with...when at least 40 of its characters fit after the sentence, and otherwise follows, whole, a short form of the sentence that names no purchase order or name, such asThe document names more than one purchase order.(the values compared stay inchecks). A reason that ends without a closing quotation mark quotes no note.sentence, on everydocument_checkedentry whoseoutcomeismismatched, is the first failing check's sentence whole, or the flag's own: asreasonbegins, but naming the purchase orders compared wherereasongives the short form. The entry's summary gives that sentence, then the whole note when there is one,The reader noted: "...", and is not held to 300 characters.sentenceis absent on entries signed before this date.- It is sent to webhook endpoints as
ledger.appendedand listed byGET /api/v1/ledger, in shadow too. It never carries the document's text, the vendor's own note, an email address, a link or a token, as defined above. EscapereaderNote,reason,sentenceand the summary for wherever you show them, as you would any text from a vendor. Nothing else in/api/v1or the webhooks changes.
2026-10-25: Evidence, receipts and the close pack
GET /api/v1/invoices/{id}/evidenceandGET /api/v1/milestones/{id}/evidenceanswer{ data }with one payable's or milestone's evidence,vestiarion-evidence/1:subject,labels,stepswith theirfacts(each citingentriesbyseq),signedEntryProves,checkAnEntry,keys, and every cited entry in full (body_hash,signature,prev_hash,hash,signing_key_id,check). A fact'swhois a member's user id, never an email: "a former member" for someone who has left, "a member" when the members could not be read, "the payee" for what a payee entered,@<login> on GitHubfor a GitHub bounty, ornullwhen the ledger names no one. A receivable, or an id the workspace does not hold, answers404.GET /api/v1/invoices/{id}/receiptanswersvestiarion-receipt/1:ready;notReady(codenot_paid,simulated,not_minted,no_transactionornot_recorded, andreason);factsas a shared receipt states them;records(seq,hash);invoiceEntry;shared(at,entry,linkOpen,changes);checks(recorded,onChain);keysandentries. It never carries a receipt's link or its hash.GET /api/v1/payee-lock/evidencetakesfromandto(YYYY-MM-DD, either left out for an open end) and answersvestiarion-payee-lock-evidence/1. A member is{ kind: "member", userId, email: null }; the file downloaded from the workspace now carriesuserIdbesideemail.GET /api/v1/close-packs/{month}answersvestiarion-close-pack/1formonthasYYYY-MM, with every member'semailnull.- The five share a limit per key: 10 at once, then one every 6 seconds; over it they answer
429 rate_limitedwithRetry-After: 60. A close pack or a payee lock period whose answer would be over 4 MB answers400 invalid_request. Every other read stays unlimited. None of the five writes a ledger entry or sends a webhook, and none is an MCP tool yet. - The TypeScript SDK 0.4.0 adds
invoices.evidence,milestones.evidence,invoices.receipt,payeeLock.evidence,closePacks.getandverifyEvidence, with the typesPaymentEvidence,PaymentReceipt,PayeeLockEvidenceandClosePack. Namingkeyswith no value throws, so an unset variable never falls back to the file's keys.verifyEvidence(document, { keys, format })takes the format you expect, and a file of another format throws; options other than{ keys, format }, a PEM passed alone among them, throw too. A file that holds another format's citing fields, or cites something that is not an entry'sseq, isok: false. Nothing else in/api/v1or the webhooks changes.
2026-10-25: Close packs exported to Google Sheets
close_pack_exportedtakesformat: "google_sheets"when a member exports a month to Google Sheets, withconnectionId,spreadsheetId(Google's id of the spreadsheet) andcreated(a new spreadsheet was made). Itssha256is then the SHA-256 of the Payments tab as written:JSON.stringifyof its rows, the header first, each as wide as the header. It names no one by email and carries no URL.- A new entry, actor
human, domainsystem, listed byGET /api/v1/ledgerand sent to webhook endpoints asledger.appended:close_pack_export_failed{ by, month, ended, format, connectionId, spreadsheetId, stage, reason }, when an export failed after rows may have reached Google.stageiswriteorread_back;reasonisrate_limited,unavailable,reconnect(Google stopped accepting the connection),forbidden,drive_full,gone(the spreadsheet was deleted during the export),bad_responseormismatch. It counts toward the same ten in ten minutes asclose_pack_exported. accounting_connectedandaccounting_disconnectedmay carryprovider: "googlesheets";externalOrgIdis then the Google account's permission id andexternalOrgNamea masked email.- Nothing else in
/api/v1or the webhooks changes.
2026-10-25: Checking a vendor's document against its bill
document_checked, new, listed byGET /api/v1/ledgerand sent to webhook endpoints asledger.appended, domainap, actoragent: the cycle checked a document that a vendor sent, or a member attached, against its bill, once per document. It carriesinvoiceId,counterpartyIdandrequestId;source,vendorormember;fileSha256,fileTypeandfileSize;missing, what the bill lacked when it was checked (purchase_order,goods_receipt, or both; none for a bill that no longer waited);outcome,matched,mismatched,unreadableorskipped;reason, the sentence the bill's card shows,nullwhen it matched;reader,anthropic,openai,deepseekorheuristic,nullwhen nothing was read;checks, one{ check, result, document, bill, alsoRead? }per check run, wherecheckisvendor,currency,amount,purchase_order,pay_toorinvoice_number,resultismatch,mismatchorabsent, amounts are plain decimals with at least 2 places, andalsoReadis another reading that differs;poReference, the purchase order the document names, when it names one;poWritten,trueonly when that purchase order was added to the bill; andreaderFlagged: true,truncated: true(only its first 20,000 characters were read) andshadow: true(vendor requests were in shadow) when they apply. It never carries the document's text, the model's or the vendor's note, an email address or a link, and has noobserved.document_receivedcan now be a member's:byis the owner or admin who attached the vendor's document from the bill's card,viais"attached", and it carriesinvoiceId,counterpartyId,requestId,fileSha256,fileType: "application/pdf"andfileSize. One the vendor sent keepsby: nullandvia: "document_request".GET /api/v1/invoices: a payable'spoReferencecan now come from adocument_checkedwithpoWritten: true, while vendor requests are on. Nothing else on the bill changes: not its status, amount, currency, due date, goods receipt or address.- The agent's
ap_payandap_scheduledecisions on such a bill are held for a person under the guardrail ruleinvoice.vendor_document(guardrailBlocked: true,execution.resultingStatus: "held"), after every other rule of the agent's guardrails and beforeobligation.duplicate_referenceandproject.budget_exceeded, which do not run for a decision it holds: such a bill reserves nothing in its project. Everyap_*entry on such a bill carriesvendorDocument: { requestId, source, fileSha256 }, whichever rule held it. A person'sapproval_paidpays it, as before. - A cycle's journal has a new stage,
document_checks, aftercompliance. It needs no other stage to have succeeded. - A
cycle_completeentry'seventscan also includedocument_received, when a vendor sent, or a member attached, a document while vendor requests are in shadow or on. - Nothing else in
/api/v1or the webhooks changes.
2026-10-25: The monthly close pack
- A new entry, actor
human, domainsystem, listed byGET /api/v1/ledgerand sent to webhook endpoints asledger.appended:close_pack_exported{ by, month, ended, format, payments, notSettled, sha256, headSeq }, when a member downloads a workspace's close pack for a month.monthis YYYY-MM;endedis false for a month still running;formatiscsvorjson;paymentsandnotSettledcount its rows;sha256is the SHA-256 of the file served, in hex;headSeqis the ledger's last entry when it was read. It names no one by email. Nothing else in/api/v1or the webhooks changes.
2026-10-23: Late fees on bills
POST /api/v1/invoicesacceptslateFee, the late fee a payable charges once it is paid late, ornullfor none:kindispercent_month, a percent a month of what is still owed, more than 0 and at most 10, orfixed, an amount incurrency, more than 0 and at mostamount;valueis the percent or the amount;startsOn, the first day it applies asYYYY-MM-DD, is on or afterdueDate, and defaults to the day after it. A receivable with a late fee is refused with400, as is a value out of range (lateFee.value) or a start before the due date (lateFee.startsOn).GET /api/v1/invoices, and the invoice a write answers with, carrylateFee:{ kind, value, startsOn }, ornull.create_invoiceentries carrylateFee({ kind, value, startsOn },valueas entered) when the invoice was added with one.- The agent's
ap_*decisions carrylateFeein theirtermswhen the bill has one:{ kind, value, startsOn, aMonth }, whereaMonthis what a month past its start costs, in the invoice's currency. A late fee is never added to what is paid:amountPaidis the invoice's amount, less an early-payment discount, as before. cash_priority_setentries'orderitems carrylateFee, the bill's late fee ascreate_invoicesigns it ({ kind, value, startsOn }), when it has one. TheirreferenceOrdernow puts first, among the bills due or overdue, the one whose late fee costs most in USDC in the coming 30 days; a fixed fee that has started, or a fee that starts after those 30 days, counts for nothing.decision_escalatedentries'decideBycan also be the eve of a bill's late fee, the day before it starts: a bill past its due date whose fee starts later than the day after it is escalated once more on that day, besides once its due date has passed, as before. When its due date was not escalated before that day, as on the first day past it, the entry is for the due date, as before, and the eve is not escalated apart: a late fee never delays an escalation. Each is escalated once for its day, and an entry that tells such an eve says in itssummaryhow many payments have a late fee from tomorrow. A late fee never moves a bill's decide-by day.- The TypeScript SDK 0.3.7 describes
lateFeeonInvoiceandCreateInvoiceInput. Nothing else in/api/v1or the webhooks changes.
2026-10-23: An accountant's client invite links
org_createdcarriesvia: "accountant_link"for a workspace a client opened from their accountant's client link. Such a workspace is always on Arc testnet,network: "arc-testnet".member_joinedfor the accountant follows in that workspace, domainsystem, actorhuman, withrole: "accountant",clientLinkId(the link's id) andgrantedBy(the client, the workspace's owner).byis the accountant, as for an accepted invitation, which carriesinvitationIdinstead.member_joinedin a workspace on Arc mainnet opened as a live slice, for each accountant of the shadow workspace its owner brought along, carriesby(the accountant),role: "accountant",via: "live_slice"andgrantedBy(the owner).- Making and revoking a client link is signed in no workspace, since none exists yet. Nothing else in
/api/v1or the webhooks changes.
2026-10-23: Asking a vendor for a missing document
- Five new entries, listed by
GET /api/v1/ledgerand sent to webhook endpoints asledger.appended:document_requests_changed, domainsystem, actorhuman: an owner set vendor requests tooff,shadoworonin Settings. It carriesby,fromandto.document_request_drafted, domainap, actoragent: with vendor requests in shadow, a bill waiting for its purchase order or goods receipt was recorded as one the agent would ask its vendor about; nothing was sent. It carriesinvoiceId,counterpartyId,requestId,missing(purchase_order,goods_receipt, or both) andemailDomain, the billing email's domain, never the address. One per bill, not one per cycle.document_requested, domainap, actoragent: the vendor's billing email was sent a one-time link to send the document. It carries the same fields andexpiresAt, 14 days after it was sent, never the link or the address.document_received, domainap, actorhuman, withby: nullandvia: "document_request": the vendor sent the document through its link. It carriesinvoiceId,counterpartyId,requestId,poReferencewhen the vendor typed one (plain text on one line, of at most 100 characters, with no link),fileSha256,fileType(application/pdf,image/pngorimage/jpeg) andfileSizein bytes, never the file or the vendor's note.document_request_revoked, domainap, actorhuman: an owner or admin revoked an open request, whose link stopped working. It carriesby,requestId,invoiceIdandcounterpartyId.
- In a sandbox,
document_request_draftedanddocument_requestedcarrysandbox: true: a sandbox never emails its vendors, so the request goes to the member who set vendor requests, andemailDomainis that member's email domain. - None of them changes the bill: its status, amount, purchase order and address stay as they were, as
GET /api/v1/invoicesreturns them. A person still adds the purchase order with Add details, recorded asinvoice_details_added. - A cycle's journal has a new stage,
document_requests, afterterm_requests. It needs theapstage to have succeeded. - A
cycle_completeentry'seventscan also includedocument_requests_on, when an owner set vendor requests to shadow or on. - Nothing else in
/api/v1or the webhooks changes.
2026-10-22: Bills waiting for approval in Discord
- Two new entries, listed by
GET /api/v1/ledgerand sent to webhook endpoints asledger.appended, both in thesystemdomain:discord_connected, actorhuman: an owner or admin connected a Discord channel webhook from Settings, after Discord took a test message on it. It carriesby,webhookIdandchannelId, Discord's ids, never the webhook's URL or token.discord_disconnected: the workspace's Discord was disconnected. Actorhumanwhen an owner or admin chose Disconnect (via: "settings"); actorsystemwhen Discord answered that the webhook is gone (via: "discord"), withbynull. It carriesby,webhookIdandvia.
- A cycle's journal has a new stage,
discord, afterslack, the last. It needs no other stage to have succeeded. - Nothing else in
/api/v1or the webhooks changes.
2026-10-22: An accountant's co-sign
- A new entry, listed by
GET /api/v1/ledgerand sent to webhook endpoints asledger.appended:accountant_cosign_changed, domainsystem, actorhuman, when an owner turns accountants' co-signing on or off. It carriesby,fromandto, eachtrueorfalse. approval_givencarriescosign: truewhen the approval is an accountant's co-sign. A co-sign is one of a bill's two approvals and never the one that pays: theapproval_paidentry that follows names it among itsapprovals.- Nothing else in
/api/v1or the webhooks changes.
2026-10-22: A vendor's statement checked
- A new entry, listed by
GET /api/v1/ledgerand sent to webhook endpoints asledger.appended:vendor_statement_checked, domainap, actorhuman, when a person checks a vendor's statement of account against its bills. It carriesby,counterpartyId,period({ from, to }),currency, the numbers oflines,charges,payments,matchedChargesandmatchedPayments, how many weremissing,rejected,twice,differs,notCompared,paidNotListed,unknownPaymentsandnotListed, andtheirBalanceandourBalance. It never carries the statement or its lines. - Nothing else in
/api/v1or the webhooks changes.
2026-10-22: Arc mainnet pays vendors on Arbitrum
POST /api/v1/counterpartiesnow acceptschain: "ARB"(Arbitrum One) for a vendor in a workspace on Arc mainnet, besideARCandBASE. A contractor stays on Arc.- Counterparties, bills and their entries may name
ARBwherever they name a payee's chain, as they nameBASE:counterparty_address_changed, a CCTP payout'sdestinationChain, and a receipt'schain, whose transaction is the mint on Arbitrum. - The TypeScript SDK 0.3.6 accepts
ARBfor a counterparty'schain. Nothing else in/api/v1or the webhooks changes.
2026-10-22: Receipts state the fees, who paid them and the invoice number
receipt_sharedentries'receiptcan now also carryinvoiceNumber(the invoice's own number, as on itscreate_invoiceentry),invoiceAmount(the invoice's amount, only when it was for more than was paid, as after an early-payment discount) andfeesPaidBy: "sender"(every fee was paid by the business on top of the amount, and none taken from the payee's). Receipts shared before keep what they stated.create_invoiceentries now carryinvoiceNumberfor an invoice typed into the invoice form with one, or read from a document, an email, or in Telegram or Slack, as they already did for imports and captured drafts; for a captured draft, the number the person kept or typed. An accounting connector's bill keeps it under the provider's name.- Nothing else in
/api/v1or the webhooks changes.
2026-10-22: The weekly brief counts payee address changes
weekly_brief_sentnow carriespayees: { lockOn, changed, confirmed, held, asked, notMe, frozen }for the last 7 days: whether the payee lock is on, the addresses set and confirmed, the agent's decisions held for an address (guardrailRulecounterparty.address_unconfirmed,counterparty.cooling_offorinvoice.pay_to_differs), the payees' contacts asked "Was this you?" and those who answerednot_me, and the payees frozen now. It is absent when they could not be read. A week with only these to tell now sends the brief, where before it sent none.- Nothing else in
/api/v1or the webhooks changes.
2026-10-22: "Was this you?" and frozen payees
- Four new entries, listed by
GET /api/v1/ledgerand sent to webhook endpoints asledger.appended, all in thecompliancedomain:address_change_check_sent(actorsystem): the payee's billing email on file was asked whether they changed its address. It carriescounterpartyId,checkId,from,to,via(member,payee_linkorgithub) andcontact: "notice_email", never the email itself.address_change_answered(actorhuman,by: null,via: "address_check"): the payee answered. It carriescounterpartyId,checkId,answer(meornot_me),fromandto.counterparty_frozen(actorsystem): anot_meanswer froze the payee while the address in question was on file. It carriescounterpartyId,checkId,addressandreason: "address_change_disputed".counterparty_unfrozen(actorhuman): an owner or admin unfroze the payee. It carriesby,counterpartyId,checkId(the check that froze it) andnote, how they checked. Whoever made the disputed change unfreezes it only when no other owner or admin can, and an unfreeze whose entry could not be written is undone, so every unfreeze has its entry.
- A frozen payee's address is no longer confirmed, so the agent holds payments to it as for any address no one has confirmed (
guardrailRule: "counterparty.address_unconfirmed"), until someone confirms it after it is unfrozen. - Nothing in
/api/v1request bodies or the webhooks' shapes changes.
2026-10-21: A screening verdict names the service that gave it
screen_counterparty,risk_level_changedandcompliance_sweepcan now carrysource: "yente:self-hosted", and so can the screening historyGET /api/v1/counterparties/{id}returns: the counterparty was screened by a self-hosted yente server the deployment names, rather than OpenSanctions' hosted API (opensanctions:yente, as before). Both are judged by the same rules.- Nothing in
/api/v1request bodies or the webhooks' shapes changes.
2026-10-21: A payment waits when its invoice asks to be paid somewhere else
- A
create_invoiceentry for an invoice read from a document can carrydocument.payTo: the 0x address the document asked to be paid to. - An agent decision entry (
ap_payand the otherap_*actions) can now carryguardrailRule: "invoice.pay_to_differs": the payment was held because the invoice asked to be paid to an address that is not the counterparty's address on file. ItsobservedcarriesdocumentPayTo. - An
ap_reconcileentry can now carrynotResubmittedBecause: "invoice.pay_to_differs": a payment that never reached the network is not sent again while the invoice asks for another address. It is held for a person. - Once the counterparty's address on file is the one the invoice asked for, the follow-up reopens it: an
invoice_reopenedentry follows, withfollowUp.changesreading "the address on file is now the one the invoice asked to be paid to", then a new decision. A webhook endpoint receives each asledger.appended. - Nothing in
/api/v1request bodies or the webhooks' shapes changes.
2026-10-21: Sanctioned payout addresses
screen_counterpartyandrisk_level_changedcan carrysource: "ofac-sdn"andmatchedEntityId: "ofac-sdn-<entry>", and so can the screening historyGET /api/v1/counterparties/{id}returns. The counterparty's payout address is on OFAC's SDN list, which decides a high-risk verdict whatever its name screens as.- A
compliance_sweepentry carriessanctionedWallets({ list: "ofac-sdn", from, readAt, addresses }): the list the payout addresses were checked against.fromislivefor the Treasury's files andsnapshotfor the copy bundled with the code. - Nothing in
/api/v1request bodies or the webhooks' shapes changes.
2026-10-21: A payment not sent again is decided again once what held it ends
- A payable whose
ap_reconcileentry carriesnotResubmittedBecause"counterparty.cooling_off","counterparty.address_unconfirmed"or"counterparty.new_payee"is no longer held until a person acts. Once the payee lock's wait ends, someone confirms the address, or a second person stands behind it, the follow-up reopens it: aninvoice_reopenedentry follows, withfollowUp.changesreading "the payee lock's wait for the new address has ended", "the counterparty's new address has since been confirmed" or "a second person now stands behind the payee's address", then a new decision (ap_payand the otherap_*actions). A webhook endpoint receives each asledger.appended. - The payment the new decision makes is sent under the same payment key as the send that never reached Circle, so it is paid once.
- Such an
ap_reconcileentry can now carryearlierSendNotLookedUp: true: the earlier send was a payout to another chain, which cannot be looked up, so Circle may still hold it. That payable still waits for a person, as do payables agreed to in shadow mode. - Nothing in
/api/v1request bodies or the webhooks' shapes changes.
2026-10-21: A cycle when a payee lock's wait ends, and when the schedule missed a workspace
- A
cycle_completeentry'seventscan includepayee_lock_wait_ended. The payee lock's wait on a confirmed address ended while a payable or a verified milestone was held back by it, and the due-work watch started the cycle, within about five minutes of the wait ending. The watch, not a person, started it, so itsbyis absent. - A
cycle_completeentry'seventscan also includepayee_lock_eased, when an owner turned the payee lock off or shortened its wait. That cycle decides again what the wait held back. - A scheduled cycle that the six-hourly schedule missed in a workspace now runs within about 20 minutes of its time. Its
cycle_completecarriestrigger: "schedule", as any scheduled cycle's does. - Nothing in
/api/v1request bodies or the webhooks' shapes changes.
2026-10-20: The payee lock
-
A new entry, listed by
GET /api/v1/ledgerand sent to webhook endpoints asledger.appended:payee_lock_changed(domainsystem, actorhuman), when an owner turns the payee lock on or off or changes its wait. It carriesby,fromandto, each{ on, coolingHours }. -
counterparty_address_confirmedmay now carry:verification({ method, contact, contactOnFileBefore, note }, wheremethodiscall,message,in_personorother): how the person checked the address;payeeLock({ coolingHours }), when the lock was on;soloConfirmation: true, when whoever entered or asked for the address confirmed it because no one else could;byGiver: true, when they confirmed it with the lock off;lookalikeOf: the ids of other counterparties whose address is the same, or shares its first 6 and last 4 hex digits;looksLikeEarlier: an address the same payee had or was paid at before that shares those digits with the new one;giverUnknown: true, when the lock was on and no member could be named as having entered or asked for the address.
Each field is present only when it applies.
-
An agent decision entry (
ap_payand the otherap_*actions) can now carryguardrailRule: "counterparty.cooling_off": the payment was held because the counterparty's address changed less than the payee lock's wait ago. Once the wait ends, aninvoice_reopenedentry'sfollowUp.changesreads "the payee lock's wait for the new address has ended", and a new decision follows. -
An
ap_reconcileentry can now carrynotResubmittedBecause: "counterparty.cooling_off": a payment that never reached the network is not sent again to a changed address inside the payee lock's wait. It is held for a person. -
Nothing in
/api/v1request bodies or the webhooks' shapes changes.
2026-10-19: A payee sends its invoice, and picks where it is paid, through its payee link
- A new entry, listed by
GET /api/v1/ledgerand sent to webhook endpoints asledger.appended:payee_invoice_submitted(domaincompliance, actorhuman), when a payee sends its invoice through a payee link that asks for one. It carriesby: null,via: "payee_link",linkId,draftId(the draft waiting for review),counterpartyId,amount(a decimal string),currency("USDC"),invoiceNumberanddocumentSha256(the SHA-256 of the file sent, ornullwithout one). No bill exists yet: one is added only when a member adds the draft. - A second new entry:
counterparty_address_kept(domaincompliance, actorhuman), when a payee keeps the address the workspace has on file through a payee link that asks for its invoice. It carriesby: null,via: "payee_link",linkId,counterpartyIdandaddress. Nothing changes on the counterparty. counterparty_address_changednow carrieschain, the chain the address is on (the workspace's own,ARCorARC-TESTNET, when the counterparty has none recorded), andfromChain, the chain before, only when the payee chose another chain through its payee link. Choosing the workspace's own chain where none was recorded is no change of chain.counterparty_address_confirmedcarrieschaintoo.payee_link_createdmay carryasksInvoice: trueandoffersChain: true, for a link made on Counterparties with those boxes ticked. A link made throughPOST /api/v1/payee-linkscarries neither, as before. A link made without them also carriesclosedInvoiceLinks(a count) when making it stopped earlier links of the same payee that were still waiting for their invoice.payee_link_revokedcarriesinvoiceOnly: truewhen Revoke stopped a used link from taking its payee's invoice, rather than revoking an unused link.create_invoicefor a bill added from a payee's invoice carriesvia: "payee_link",invoiceDraftId,invoiceNumberandpayeeLinkId, where a draft from the Chrome extension carriesvia: "chrome".POST /api/v1/payee-linksand the SDK make links with both options off, as before. A new link, made there or anywhere, also stops an earlier link of the same payee that is still waiting for its invoice. Nothing else in/api/v1or the webhooks changes.
2026-10-19: Pay a vendor on Base from your own wallet
- A workspace paying from its owner's own wallet now pays a vendor on Base through version 2 of its spending limit contract. Its
ap_payfor such a bill carriesonChainLimit.covered: trueand the contract'sverdict, asked with the CCTP fee, where it was held before underguardrailRule: "workspace.onchain_limit_route". A version 2 contract that would refuse it holds it under"workspace.onchain_limit", as for a payment on Arc; a version 1 contract still holds it under"workspace.onchain_limit_route".payoutand the reconcile entry'sexecution.destinationChainandmintTxHashare as for any payout to Base. spending_limit_deployednow carriesversion(1or2), and, for an upgrade,replaces: the contract it is to replace.- Two new entries, listed by
GET /api/v1/ledgerand sent to webhook endpoints asledger.appended, both in domainsystem, actorhuman:spending_limit_upgraded, when version 2 takes over the agent's payments:by,fromandto(the two contracts),version(2),agent,treasury,signer(walletorpasskey),dailyUsdc,weeklyUsdc,deployTxHash,approveTxHash,revokeTxHash(the passkey's one transaction, ornulluntil a browser wallet revokes) andallowanceUsdc(nullwithout a cap).spending_limit_revoked, when the owner's wallet sets its approval of the replaced contract to 0:by,contract,replacedByandtxHash.
- Nothing else in
/api/v1or the webhooks changes.
2026-10-19: Pay a vendor on Base from Arc mainnet
chainon a counterparty (POST /api/v1/counterpartiesand every response that carries it) may now beBASE: a vendor's address on Base, in a workspace on Arc mainnet. As on Arc testnet, only a vendor can be on another chain, and only a chain the workspace's network pays on is accepted (BASEon Arc mainnet;BASE-SEPOLIA,ARB-SEPOLIAorETH-SEPOLIAon Arc testnet).POST /api/v1/milestonesnow refuses acontractorIdwhose counterparty is paid on another chain, on either network, withinvalid_requestand "contractorId: This vendor is paid on another chain, and a milestone is paid on the workspace's own chain only. Add the work as an invoice instead." A milestone is released on the workspace's own chain, so such a payee would have been sent USDC there.- Such a payout is recorded like one from Arc testnet:
ap_paycarriespayout: { chain: "BASE", route: "cctp", domain: 6, feeUsdc, quotes }, and the payment's reconcile entry carriesexecution.destinationChain: "BASE"andmintTxHash, the mint on Base. It is paid only from a workspace on its own Circle account; a workspace paying from its own wallet holds it for a person, as before. - The TypeScript SDK 0.3.5 accepts
BASEfor a counterparty'schain. Nothing else in/api/v1or the webhooks changes.
2026-10-19: A reminder when a workspace stops
- Two new entries, listed by
GET /api/v1/ledgerand sent to webhook endpoints asledger.appended, both in domainsystem, actorsystem:activation_nudge_sent, signed just before a setup reminder goes, withstage(first_bill: no real bill a day after the workspace was opened;first_verdict: in shadow mode, no verdict three days after the agent's first decision on a real bill),recipients(how many it goes to), anddaysandshadowforfirst_bill, orwaiting(decisions still to give a verdict on) forfirst_verdict. Each stage goes once per workspace.activation_nudge_failed, when no email went after all, withstageandfailed; the reminder is then tried again, up to three tries in all.
- Nothing else in
/api/v1or the webhooks changes.
2026-10-19: Where an invitation came from
member_invitedmay now carryvia:console_nudgefor an invitation an owner or admin sent from Treasury's Bring in a second person, andweekly_brieffor one sent from Members after following the weekly summary's link. An invitation sent any other way has novia, as before;by,invitationIdandroleare unchanged.- Nothing else in
/api/v1or the webhooks changes.
2026-10-18: Ask every payee for an address at once
- A new entry, listed by
GET /api/v1/ledgerand sent to webhook endpoints asledger.appended:payee_addresses_requested(domaincompliance, actorhuman), when an owner or admin asks every payee with no address of its own at once. It carriesby(their user id),links(each{ counterpartyId, linkId, emailed },emailedsaying whether the link went to the payee's notice email) andnotMade(the counterparty ids whose link could not be made). Each link also has its ownpayee_link_createdentry, as before. - Nothing else in
/api/v1or the webhooks changes.
2026-10-18: Start the live slice from shadow mode
- A new entry, listed by
GET /api/v1/ledgerand sent to webhook endpoints asledger.appended:live_slice_started(domainsystem, actorhuman), in a workspace in shadow mode, when an owner opens a workspace on Arc mainnet from it. It carriesby(their user id),liveOrgIdandliveSlug(the new workspace),vendors(each{ counterpartyId, name, address }, whereaddresssays how its address went over:own, carried;mirror,other_chain,unconfirmedornone, not carried) andskipped(each vendor left behind,{ counterpartyId, name, reason }, wherereasonisno_limit,not_validornot_added). - In the new workspace, each vendor's
create_counterpartycarriesvia: "live_slice",fromOrgId,fromCounterpartyIdandaddressNeedsConfirmation. A carried address waits for a member's confirmation, as one added through the API does. - Nothing else in
/api/v1or the webhooks changes.
2026-10-18: A person's order for which bill first
cash_priority_setmay now be signed by a member (actorhuman), when an owner, admin or approver sets the order from the payment plan. It then carriesdecisionMode: "person",by(their user id),previousOrder(the invoice ids in the order it replaced, ornull), andreasoningsaying a person set it;order,cash,fingerprint,referenceOrderandagreedWithReferenceare as before. While the same bills compete, the agent applies that order and signs no new one.- When bills leave a person's order (paid, or past the window) and the rest are unchanged, the agent signs
cash_priority_setagain for the bills still due, actoragent, withdecisionMode: "person", the sameby, andcarried: true. - An AP decision on a bill in a person's order carries
cashPriority: { waits, reason: null, fingerprint, byPerson: true }, whether it is kept or waits. invoice_reopenedfor a bill a person's order keeps says so in its summary andfollowUp.changes: "a person chose to pay it first".- Nothing else in
/api/v1or the webhooks changes.
2026-10-18: A supplier's payment status link
- Two new entries, listed by
GET /api/v1/ledgerand sent to webhook endpoints asledger.appended, both in domainap, actorhuman:supplier_status_shared, when an owner or admin makes a supplier's payment status link:by(their user id),linkId,counterpartyId,expiresAt,days(7, 30 or 90) andreplaced(the ids of the supplier's links it stopped). The link itself is never in the entry.supplier_status_unshared, when one is stopped:by,linkIdandcounterpartyId.
- Nothing else in
/api/v1or the webhooks changes.
2026-10-18: Which bill first when the cash cannot cover them all
- A new entry, listed by
GET /api/v1/ledgerand sent to webhook endpoints asledger.appended:cash_priority_set(domainap, actoragent), when the bills due within 14 days add up to more than the cash and the agent chooses the order they are paid in. It carriesfingerprint,cash: { operating, reserve, committed, available },order(each bill, most important first:{ invoiceId, payee, amount, dueOn, keep, reason }),reasoning,decisionMode,referenceOrder(the written policy's, as invoice ids),agreedWithReference, andorderCorrected: truewhen code fixed the model's order. It is signed again only when the bills change, or the cash changes enough to split them differently. invoice_reopenedmay carryfollowUp.reason: "cash_priority", for a bill held for want of cash that the agent chose to pay first.- An AP decision on a bill in the plan carries
cashPriority: { waits, reason, fingerprint }, andtimingRulemay be"cash.priority"when code turned the model's pay or schedule on a waiting bill into a hold; such a hold hasexecution.heldBecause: "cash_shortfall", and itscashNeededUsdcis its own amount plus the kept bills'. - Nothing else in
/api/v1or the webhooks changes.
2026-10-18: The weekly brief in shadow mode
- In a workspace in shadow mode,
weekly_brief_sentnow carriesshadow: { verdicts: { given, agreed }, sinceStart: { given, agreed, since } }, the verdicts given in the week and since shadow mode began, andshortis alwaysnull: the wallet only mirrors agreed payments. Such a workspace now gets the brief, where before it got none. Nothing else in/api/v1or the webhooks changes.
2026-10-18: The agent's weekly brief
- Two new entries, listed by
GET /api/v1/ledgerand sent to webhook endpoints asledger.appended, both in domainsystem, actorsystem:weekly_brief_sent, signed just before the emails go, withweek(2026-W43),recipients(how many it goes to),paid: { count, usdc },received: { count, usdc },decisions,waiting,next7: { count, usdc, expectedUsdc }andshort(the cash shortfall, ornull). One a member sent to themselves from Settings also carriespreview: trueandby, their user id.weekly_brief_failed, when no email went after all, withweekandfailed; the week's brief is then tried again.
- Nothing else in
/api/v1or the webhooks changes.
2026-10-17: The agent tells you before the cash runs short
- Two new entries, listed by
GET /api/v1/ledgerand sent to webhook endpoints asledger.appended, both in domaintreasury, actoragent:cash_short_ahead, when the wallet will run short within 30 days:shortOn(the first short day,YYYY-MM-DD) andshortBy,lowestOnandneed(the shortest day and what it needs to pay everything due through it),expectedBy(receivables expected by then, not counted) andcoveredWithExpected,cash: { operating, reserve }, anddoing: { heldForCash: { count, total }, termRequestsOpen, customerDiscountsOpen }, eachnullwhen it could not be read. Signed again only whenshortOncomes earlier,needgrows by at least 1 USDC and a tenth, or 7 days pass.cash_short_cleared, once the wallet no longer runs short after an alert, withprevious: the last alert's detail.
- A cycle's journal has a new stage,
cash_alert, afterterm_requests. It runs only whenreconcilecompleted. Nothing else in/api/v1or the webhooks changes.
2026-10-17: Scheduled payments checked against the cash ahead
- An AP decision made before a scheduled bill's day, because the cash will no longer cover it then, carries
cashAhead:{ scheduledFor, cashCounted, dueBefore: { total, count }, needed }. Such an entry is usuallyap_holdwithexecution.heldBecause: "cash_shortfall". timingRulemay be"pay.cash_ahead": the model chose to pay such a bill now, and code held it, since paying it would take the cash the bills before it count on.- Nothing else in
/api/v1or the webhooks changes.
2026-10-17: Suppliers counter the agent's requests for more time
- On a request for more time, a supplier may propose fewer days, and the agent answers it. New entries, listed by
GET /api/v1/ledgerand sent to webhook endpoints asledger.appended, all in domainap:term_request_countered(actorsystem,via: "terms_link"), withrequestId,invoiceId,counterDaysanddays.term_counter_acceptedandterm_counter_declined(actoragent), withrequestId,invoiceId,counterpartyId,days,counterDays,decision: { action: "accept" | "decline", reasoning },referenceDecision,decisionMode,agreedWithReferenceandsupplierTold. An acceptance also carriesnewDueDate; a counter the bill changed under carriesbillChanged: true.decisionModeiscodewhen the bill was being paid and no model was asked.
- An accepted counter moves the invoice's
dueDatebycounterDaysand returns the payable topending. Nothing else in/api/v1or the webhooks changes.
2026-10-17: Requests for more time withdrawn when no longer needed
term_request_withdrawnmay now carryreason: "paid", when the bill is being paid, orreason: "not_needed", when it is no longer held for want of cash, beside"not_emailed". These carrycounterpartyId,days,supplierTold(whether the supplier was emailed that the request is withdrawn) andto(the address, masked). Nothing else in/api/v1or the webhooks changes.
2026-10-17: The agent asks suppliers for more time
- An owner or admin can let the agent ask a supplier for more time on a bill held for want of cash. Each step is a new entry, listed by
GET /api/v1/ledgerand sent to webhook endpoints asledger.appended:term_requests_on(domainap, actorhuman), withmaxDaysandby, andterm_requests_off, withby.term_request_sent(actoragent,via: "agent"), withrequestId,invoiceId,counterpartyId,to(the supplier's address, masked),days,amount,currency,dueDate,newDueDate,expiresAt,decision: { action: "ask", days, reasoning },referenceDecision,decisionModeandagreedWithReference;daysLimited: { chosen, sent }when code kept the days within their bounds, andsandbox: truein a sandbox.term_request_skipped(actoragent), withinvoiceId,counterpartyId,decision: { action: "skip", reasoning },referenceDecision,decisionModeandagreedWithReference.term_request_withdrawn(actoragent,via: "agent",reason: "not_emailed"), withrequestIdandinvoiceId, when a request could not be emailed.term_request_acceptedandterm_request_declined(actorsystem,via: "terms_link"), withrequestIdandinvoiceId; an acceptance also carriesdaysandnewDueDate.
- An accepted request moves the invoice's
dueDateto the new date and returns the payable fromheldtopending, asGET /api/v1/invoicesshows it. The agent's next decision on it, anap_…entry as before, weighs the new date. Nothing else in/api/v1or the webhooks changes.
2026-10-17: The agent offers customers a discount to pay early
- An owner or admin can let the agent offer customers a discount for paying an open receivable early while bills are held for want of cash. New entries, listed by
GET /api/v1/ledgerand sent to webhook endpoints asledger.appended, all in domainar:customer_offers_on(actorhuman), withmaxPctandby, andcustomer_offers_off, withby.customer_discount_offered(actoragent), withofferId,invoiceId,counterpartyId,to(the customer's address, masked),discountPct,amount,offeredAmount,currency,payBy,daysEarly,shortfall,decision: { action: "offer", pct, reasoning },referenceDecision,decisionMode,agreedWithReference, andpctLimited: { chosen, sent }when code kept the discount within its bounds.customer_discount_skipped(actoragent), withinvoiceId,counterpartyId,daysEarly,shortfall,decision: { action: "skip", reasoning },referenceDecision,decisionModeandagreedWithReference.customer_discount_withdrawn(actoragent), withofferId,invoiceIdandreason: "not_emailed".customer_discount_acceptedandcustomer_discount_declined(actorsystem,via: "discount_link"), withofferIdandinvoiceId; an acceptance also carriesdiscountPct,offeredAmount,payByandcurrency.customer_discount_taken(actoragent), withinvoiceId,counterpartyId,offerId,amount,received,discountPct,discount(what it cost),payBy,currencyandtxHash, after the receivable was paid at the discount.
- An accepted offer sets the receivable's
earlyPayDiscountto the offer's, the deadline being its pay-by day; itsamountdoes not change. Itsar_receivedentry, when paid at the discount, carriesatDiscount: trueand the amount received. A discount set on a receivable any other way still changes nothing about what pays it. Nothing else in/api/v1or the webhooks changes.
2026-10-17: The agent's early-payment offers in a sandbox
- In a sandbox, the agent now makes early-payment offers, sent to the member who turned them on in place of the sample supplier. Its
early_payment_offeredentry there carriessandbox: true, andtois that member's address, masked. Nothing else in/api/v1or the webhooks changes.
2026-10-17: The agent withdraws offers the cash no longer covers
early_payment_offer_withdrawnmay now come from the agent withvia: "agent"andreason: "cash". It carriesofferId,invoiceId,offeredAmount, andcovering: the operating USDC left after the cycle's payments, less what falls due in 7 days. The agent sends it when that cash no longer covers every open offer, and withdraws its own offers, the largest first. Nothing else in/api/v1or the webhooks changes.
2026-10-17: A payment now that gains nothing waits for its day
- An
ap_scheduleentry may carry a new value oftimingRule,pay.no_gain. The model answered pay for a payable that gains nothing by being paid today: no early-payment discount available, no shortfall, a due date ahead, and not already set for today. Code scheduled it for the policy's day, its due date, instead. The entry'sdecisionis{ action: "schedule", payOn }, and its reasoning ends with a note that says so. Nothing else in/api/v1or the webhooks changes.
2026-10-17: Suppliers counter the agent's early-payment offers
- On an offer the agent made, a supplier may propose a smaller discount, and the agent answers it. Each step is a new entry, listed by
GET /api/v1/ledgerand sent to webhook endpoints asledger.appended:early_payment_offer_countered(domainap, actorsystem,via: "offer_link"), withofferId,invoiceId,counterPct,discountPctandcurrency.early_payment_counter_acceptedandearly_payment_counter_declined(actoragent), withofferId,invoiceId,counterpartyId,discountPct,counterPct,decision: { action: "accept" | "decline", reasoning },referenceDecision,decisionModeandagreedWithReference. An acceptance also carriesofferedAmount; a counter the bill changed under carriesbillChanged: true.decisionModeiscodewhen code declined it without asking a model.
- An accepted counter sets the invoice's
earlyPayDiscountto the counter, the deadline being today (UTC), and returns the payable topending; the agent's nextap_…entry weighs it as before.
2026-10-16: The agent makes early-payment offers
- An owner or admin can let the agent make early-payment offers itself. New entries, listed by
GET /api/v1/ledgerand sent to webhook endpoints asledger.appended:early_offers_on(domainap, actorhuman), withmaxPctandby, andearly_offers_off, withby.early_payment_offeredwith actoragentandvia: "agent". Beside the fields a person's offer carries (butby), it hasto(the supplier's address, masked),daysEarly,decision: { action: "offer", pct, reasoning },referenceDecision,decisionModeandagreedWithReference, andpctLimited: { chosen, sent }when code kept the discount within its bounds.early_payment_offer_skipped(actoragent), withinvoiceId,counterpartyId,daysEarly,decision: { action: "skip", reasoning },referenceDecision,decisionModeandagreedWithReference.early_payment_offer_withdrawnwithvia: "agent"andreason: "not_emailed", when an offer the agent made could not be emailed.
- Nothing else in
/api/v1or the webhooks changes.
2026-10-16: Early-payment offers
- An owner or admin can offer a supplier payment today for a discount, through a one-time link the supplier answers with no account. Each step is a new entry, listed by
GET /api/v1/ledgerand sent to webhook endpoints asledger.appended:early_payment_offered(domainap, actorhuman), withofferId,invoiceId,counterpartyId,discountPct,amount,offeredAmount,currency,expiresAtandby.early_payment_offer_acceptedandearly_payment_offer_declined(actorsystem,via: "offer_link"), withofferIdandinvoiceId; an acceptance also carriesdiscountPct,offeredAmountandcurrency.early_payment_offer_withdrawn, withofferIdandby.
- An accepted offer sets the invoice's
earlyPayDiscountto{ percent, deadline }, the deadline being today (UTC), and returns a scheduled payable topending, asGET /api/v1/invoicesshows it. The agent's next decision on it, anap_…entry as before, weighs that discount like any other. Nothing else in/api/v1or the webhooks changes.
2026-10-16: Bills paid to a vendor's bank account in Mexico
- An owner can set a workspace up for bank payouts through BlindPay, and an owner or admin can give a vendor a bank account in Mexico, whose bills are then paid in pesos over SPEI from the workspace's USDC. Each change is a new entry, listed by
GET /api/v1/ledgerand sent to webhook endpoints asledger.appended:bank_payouts_set_up(domaintreasury), withprovider: "blindpay",customerIdandtosId(BlindPay's ids),kybStatusandby.counterparty_bank_account_set(domaincompliance), withcounterpartyId,provider: "blindpay",bankAccountId(BlindPay's id),rail: "spei",bankCode(the CLABE's first three digits),last4andstatus. When the account is removed,bankAccountIdisnull. The whole CLABE is never in an entry.bank_payouts_test_token_minted(domaintreasury), on Arc testnet only: BlindPay's test token minted to the operating wallet, withtoken: "USDB",contract,amount,txHash,statusandby.
- The agent's decision on a bill of such a vendor carries
paidToBank: true, and a payment it would make is held withguardrailBlocked: trueand a new value ofguardrailRule,payout.bank_needs_person: a person approves every bank payout. On Arc testnet, where BlindPay takes its test token USDB, such a bill is timed against the operating wallet's USDB: a hold for want of it carries noheldBecause: "cash_shortfall",cashNeededUsdcorcashSeen, since USDC coming in does not cover it. - A person's
approval_paidentry for one carriespayout: { route: "bank", provider: "blindpay", quoteId, payoutId, receiverAmount, currency: "MXN", rate, feesSender, network, token, rail: "spei", bankAccount: { bankCode, last4 } }, BlindPay's quote and payout. The payment is confirmed once BlindPay says the payout completed. Nothing else in/api/v1or the webhooks changes.
2026-10-16: Deals brought in from Zoho CRM
- An owner or admin can connect a workspace to a Zoho CRM organization, and a person plans the collections of the won deals it brings in. There is no new kind of entry: the entries HubSpot's and Pipedrive's deals use (below) now also name Zoho CRM. Each is listed by
GET /api/v1/ledgerand sent to webhook endpoints asledger.appended:accounting_connectedandaccounting_disconnectedwithprovider: "zohocrm";externalOrgIdis the Zoho CRM organization id andexternalOrgNameits name.accounting_connectedcarriesconsent.versionzohocrm-2026-10-16, andscopesZohoCRM.modules.deals.READ,ZohoCRM.modules.accounts.READ,ZohoCRM.modules.contacts.READ,ZohoCRM.org.READ,ZohoCRM.settings.layouts.READandZohoCRM.settings.pipeline.READ, all read only. Several workspaces may connect the same organization, each with its own connection.deal_signed, for a deal planned from Zoho CRM, anddeal_revised, for a change saved from what Zoho CRM changed, withvia: "zohocrm"andzohocrm: { organizationId, dealId, accountId }: the organization id, the deal's id and the id of the account it was sold to, in Zoho CRM. The deal'sexternalRefiszohocrm-followed by Zoho CRM's deal id.create_counterparty, for a customer added with such a deal, andcounterparty_notice_email_changed, for a billing email filled from Zoho CRM, withvia: "zohocrm"andzohocrm: { organizationId, accountId }; the addresses are masked, as before.crm_deal_changedandcrm_deal_change_keptwithprovider: "zohocrm";crmDealIdis Zoho CRM's deal id, without thezohocrm-prefix. Astagechange'slabelis the stage's name in Zoho CRM.
- Nothing is written to Zoho CRM, so a Zoho CRM connection writes no
crm_receipt_entries. Nothing else in/api/v1or the webhooks changes: the Zoho CRM deals not planned are not in the API.
2026-10-16: Bills brought in from Zoho Books
- An owner or admin can connect a workspace to a Zoho Books organization, and a person adds the bills it brings in from Bills & receivables. Its connection writes the entries Xero's and QuickBooks' write (below), each sent to webhook endpoints as
ledger.appendedand listed byGET /api/v1/ledger, withprovider: "zohobooks":accounting_connected,accounting_disconnected,accounting_bill_closedandaccounting_bills_dismissed.externalOrgIdis the Zoho Books organization id,externalOrgNameits name, andbillIdandbillIdsare Zoho Books bill ids. accounting_connectedcarriesconsent.versionzohobooks-2026-10-16, andscopesZohoBooks.bills.READ,ZohoBooks.contacts.READandZohoBooks.settings.READ, all read only. Several workspaces may connect the same organization, each with its own connection.accounting_bill_closedcomes when a bill already added is paid or voided in Zoho Books, withsourceStatuspaidorvoided, neverdeleted: Zoho Books does not say when a bill is deleted.- A bill added from Zoho Books is a
create_invoiceentry withvia: "zohobooks"andzohobooks: { tenantId, billId, contactId, invoiceNumber }: the organization id, the bill's id, its vendor's id and its number in Zoho Books. A vendor added with it is acreate_counterpartyentry withvia: "zohobooks"andzohobooks: { tenantId, contactId }. A bill partly paid in Zoho Books is added at what is left to pay. - Nothing is booked in Zoho Books, so a Zoho Books connection writes no
accounting_payment_account_chosenand noaccounting_payment_entries. Nothing else in/api/v1or the webhooks changes.
2026-10-15: A release Circle took is recorded in the cycle that finds it
- When the agent finds on Circle a batch whose answer was lost, while reconciling one of its milestones, Circle's transaction is recorded on every member at once. The batch's other milestones, reconciled later in the same cycle, now get a
milestone_reconcileentry withreconciled: trueand theirexecution.resultingStatus("paid"once confirmed). They used to get one withreconciled: falseandreconcileError: "another request is settling this payment's send right now; it is reconciled next cycle", and were recorded paid only on the next cycle. The same holds for any payment whose send another lookup recorded after the cycle read it. - A release from an escrow hold already sent is now only read and recorded, and the hold is marked released once Circle confirms it, even when the hold pays an address that is no longer the contractor's: the release went where the hold pays. Its
milestone_reconcileentry hasreconciled: trueandexecution.resultingStatus: "paid". It used to get, every cycle, one withreconciled: false,execution.resultingStatus: "verified"and areconcileErrorsaying to refund the hold and pay again, though the release had gone out. A person's Pay now that only checks such a release records it the same way. Only a new release from such a hold is held for a person, as before. - A webhook endpoint receives these entries as
ledger.appended, as before. Nothing else in/api/v1or the webhooks changes.
2026-10-15: A reconcile looks for an unanswered send before it holds one
- The agent now looks a payment's earlier send up at Circle before anything would hold it or decide it again, when that send's answer was lost: a claim that went stale with no Circle id, and a send recorded failed because Circle never answered it (the call ran out of time, Circle answered 5xx or with no id). When Circle had taken the transfer, the payment gets an
ap_reconcileormilestone_reconcileentry withreconciled: trueandexecution.resultingStatus"paid"(or still"matched","verified"for a milestone). Before, a stale claim's entry could carrynotResubmittedBecause("counterparty.high_risk","counterparty.new_payee","workspace.two_approvals") withexecution.resultingStatus: "held", and a failed send was decided again, so its entry was a decision (ap_…,milestone_…) about a payment that had already moved. A webhook endpoint receives each asledger.appended, as before. - When Circle has not listed the send yet, could not be asked, or another request is settling it, the entry has
reconciled: false,reconcileErrorsaying which (for example "Circle has not listed this payment's earlier send yet; it is looked for again from 10:15 UTC, and sent again only if Circle has none"), andexecution.resultingStatus"matched"("verified"for a milestone): the payment's status does not change, and the next cycle looks again. This is the shape a reconcile that could not read a transfer already had. - When Circle never took it, a stale claim is checked and sent again, as before, and a failed send is decided again: its entry is that decision. For a bill, that decision is as before. A milestone release decided again this way is now weighed against the operating wallet's cash, as any new release is, and can be held with
execution.heldBecause: "cash_shortfall". This corrects the 2026-10-06 entry "A milestone release waits for its cash", which said a release whose last send Circle never answered is not held for cash: that holds only until Circle is known never to have taken it, and one Circle took is reconciled, never decided again. - A payout to another chain cannot be looked up by its reference. A stale claim's is checked before it is asked for again under its payment key, so its entry can still carry
notResubmittedBecauseand"held"while Circle may hold the transfer; a failed one's is decided again, as before. - With no operating account to look from, such a payment gets no entry: it stays
matched(verified), as a transfer already sent does. - So
notResubmittedBecauseis now recorded only once Circle has no transfer for the earlier send, or for a payout to another chain. Nothing else in/api/v1or the webhooks changes.
2026-10-15: A payment sent again is held when it would be a new payee's first
- An
ap_reconcileormilestone_reconcileentry can now carrynotResubmittedBecause: "counterparty.new_payee", withexecution.resultingStatus: "held". This is a payment whose earlier send's outcome was never recorded: no Circle transaction id was kept for it. Before, the agent looked that send up at Circle and, if Circle had none, sent the payment again to the payee's address as it stands now. Now, when sending it again would be the first payment to that payee at that address with two different people not behind it, the agent holds it for a person instead: once Circle has none (the entry above: the send is looked up first), or, for a payout to another chain, which cannot be looked up this way, before it is asked for again. A webhook endpoint receives that entry asledger.appended, in place of one recording the new send. - A person's Approve and pay, or Pay now on a milestone, looks the earlier send up at Circle first: a transfer Circle took is recorded as it stands, and nothing new is sent until Circle has answered.
- Such an entry also carries the hold as a decision records it:
guardrailBlocked: true,guardrailRule: "counterparty.new_payee", andnewPayee, the same{ addressBy, linkCreatedBy?, bountyBy?, confirmedBy, unanswered?, twoParties }a decision records asobserved.newPayee. It still carries noobserved. - A transfer recorded with its Circle transaction id is only read, and its reconcile entry is unchanged. Nothing else in
/api/v1or the webhooks changes.
2026-10-15: Who asked for a payee's address counts as having given it
- The member who created a payee link, in the console or with Create a payee link (the member who issued the key), now counts as having given the address the payee sends through it. When that member is also the only one who confirmed the address, the agent holds the first payment to it with the rule
counterparty.new_payee(guardrailBlocked: true,execution.resultingStatus: "held"), where it used to pay it. A webhook endpoint then receives that hold's entry asledger.appended, in place of a payment's. When another member confirmed the address, the agent pays it as before. - That member is read from the link's signed
payee_link_createdentry, so deleting their account changes nothing; only when that entry is missing is the link's own record read. - For an address sent with
/paytoon GitHub, and for any address no member can be named as having given, no confirmation counts as the second person: the agent always holds its first payment ascounterparty.new_payee, where it used to pay one a member confirmed. The decision recordsobserved.newPayee.unanswered: true, and its reasoning says one member confirms the address and a different one approves it. A bounty typed by its pull request's own author names no member. - A first payment is now the first to that payee at that address. An address the workspace has paid for another counterparty no longer lets the agent skip the second person for this one, so a first payment it used to make on its own may be held as
counterparty.new_payee. - A decision on the first payment to an address a member asked for records
observed.newPayee.linkCreatedBy(a payee link) orobserved.newPayee.bountyBy(the member a GitHub bounty acts as), besideaddressBy: "payee",confirmedByandtwoParties. Each is absent for an address given any other way, and when no member can be named. approval_paidandmilestone_approval_paidgainaddressGiverApproved: true, and their summary a note, when the workspace's only approver made a first payment to an address no other member stands behind: one they gave, asked for or confirmed, or one no one else confirmed.- Nothing else in
/api/v1or the webhooks changes.POST /api/v1/payee-linkstakes and answers the same.
2026-10-15: Invoices captured with the Chrome extension
- An owner or admin can capture invoices with the Chrome extension Vestiarion Invoice Capture, as drafts that an owner or admin then adds as bills in the console. Five new entries, each listed by
GET /api/v1/ledgerand sent to webhook endpoints asledger.appended:extension_connected, actorhuman, domainsystem:{ by, connectionId, client, scopes }, when a member allowed the extension.clientis the Chrome extension's id;scopesareinvoice_draft:createandinvoice_draft:reador one of them. No token is ever recorded.extension_disconnected, actorhuman, domainsystem:{ by, connectionId, client, reason }.reasonisextension(its own Disconnect),settings(Disconnect in Settings,bynaming who),reused_code(a one-time code was used twice, so the connection it made was ended),reused_refresh(a refresh token was used again after it was replaced, or twice at once),role_changed(the member's role can no longer add bills), or, when the membership ended and its connections with it,member_removed(bynaming who removed them),member_leftoraccount_deleted.byis null forreused_code,reused_refreshandrole_changed.invoice_draft_captured, actorhuman, domainap:{ by, draftId, source, document, connectionId }, when a draft was sent for review.sourceisselectionorfile;documentis{ kind, sha256 },kindbeingpdf,email,textorimage, or null. The fields and the captured text are never in it.invoice_draft_confirmed, actorhuman, domainap:{ by, draftId, invoiceId }, after the bill's owncreate_invoice; in the rare case the bill was written and itscreate_invoiceentry was not, this entry still links the draft to it.invoice_draft_discarded, actorhuman, domainap:{ by, draftId }.
- A
create_invoiceentry for a bill added from a captured draft namesvia: "chrome",invoiceDraftIdand, when one was read,invoiceNumber, withdocumentas one added from a document carries it. - Nothing changes in
/api/v1: a draft is not an invoice, andGET /api/v1/invoiceslists a captured invoice only once a person added it. The extension's own endpoints, under/api/extension/v1, take only its tokens; they are not part of this API, and an extension token is refused by/api/v1and the MCP server.
2026-10-15: New connector consent versions
- Any new connection or reconnection of Xero, QuickBooks, HubSpot or Pipedrive now carries
consent.versionxero-2026-10-15,quickbooks-2026-10-15,hubspot-2026-10-15orpipedrive-2026-10-15in itsaccounting_connectedentry, withreconnected: trueon a reconnect. That includes the reconnects behind Allow Vestiarion to book payments and Allow writing to HubSpot. The new words say the agent's model provider sees a bill's facts, or may see a deal's, under that provider's own API terms, where the earlier versions promised it would not train on them; Pipedrive's also says disconnecting revokes Vestiarion's access, which, as Pipedrive documents it, uninstalls the app. Asana's staysasana-2026-10-14. - An existing connection keeps the version it agreed to, on the connection and in its entries, until it reconnects.
accounting_payment_approvedmay name an accountant inbyon a Xero connection agreed underxero-2026-10-13orxero-2026-10-15. - The version recorded is the one the connect page showed. A page loaded before the words changed is sent back to be read again, and nothing is recorded until the person agrees to the current words.
- Nothing else in
/api/v1or the webhooks changes.
2026-10-15: Postman collections, and the MCP server described for the MCP Registry
- Two Postman collections and an environment, generated from the OpenAPI document and served under
https://www.vestiarion.xyz/postman/. "Vestiarion: Getting Started" goes from a key to a first200, then adds a counterparty, at a wallet you set, and an invoice for it. "Vestiarion API reference" has every operation, with a saved example of its success and of each error it documents. Both authenticate with{{apiKey}}from the environment, and no file holds a key. Use Vestiarion from Postman says how to import them. They call the endpoints as they are: no endpoint changes. - Both collections are also in a public Postman workspace, Vestiarion API, to fork or watch. Its copy is updated by hand after an API change, so importing by link from the site still always gets the latest version; see From the public workspace.
- The example answer of Create a payee link, on its reference page and in
/api/v1/openapi.json, now shows an invented token inurlin place of a real, expired one. The answer's shape is unchanged. server.json, at the repository root, describes the MCP server athttps://www.vestiarion.xyz/api/mcpfor the official MCP Registry, asio.github.duongnq2798/vestiarion, with the API key as a required, secretAuthorizationheader. The server, its tools and how they authenticate are unchanged. The MCP page now says which key to use: a read-only key by default, a read-and-write key for an agent that should add records.- The MCP server is listed in the official MCP Registry as
io.github.duongnq2798/vestiarion, version 1.0.0, so a client that reads the registry can find it. It still needs a workspace API key as the bearer token, read-only by default; see In the MCP Registry. - Nothing else in
/api/v1, the MCP server or the webhooks changes.
2026-10-14: Status says unavailable while payments are switched off
GET /api/v1/statusnow answersprovenance.payments: "unavailable", andprovenance.yield: "unavailable", while payments are switched off for every workspace on the deployment, or while whether they are could not be read. Before, it answered the workspace's chain mode,liveorsimulate, although nothing was paid. The other reasons forunavailableare unchanged; see Get status.- A shadow-mode workspace still answers its chain mode: a payment a person agrees to is paid as
provenance.paymentssays. - Each
approval_returnedentry may now carryreason, the line a person gave when they returned a bill to the agent, asapproval_rejectedalready could. It is absent when none was given. - A
decision_verdictentry for a disagreement may now carryreason: null: a reason is asked for, and no longer required. - Nothing else in
/api/v1or the webhooks changes. The TypeScript SDK 0.3.4 describes the new reason forunavailableinprovenance's comment; its types are unchanged.
2026-10-14: Commissions on money received
- An owner or admin can set a commission plan for a vendor or contractor, which earns a commission on customer money applied to the invoices of the deals the plan covers, and turn what a partner is due into a payable. Five new entries, domain
ap, each listed byGET /api/v1/ledgerand sent to webhook endpoints asledger.appended. Amounts are decimal numbers in the line's currency,USDCorEURC; rates are in basis points (1250is 12.5%) and asratePercent, such as"12.5%".commission_plan_set, actorhuman:{ by, planId, replaces, beneficiaryId, beneficiaryName, beneficiaryMember, rateBps, ratePercent, basis, scope, dealIds, holdDays, reference, startedAt }.basisisnet(money that arrived on Arc) orgross(also a difference recorded as a fee on the invoice);scopeisall_dealsorchosen_deals, withdealIdsfor the latter.replacesis the version this one ended, or null.beneficiaryMemberis the user id of the member who is this partner, or null.commission_plan_ended, actorhuman:{ by, planId, beneficiaryId, beneficiaryName, endedAt }.commission_accrued, actoragent:{ lineId, planId, beneficiaryId, receivableId, dealId, source, allocationId, transferId, base, rateBps, ratePercent, basis, amount, currency, appliedAt, dueAt, formula }, once for each payment applied to a receivable of a covered deal.sourceispayment(a payment applied, part or all),fee(a fee recorded on the invoice, gross only) orwhole_match(a transfer matched to the invoice in full, with noallocationId).amountisbasetimes the rate, rounded down to the millionth;dueAtisappliedAtplus the plan's hold window. The receivable is namedreceivableId, neverinvoiceId.commission_adjusted, actoragent:{ lineId, adjusts, planId, beneficiaryId, receivableId, dealId, source, reversalId, transferId, amount, currency, appliedAt, dueAt, carriedForward, reason }, when the money a commission was earned on was taken back off the receivable.amountis minus the adjusted commission's;reasonisallocation_reversed(reversalIdnames the reversal) orwhole_match_released;carriedForwardis true when the commission was already in a payable, so it comes off the next one.commission_payable_created, actorhuman:{ by, payoutId, statement, payableId, beneficiaryId, beneficiaryName, amount, currency, lineIds, accrued, adjusted }. The payable's owncreate_invoiceentry comes first, withvia: "commission",commission: { payoutId, statement }and the statement number, such asCS-7F3A21C9, as itspoReference.
- A commission payable is a payable like any other in
GET /api/v1/invoices, and the agent'sap_pay,ap_scheduleandap_holdentries decide it as any bill. A person's approval of it by the member named as the partner is refused; there is no newapproval_*entry. - Nothing else in
/api/v1changes: plans and commissions are not in the API.
2026-10-14: Contractor work accepted from Asana
- A milestone's
verificationMethodmay now beasana, inGET /api/v1/milestonesand on its own page: the work was accepted by a person against the milestone's acceptance criteria once its Asana task was completed. ItsverificationDetailis{ note, asanaTask, taskGid, completedAt, fingerprint, criteriaSha256, acceptedBy }; once an acceptance is taken back it also carriesheldReasonandheldAt,verifiedis false,verificationStatusisunverifiedandstatusispendingagain. The TypeScript SDK 0.3.3 accepts the value. - Six new entries, domain
contractor, each listed byGET /api/v1/ledgerand sent to webhook endpoints asledger.appended:asana_task_linked, actorhuman:{ by, milestoneId, linkId, taskGid, workspaceGid, projectGid, taskUrl, completed, fingerprint }.asana_task_unlinked, actorhuman:{ by, milestoneId, linkId, taskGid, withdrewAcceptance }.milestone_criteria_set, actorhuman:{ by, milestoneId, criteria, criteriaSha256, previousSha256 }.previousSha256is null the first time.asana_task_ready, actorsystem:{ milestoneId, linkId, taskGid, completedAt, completedByName, fingerprint, deliverables }, when a linked task is completed in Asana and the milestone has criteria. It verifies nothing:deliverablesis a count.milestone_accepted, actorhuman:{ by, milestoneId, linkId, taskGid, taskUrl, completedAt, completedByName, fingerprint, deliverables, criteriaSha256, payeeAsanaMapped }, when a person accepted the work.deliverableslists each{ kind, label, href }accepted,kindbeingattachment,linkorcomment_link;fingerprintis the SHA-256 of that set.milestone_acceptance_withdrawn, actorsystem:{ milestoneId, linkId, taskGid, reason, afterPayment, acceptedFingerprint, fingerprint, completed, completedAt }, when the task was reopened, its deliverables changed or Asana no longer showed it after the work was accepted.reasonisreopened,deliverable_changedortask_unreachable. WithafterPayment: falsethe milestone lost its verification before any payment; withafterPayment: truea payment was already sent, and is not taken back.
- A new Asana connection's
accounting_connectedcarriesprovider: "asana"andconsent.versionasana-2026-10-14; itsexternalOrgIdis the Asana user who connected. - Nothing else in
/api/v1changes: a milestone is not linked to an Asana task through the API, and the write API still adds a milestone pending.
2026-10-14: A command-line interface over the API
@vestiarion/cli0.1.0, thevestiarioncommand, calls/api/v1with a workspace API key, through the TypeScript SDK. Each command is one or two existing operations; the CLI page maps each command to its operation. It adds no endpoint and changes none.- Its requests are like any other client's: the key as
Authorization: Bearer, and aUser-Agentofvestiarion-cli/0.1.0followed by the SDK's own, such asvestiarion-sdk-js/0.3.2. A write carries anIdempotency-Key, the caller's own with--idempotency-key, except a payee link. vestiarion loginchecks a key with oneGET /api/v1/statusbefore saving it, andvestiarion whoamireadsGET /api/v1/statusandGET /api/v1/treasury, so a key's Last used time in Settings moves when either runs.- Offline,
vestiarion ledger verifychecks an audit export asverify-ledger-export.mjsdoes, andvestiarion webhooks verifychecks a delivery'sVestiarion-Signature. - Nothing in
/api/v1or the webhooks changes.
2026-10-14: Deals brought in from Pipedrive
- An owner or admin can connect a workspace to a Pipedrive company, and a person plans the collections of the won deals it brings in. There is no new kind of entry: the entries HubSpot's deals use now also name Pipedrive. Each is listed by
GET /api/v1/ledgerand sent to webhook endpoints asledger.appended:accounting_connectedandaccounting_disconnectedwithprovider: "pipedrive";externalOrgIdis the Pipedrive company id andexternalOrgNameits name. A Pipedrive connection'sconsent.versionispipedrive-2026-10-14.deal_signed, for a deal planned from Pipedrive, anddeal_revised, for a change saved from what Pipedrive changed, withvia: "pipedrive"andpipedrive: { companyId, dealId, organizationId }, Pipedrive's own ids. The deal'sexternalRefispipedrive-followed by Pipedrive's deal id, such aspipedrive-482.create_counterparty, for a customer added with such a deal, andcounterparty_notice_email_changed, for a billing email filled from Pipedrive, withvia: "pipedrive"andpipedrive: { companyId, organizationId }; the addresses are masked, as before.crm_deal_changedandcrm_deal_change_keptwithprovider: "pipedrive";crmDealIdis Pipedrive's deal id, without thepipedrive-prefix. Astagechange'slabelis the stage's name, or the lost reason for a deal marked lost.crm_receipt_writes_changed,crm_receipt_written,crm_receipt_conflict,crm_receipt_failed,crm_receipt_refusedandcrm_receipt_overwrite_chosenwithprovider: "pipedrive".fieldsandconflictsuse the same keys as for HubSpot (vestiarion_collectedand the rest), whatever the fields are called in Pipedrive.accountTypeisCOMPANY: Pipedrive names no developer sandbox, so payments on Arc testnet or in shadow mode are never written to it, and a write queued for them ends incrm_receipt_refusedwithreason: "reality".
- Nothing else in
/api/v1changes: the Pipedrive deals not planned are not in the API.
2026-10-13: A reporting currency, and cash scenarios saved as versions
- Two new entries, actor
human, each listed byGET /api/v1/ledgerand sent to webhook endpoints asledger.appended:reporting_currency_changed, domainsystem:{ by, from, to }, when an owner or admin set the currency the workspace reports and plans in.toisUSD,EUR,SGD,JPY,KRW,PHPorMYR;fromis the one before, or null the first time.cash_scenario_saved, domaintreasury:{ by, scenarioId, versionId, version, name, horizon, lateDays, costPct, costScope, receivablesChanged, rates, reportingCurrency }, when an owner or admin saved a cash scenario. Each save is the nextversionofscenarioId, from 1.rateslists each rate typed,{ currency, perUsd, reference }:perUsdis how many of the currency make one US dollar, as a decimal string, andreferenceis{ perUsd, source, at }, the reference rate shown beside it, or null.
- Nothing else in
/api/v1changes: invoices are still in USDC or EURC, and a payment still carries the amount the bill was converted to. The rates, the reporting currency and the FX variance on paid bills are not in the API.
2026-10-13: Collections that follow the customer's context
- Before it reminds a customer, the agent proposes each receivable's next step from what the customer said, paid and was promised, its own rules and the HubSpot deal it was sold through, and asks a person when the step is theirs. Three new entries, domain
ar, each listed byGET /api/v1/ledgerand sent to webhook endpoints asledger.appended:collection_policy_set, actorhuman:{ by, counterpartyId, version, approval, maxTone, minDaysBetween, channel, accountOwner }, when a person saved a customer's rules.approvalisautoorask_first;maxToneisfriendly,firmorfinal;minDaysBetweenis 3 to 30;channelisemail;accountOwneris a member's user id or null. Each save is the nextversion.collection_task_opened, actoragent:{ taskId, invoiceId, counterpartyId, kind, reason, policyVersion, reasons }, withreminder: { number, tone }when the task is about a drafted reminder.kindisask_ownerorfinance_review;reasonispolicy_ask_first,hubspot_owner,no_contact,promise_passed,claim_unverified(a claim of payment still open 7 days after the customer made it) orreminders_done;reasonslists the codes of the facts the step rests on. A need that was already so before the agent first ran in the workspace with this change opens no task and has no entry.collection_task_resolved, actorhuman:{ by, taskId, invoiceId, counterpartyId, reason, outcome, policyVersion }, withholdUntil(YYYY-MM-DD) for a hold andreminder: { number, tone }for an approval.outcomeisapproved,held,no_reminder,resumedordone.
ar_reminder_sentandar_reminder_deferredgaincontext: { policyVersion, reasons }. A reminder a person approved is anar_reminder_sentwithdecisionMode: "person",agreedWithReference: null,approvedTaskIdandapprovedBy.- A customer's open claim of payment now holds the agent's reminders until it is closed, finance being asked after 7 days, and a promise whose day passed holds them until finance reviews it: fewer
ar_reminder_sententries follow such a request. Resolving aclaim_unverifiedtask closes the claim asnot_received, acustomer_request_closedentry before thecollection_task_resolvedone. - Nothing else in
/api/v1changes: rules and tasks are not in the API.
2026-10-13: Project budgets, and the same work billed twice
- An owner or admin can make projects, each with a budget and a buffer in USDC, and anyone who adds bills can put a bill, a milestone or a deal in one. A project's budget is an earmark in Vestiarion: nothing is locked on chain. Three new entries, actor
human, domainap, each listed byGET /api/v1/ledgerand sent to webhook endpoints asledger.appended. Amounts are USDC;…Minorfields are in cents and the others decimal strings.project_created{ by, projectId, name, currency, budget, budgetMinor, buffer, bufferMinor, status }.currencyisUSDC;statusisactive.project_changed{ by, projectId, before, after }, each ofbeforeandafterthe fields ofproject_createdbutbyandprojectId. Archiving setsafter.statustoarchived; reopening, toactive.project_assigned{ by, subject, subjectId, projectId, projectName, previousProjectId, reservation }, when a bill (subject: "invoice",subjectIdan invoice id), a milestone or a deal is put in a project or taken out of one (projectIdnull).via: "entry"when the project was chosen as the bill or milestone was added.reservationis null for a deal, a removal, or when the reservation could not be made, and otherwise{ state, neededMinor, availableMinor, reservedMinor, paidMinor }:stateisreserved(the money was set aside),over(the budget could not hold it; nothing was set aside), orarchived,settledorno_project. The entry names the bill assubjectId, neverinvoiceId, so it is not taken for a decision on it.
- Two new values of
guardrailRuleon the agent'sap_pay,ap_scheduleandmilestone_releaseentries, each withguardrailBlocked: trueandexecution.resultingStatus: "held". Both run after every other rule, and only on a payment the others let through:project.budget_exceeded: the bill or milestone is in a project whose budget, less its buffer, less what is set aside and paid, cannot hold it.observed.projectis{ id, name, state, neededMinor, budgetMinor, bufferMinor, reservedMinor, paidMinor, availableMinor }, withstateoverorarchived, andexecution.heldBecauseisproject_budgetforover; or{ id, state: "unreadable" }when the project could not be read.obligation.duplicate_reference: a bill names the same purchase order, for the same payee, as an earlier milestone, or a milestone as an earlier bill; or one links the same delivered work as the other.observed.sameWorklists each{ otherKind, otherId, otherStatus, signal, reference, finding },signalpurchase_orderordeliverable.
- On every agent decision about a bill or milestone in a project,
observed.projectIdnames the project, andobserved.projectrecords what its reservation found (state: "reserved", withalready) when the payment went ahead;observed.sameWorkis recorded whenever an earlier bill or milestone for the same work exists, whatever held the decision. A milestone'screate_milestoneentry carriespoReferencewhen one was entered. - A new value of
execution.heldBecause,project_budget. The follow-up decides such a payment again once its project has room, with aninvoice_reopenedormilestone_reopenedentry whosefollowUp.changessays so. - Nothing else in
/api/v1changes:GET /api/v1/invoicesand the milestones routes return a bill or milestone in a project as before, and the write API takes no project or milestone purchase order.
2026-10-13: An accountant role, and a month's hand-off
- A member's role may now be
accountant, wherever an entry names one:roleinmember_invitedandmember_joined, and the roles inmember_role_changed. An accountant reads the workspace, books payments in the accounting tool and applies money received; it decides no payment. - A new entry, actor
human, domainsystem, listed byGET /api/v1/ledgerand sent to webhook endpoints asledger.appended:handoff_exported{ by, format, month, decisions, payments, bookings, openItems, headSeq }, when a member downloads a workspace's hand-off for a month.formatiscsvorjson;monthis YYYY-MM; the counts are how many rows of each section it held;headSeqis the ledger's last entry when it was made. - A new Xero connection's
accounting_connectedcarriesconsent.versionxero-2026-10-13, whose words say an owner, admin or accountant approves what is booked.accounting_payment_approvedmay now name an accountant inby, on a connection agreed under that version. - Nothing else in
/api/v1changes.
2026-10-13: A deal's planned costs, and held bills escalated past their day
- A person can enter a deal's planned costs, remove one, and link one to the payable or milestone it became. Its ledger gains three entries, actor
human, domainar, each listed byGET /api/v1/ledgerand sent to webhook endpoints asledger.appended:deal_cost_added{ by, dealId, title, costId, label, counterpartyId, counterpartyName, currency, digits, amount, amountMinor, expectedOn, noDocument }.currencyanddigitsare the deal's;amountis a decimal string andamountMinorthe same in minor units;expectedOnis YYYY-MM-DD;counterpartyIdandcounterpartyNameare null when nobody was named;noDocumentis true when no bill or quote backs it yet.deal_cost_removed, the same fields pluslinked: null, or{ kind, id }for the payable (kind: "payable", an invoice id) or milestone it was linked to. A removed cost stays in the deal's record and counts nowhere.deal_cost_linked, the same fields pluslinked: { kind, id, amount, amountMinor, status }: the payable or milestone the cost became, its amount in the deal's currency and its status when it was linked. A payable or milestone backs one cost at a time.
- A new entry, actor
system, domainsystem, listed and sent the same way:decision_escalated{ invoiceIds, decideBy, recipients, failed }, when the members who can decide payments were emailed about held payables that passed the day they were to be decided by.decideBymaps each invoice id to that day (YYYY-MM-DD);recipientsandfailedare counts. A payable is escalated once for each such day, and only for a day on or after the first scheduled cycle that ran escalations in the workspace: payables already past their day then are never escalated. - Nothing else in
/api/v1changes: a planned cost is not an invoice, andGET /api/v1/invoicesreturns a linked payable as before.
2026-10-13: Customer statements and what customers say on them
- An owner or admin can send a customer a link to its own statement, where the customer pays an invoice through its pay link, or says it paid, promises a day, disputes an invoice or asks for a pay link. Nine new entries, domain
ar, each listed byGET /api/v1/ledgerand sent to webhook endpoints asledger.appended. None changes an invoice: a customer saying it paid is its word, and the invoice stayspendinguntil the payment arrives and is applied.customer_statement_shared, actorhuman:{ by, linkId, counterpartyId, expiresAt, days, replaced }.daysis 7, 30 or 90;replacedlists the ids of the customer's earlier links this one stopped. The link itself is never in the entry.customer_statement_unshared, actorhuman:{ by, linkId, counterpartyId }.customer_said_paid,customer_promised_payment,customer_disputed_invoiceandcustomer_asked_pay_link, actorhumanwith noby:{ via: "customer_portal", linkId, requestId, invoiceId, counterpartyId, kind }, withpaidOn(YYYY-MM-DD), andamountandcurrencywhen the customer gave an amount, forcustomer_said_paid;promisedOnforcustomer_promised_payment;superseded, the ids of the customer's earlier open requests of the same kind on that invoice it replaced; andtextSha256, the SHA-256 of what the customer wrote (its reference and message, joined by a line break), never the words.kindispaid,promise,disputeorpay_link.customer_wrote, actorhumanwith noby: the customer wrote more under an open request.{ via: "customer_portal", linkId, requestId, invoiceId, counterpartyId, kind, textSha256 }, withmessageIdfor a message written under the request; a second dispute or pay link request on the same invoice, added to the open one, has none. Asking again for a pay link already asked for, with no words, writes nothing and adds no entry.customer_request_replied, actorhuman:{ by, requestId, messageId, invoiceId, counterpartyId, kind, textSha256 }.customer_request_closed, actorhuman:{ by, requestId, invoiceId, counterpartyId, kind, outcome }.outcomeisresolved, ornot_receivedfor a claim of payment the business has not received.
- Nothing else in
/api/v1changes: the statements and what customers said are not in the API.
2026-10-13: Receipts written back to HubSpot, and notes that say what is known
- An owner or admin can turn on writing receipts to HubSpot. Each deal planned from HubSpot then gets, in HubSpot deal properties of a
vestiariongroup: what was collected from payments confirmed on Arc and applied to its invoices, what is still owed, the currency, a collection status, the last receipt's day, amount and transaction link, a reconciliation status and a link to the deal. Payments on Arc testnet or in shadow mode are written only to a HubSpot developer test account or sandbox. Six new entries, each listed byGET /api/v1/ledgerand sent to webhook endpoints asledger.appended:crm_receipt_writes_changed, actorhuman, domainsystem:{ by, provider, connectionId, externalOrgId, on, scopes }, when writing was turned on or off.crm_receipt_written, actorsystem, domainar:{ provider, connectionId, externalOrgId, writeId, dealId, crmDealId, fields, writtenAt, adopted, network, shadow, accountType }, once HubSpot read the write back the same.crmDealIdis HubSpot's deal id anddealIdthe Vestiarion deal;fieldsholds each property's value as HubSpot read it back (vestiarion_collected,vestiarion_still_owed,vestiarion_currency,vestiarion_collection_status,vestiarion_last_receipt_date,vestiarion_last_receipt_amount,vestiarion_last_receipt_link,vestiarion_reconciliation,vestiarion_evidence_link), amounts as decimal strings in the deal's currency;adoptedis true when HubSpot already held them;accountTypeis HubSpot's (DEVELOPER_TEST,SANDBOX,STANDARD).crm_receipt_conflict, actorsystem, domainar:{ provider, connectionId, externalOrgId, writeId, dealId, crmDealId, conflicts }, when someone changed a field in HubSpot since Vestiarion last wrote it; nothing is written over it. Each ofconflictsis{ field, ours, theirs, next }.crm_receipt_failed, actorsystem, domainar:{ …, reason, message, retryAt }, once per write, at its first failure;reasonisno_answer,rate_limited,reconnect,refused_by_crmorfields. It is tried again on its own.crm_receipt_refused, actorsystem, domainar:{ …, reason, message }, final;reasonisreality(withnetwork,shadowandaccountType) ordeal_gone.crm_receipt_overwrite_chosen, actorhuman, domainar:{ by, writeId, dealId, crmDealId, connectionId, seen }, when a person chose to write Vestiarion's figures over what HubSpot held (seen).
- A new HubSpot connection's
accounting_connectedcarriesconsent.versionhubspot-2026-10-13, and itsscopesincludecrm.objects.deals.writeandcrm.schemas.deals.writewhen writing was allowed. - An invoice's or a milestone's
agentReasoningnotes a person's payment as paid only once Circle confirmed it:[approved and paid by a person]and[paid now by a person]as before when it was confirmed;[approved by a person; payment submitted]while Circle has not confirmed it, and[approved by a person; payment not confirmed]when it did not go through. Notes written before stay as they are. - Nothing else in
/api/v1changes.
2026-10-12: Deals brought in from HubSpot
- An owner or admin can connect a workspace to a HubSpot account, and a person plans the collections of the won deals it brings in. Connecting and disconnecting are the
accounting_connectedandaccounting_disconnectedentries the Xero connector added, withprovider: "hubspot";externalOrgIdis the HubSpot account (hub) id andexternalOrgNameits domain. - A deal planned from HubSpot is a
deal_signedentry as any deal, withvia: "hubspot"andhubspot: { hubId, dealId, companyId }, HubSpot's own ids; itsexternalRefis HubSpot's deal id. A change saved from what HubSpot changed is adeal_revisedentry with the sameviaandhubspot. A customer added with the deal is acreate_counterpartyentry withvia: "hubspot"andhubspot: { hubId, companyId }. - Two new entries, domain
ar, each sent to webhook endpoints asledger.appendedand listed byGET /api/v1/ledger:crm_deal_changed, actorsystem:{ provider, connectionId, externalOrgId, crmDealId, dealId, changes }, once for each new set of changes HubSpot made to a planned deal.crmDealIdis HubSpot's deal id anddealIdthe Vestiarion deal. Each ofchangesis{ what: "amount", from: { amount, currency }, to: { amount, currency } },{ what: "close", from, to }(days as YYYY-MM-DD, or null),{ what: "stage", from, to, label }(won,openorlost, and HubSpot's stage label), or{ what: "deleted" }. Nothing in Vestiarion changes with it.crm_deal_change_kept, actorhuman:{ by, provider, connectionId, crmDealId, dealId, changes }, when a person kept the deal as it is.
- A billing email filled from HubSpot is a
counterparty_notice_email_changedentry, as one typed in, withvia: "hubspot"andhubspot: { hubId, companyId }; its addresses are masked, as before. - Nothing else in
/api/v1changes: the HubSpot deals not planned are not in the API.
2026-10-12: Payments made on Arc booked in Xero, after a person reviews them
- When a payable added from a Xero bill is paid on Arc and confirmed, Vestiarion drafts its booking against that bill in Xero; an owner or admin reviews it on Bills & receivables and approves it, and only then is it written to Xero. A payment on Arc testnet, and every payment in shadow mode, is booked only into an organisation Xero calls a demo company. Its ledger gains six entries, domain
ap, each naming the payable asinvoiceId, listed byGET /api/v1/ledgerand sent to webhook endpoints asledger.appended:accounting_payment_drafted, actorsystem:{ provider, connectionId, externalOrgId, postingId, invoiceId, billId, amount, currency, paidOn, reference, network, shadow, paidAmount, paidToken, networkFee }.amountandcurrencyare what will be booked, in the bill's currency (USDC as USD, EURC as EUR; a shadow bill at its own amount);paidOnis the day the payment was confirmed (YYYY-MM-DD, UTC);referenceis the Arc transaction hash;paidAmountandpaidTokenare what left on Arc;networkFeeis in USDC and is never booked.billIdis the Xero bill (invoice) id.accounting_payment_approved, actorhuman:{ by, provider, connectionId, postingId, invoiceId, account: { id, code, name, currency }, fingerprint, amount, currency, paidOn, reference }.fingerprintis a SHA-256 of exactly what the person was shown.accounting_payment_sent, actorsystem:{ provider, connectionId, postingId, invoiceId, paymentId, adopted }.paymentIdis the Xero payment id;adoptedis true when Xero already held a payment with this reference on the bill, which Vestiarion took instead of writing another.accounting_payment_confirmed, actorsystem:{ provider, connectionId, postingId, invoiceId, paymentId, amount, currency, account, paidOn, reference }, what Xero answered when the payment was read back.accounting_payment_failed, actorsystem:{ provider, connectionId, postingId, invoiceId, reason, message, retryable }.reasonisno_answer,refused_by_provider,rate_limited,reconnectormismatch; approving it again tries once more.accounting_payment_refused, actorsystem:{ provider, connectionId, postingId, invoiceId, billId, reason, message, network, shadow, organisationDemo, amount, currency, reference }.reasonisreality(a payment on Arc testnet or in shadow mode, into an organisation that is not a demo company),already_paid,bill_closed,currencyordeleted_in_provider. It is final: nothing is sent.
- A new Xero connection asks for
accounting.paymentsbeside its read scopes, andaccounting_connected'sscopeslists it; itsconsent.versionisxero-2026-10-12.2. A connection made before reconnects to allow booking. - Nothing else in
/api/v1changes: an invoice's status andtxHashare those of its payment on Arc, booked or not.
2026-10-12: Bills brought in from QuickBooks Online
- An owner or admin can connect a workspace to a QuickBooks Online company, and a person adds the bills it brings in from Bills & receivables. It writes the same five entries as Xero (below), each sent to webhook endpoints as
ledger.appendedand listed byGET /api/v1/ledger, withprovider: "quickbooks".externalOrgIdis the QuickBooks company (realm) id, andbillIdandbillIdsare QuickBooks bill ids.accounting_bill_closedalso comes when a bill already added is deleted in QuickBooks, withsourceStatusdeleted. - A bill added from QuickBooks is a
create_invoiceentry withvia: "quickbooks"andquickbooks: { tenantId, billId, contactId, invoiceNumber }: the company (realm) id, the bill's id, its vendor's id and its number in QuickBooks. A vendor added with it is acreate_counterpartyentry withvia: "quickbooks"andquickbooks: { tenantId, contactId }. A bill partly paid in QuickBooks is added at what is left to pay. accounting_disconnectedgainsatProvider: truewhen a QuickBooks connection was disconnected in QuickBooks itself and QuickBooks confirmed it no longer accepts it; thenrevokedAtProvideristrueand Vestiarion revoked nothing. Without it, the entry is as before.- Nothing else in
/api/v1changes.
2026-10-12: Deals, their versions and the receivables released from them
- An owner or admin can confirm a deal on Bills & receivables: a customer, a total and a schedule of lines that add up to it, each line released as a receivable when it is time to invoice it. Its ledger gains four entries, actor
human, domainar, each listed byGET /api/v1/ledgerand sent to webhook endpoints asledger.appended:deal_signed{ by, dealId, version, counterpartyId, counterpartyName, title, currency, digits, total, totalMinor, startsOn, termsDays, externalRef, template, autoRelease, lines }for version 1.currencyisUSDC,EURC, or a three-letter code in shadow mode;digitsis 2, or 0 for a currency without cents such asJPY;totalis a decimal string andtotalMinorthe same in minor units.templateisdeposit,milestones,retainerorcustom;externalRefis null or the reference given, such as a CRM deal id. Each oflinesis{ lineId, position, kind, label, invoiceOn, dueOn, amount, amountMinor, roundingMinor, replaces }, days as YYYY-MM-DD;roundingMinoris how much of the last line's amount is the rounding remainder.deal_revised, the same deal fields plus{ kind, fromTotal, toTotal, difference, fromTotalMinor, toTotalMinor, reason, ended, added, changes }, for a change (kind: "revised") or a reopen (kind: "reopened").endedlists{ lineId, status }for each planned line it ended (supersededorcancelled);addedlists new lines as indeal_signed, a line thatreplacesanother naming it. A credit owed to the customer is a line withkind: "credit"and a negative amount. A line already released is never inended.deal_cancelled, the same fields asdeal_revised, withkind: "cancelled".deal_auto_release_changed{ by, dealId, title, on }: whether the agent releases each line on its invoice day.
- Releasing a line is a
create_invoiceentry, domainar, as for any receivable, withvia: "deal"anddeal: { dealId, lineId, version, title, line, releasedBy }.releasedByisperson, orschedulewhen the agent's cycle released it on its day, in which case the entry's actor isagentandbyis null. - Nothing else in
/api/v1changes: a deal line not released yet is not an invoice, andGET /api/v1/invoicesreturns the receivable a line became like any other.
2026-10-12: Bills brought in from Xero
- An owner or admin can connect a workspace to a Xero organisation, and a person adds the bills it brings in from Bills & receivables. Its ledger gains five entries, each sent to webhook endpoints as
ledger.appendedand listed byGET /api/v1/ledger:accounting_connected, actorhuman, domainsystem:{ by, provider, connectionId, externalOrgId, externalOrgName, scopes, consent: { version, at }, reconnected }.providerisxero;externalOrgIdis the Xero organisation (tenant) id;consentis the version of what the person agreed to and when they ticked it.accounting_disconnected, actorhuman, domainsystem:{ by, provider, connectionId, externalOrgId, revokedAtProvider }.revokedAtProvideris whether Xero confirmed it ended the app's access.accounting_payment_account_chosen, actorhuman, domainsystem:{ by, provider, connectionId, account: { id, code, name, currency } }, the Xero account payments made on Arc will be booked to. Nothing is written to Xero yet.accounting_bill_closed, actorsystem, domainsystem:{ provider, connectionId, externalOrgId, billId, invoiceId, invoiceNumber, sourceStatus, at }, when a bill already added is paid, voided or deleted in Xero.invoiceIdis the invoice it became;sourceStatusispaid,voidedordeleted. The invoice itself is unchanged.accounting_bills_dismissed, actorhuman, domainap:{ by, provider, connectionId, billIds }, the Xero bill ids a person chose not to add.
- A bill added from Xero is a
create_invoiceentry, as one typed into the form, withvia: "xero"andxero: { tenantId, billId, contactId, invoiceNumber }, Xero's own ids. A supplier added with it is acreate_counterpartyentry withvia: "xero"andxero: { tenantId, contactId }. - Nothing else in
/api/v1changes.
2026-10-12: Money received applied to invoices: part payments, one payment for several invoices, fees
- An owner or admin can apply a payment received on Arc to one or more open receivables of its currency, record a difference as a fee with a reason, and reverse either; the agent applies by itself a payment that is exactly what is still owed on a part-paid receivable. Its ledger gains three entries, domain
ar, each sent to webhook endpoints asledger.appendedand listed byGET /api/v1/ledger, one per invoice touched:ar_payment_applied, actorhuman, oragentfor the rest of a part-paid receivable:{ by, allocationId, invoiceId, counterpartyId, transferId, amount, currency, txHash, from, basis, outstandingAfter, unappliedAfter, group }.amountis what was applied to that invoice;outstandingAfterwhat is still owed on it, 0 once it is paid;unappliedAfterwhat is left of the payment, the client's credit.basisisperson, orsenderoramountfor the agent, asar_received'smatchedBy.groupis the same for the entries one press wrote.suggestion: { rule, why }is added when a person applied a suggestion;byis null for the agent.ar_fee_recorded, actorhuman: the same fields withreason,transferId,txHashandfromnull. A fee is applied to the invoice, never counted as paid by the client.ar_allocation_reversed, actorhuman:{ by, allocationId, reverses, reversedKind, invoiceId, counterpartyId, transferId, amount, currency, txHash, reason, outstandingAfter, unappliedAfter, group }.reversesis theallocationIdreversed andreversedKindispaymentorfee. Nothing is edited: what it applied is owed again.
GET /api/v1/invoiceskeeps its shape. A part-paid receivable keeps its fullamountand the statuspending(ormatched) until what is applied covers it, then becomesreceived, withsettledAtandtxHashfrom the last payment applied. A reversal that leaves something owed on a received receivable makes itpendingagain, withsettledAtandtxHashnull. What was applied is in the entries above.GET /api/v1/treasurykeeps its shape. ItslatestForecast.projectedInflowcounts a part-paid receivable for what is still owed, not its full amount: what arrived is inliquidBalancealready.- A payment matched to one invoice in full is unchanged: one
ar_receivedentry, as before. Nothing else in/api/v1changes.
2026-10-11: A bill moved from the payment plan is a payment_rescheduled entry
- Bills & receivables shows a payment plan for the next 14 days. A member who can approve payments can move a bill the agent scheduled to the day the plan proposes. Its ledger gains
payment_rescheduled, actorhuman, domainap, listed byGET /api/v1/ledgerand sent to webhook endpoints asledger.appended:{ by, invoiceId, counterpartyId, from, to, dueOn, amount, pays, discount, balanceAfter, planFingerprint, lineFingerprint }.fromandtoare the days (YYYY-MM-DD, UTC) the bill was scheduled for and is now;paysis what the plan expects to leave that day, less the early-payment discount when paid by its deadline;discountis{ pct, value, until }or null;balanceAfteris the plan's projected balance after it: the plan only moves a bill to an earlier day within the 14 days it shows.soleApprover: trueis added when the person who entered the bill moved it as the workspace's only approver. - A move is neither a payment nor a decision: the invoice stays
scheduled, with the new day as itsscheduledForinGET /api/v1/invoices, and the agent decides it again on that day with anap_*entry, as for any scheduled bill. - A move to today starts a cycle, whose
cycle_completeentry lists the new event kindplan_approvedinevents. Nothing else in/api/v1changes.
2026-10-11: A report shared by a link, and the value question
- An owner or admin can share the workspace report by a public link, and stop one; an owner can answer how long one bill took before Vestiarion, which the report's value section estimates from. Its ledger gains three entries, actor
human, domainsystem, each sent to webhook endpoints asledger.appendedand listed byGET /api/v1/ledger:report_shared{ by, shareId, options: { names, amounts, title } }: a link was made.namesislabelsorshown,amountsisshownorhidden, andtitleisworkspaceorneutral. The link itself is never in the entry.report_unshared{ by, shareId }: the link with thatshareIdwas stopped.report_baseline_answered{ by, baselineId, minutesPerBill, peoplePerBill }: an owner answered, in whole minutes and people. A changed answer is a new entry; the newest is the one the report reads.
- Nothing else in
/api/v1changes: sharing and the answer are made in the console only.
2026-10-11: What the business paid, from its bank statement
- An owner or admin can fill in what the business paid from its bank statement, on the workspace report: each ticked line of money out is recorded against the bill it paid. Each is an
actual_payment_recordedentry, oractual_payment_correctedwhen the bill had a record, as before, sent to webhook endpoints asledger.appendedand listed byGET /api/v1/ledger. Such a record is a payment bybank_transferon the line's booking day, for its amount and currency, with its reference, and its entry adds:via: "statement".statementLine{ id, account, line, bookedOn, valueOn, amount, currency, description, payee, reference, balance }: the kept line's id, the account as the person named it, the line of the file, the booking day and the value day (YYYY-MM-DD,valueOnnull when the statement has none), the amount as the statement says it (money out negative) incurrency, the bank's description, and the payee, the reference and the running balance after the line, each null when the statement has none.
- Entries without these fields are unchanged. Nothing else in
/api/v1changes.
2026-10-10: A limit applied after trying it records the replay
- A person can try a new payment limit, figure for two approvals or spending limit on the agent's past decisions before saving it. When they apply it from that result, its entry gains
replayin itsdetail:{ windowDays, from, to, decisions, unchanged, nowHeld, nowPaid, nowTwoPeople, cantTell }.windowDaysis 30 or 90,fromandtobound the window, and the counts are the decisions replayed and how their outcome would change. A later decision on a bill the replay already paid counts asunchanged, so each bill moves a count once. - The entries are
counterparty_limit_changed,approval_policy_changedandagent_budget_changed, inGET /api/v1/ledgerand asledger.appendedalike. A change saved without trying it first has noreplay, as before. - Trying a figure writes nothing to the ledger. Nothing else in
/api/v1changes.
2026-10-10: An imported bill is a create_invoice entry
- A bill list imported on Bills & receivables adds each row as a
create_invoiceentry, as an invoice typed into the form, sent to webhook endpoints asledger.appended. Such an entry carriesvia: "import",importFile(the SHA-256 of the list's text as it was sent) andimportRow(the row's number in the list, as the spreadsheet shows it), andinvoiceNumberwhen the row has one. A bill in the business's own currency, in shadow mode, carriesbillas one typed into the form does. - Imports no longer write
import_invoiceentries. Entries already written keep their action. - The invoice number starts the invoice's
memo, for instanceInvoice KP-1042: Copy paper, inGET /api/v1/invoicesas everywhere. Nothing else in/api/v1changes.
2026-10-10: What the business paid outside Vestiarion
- An owner or admin can record how the business paid a payable outside Vestiarion, or that it did not, from the workspace report. Its ledger gains two entries, actor
human, domainap, each sent to webhook endpoints asledger.appendedand listed byGET /api/v1/ledger:actual_payment_recorded{ by, actualId, subject, subjectId, outcome, paidOn, amount, currency, method, reference, note, reason }for a bill's first record.subjectisinvoiceandsubjectIdthe invoice's id.outcomeispaid, withpaidOn(YYYY-MM-DD),amount,currency(three capital letters, orUSDCorEURC) andmethod(bank_transfer,card,cashorother), andreasonnull; ornot_paid, withreasonand the four others null.referenceandnoteare null when none was given.actual_payment_corrected, the same fields plusreplaces, theactualIdof the record it corrects. A record is never changed: the newest of a bill's records is what the business did.- A record from a CSV carries
via: "csv".
- The entry names the payable as
subjectId, neverinvoiceId. Nothing else in/api/v1changes.
2026-10-09: A payable to a payee with no address is held before anything is sent
- Wherever payments are real, an agent decision (
ap_payorap_schedule) about a payable whose counterparty has no payment address is held by a new guardrail rule,counterparty.no_address:guardrailBlocked: true,execution.resultingStatus: "held", andobserved.addressMissing: true. Before, the transfer was tried and failed, and the reasoning carried the provider's error. A sandbox's entries are unchanged. - Once the counterparty has an address and a person confirmed it, the follow-up decides the payable again, with an
invoice_reopenedentry whosechangesinclude "the counterparty now has a confirmed payment address". - Approve and pay refuses such a payable with the error code
no_address: "This payee has no payment address yet. Add it on Counterparties, or ask them for it with a one-time link." Nothing else in/api/v1changes.
2026-10-08: Test USDC for shadow mode
- A workspace in shadow mode on Arc testnet can take the test USDC its open bills need from Vestiarion's float. Its ledger gains
test_usdc_added, actorhuman, domaintreasury, sent to webhook endpoints asledger.appended:{ by, amount, from, to, transferId, txHash, status, shortfall, weeklyLimit }.fromis the float's address andtothe operating wallet's.statusisconfirmed,pendingorfailed, as Circle reported the transfer when the entry was written;txHashisnullwhile Arc testnet still confirms it.shortfallis what the open bills needed, andamountwhat Circle says was sent. - Entries are never updated: a transfer recorded as
pendingstays so in its entry. A later entry withrecovered: trueandby: nullrecords a transfer Vestiarion's float sent whose entry was never written, from Circle's own figures, withshortfall: null. - Each one starts a cycle, whose
cycle_completeentry lists the new event kindtest_usdc_addedinevents. - Money from the float is never matched to a receivable: no
ar_receivedfollows it. Nothing else in/api/v1changes.
2026-10-08: Decisions made in shadow mode say so
- An agent decision entry (
ap_pay,ap_schedule,ap_hold,ap_flag_fraud,ap_request_info) written while the workspace is in shadow mode carriesshadow: truein itsdetail, inGET /api/v1/ledgerand in the webhooks alike. Entries written outside shadow mode are unchanged. - A payment the agent decided in shadow mode that a check in code held (
guardrailBlocked: true) is now settled through a person's verdict, as one shadow mode held: itsdecision_verdictentry precedes anyapproval_paid,approval_rejectedorapproval_returnedfor it.
2026-10-07: A mirror address for a supplier with none, in shadow mode
- In shadow mode, a supplier with no Arc address can be given a mirror address: a wallet Vestiarion makes for it on Arc testnet, in the workspace's own Circle wallet set. The counterparty's
addressis then that wallet's, andchainisARC-TESTNET. - It is recorded as
counterparty_address_changedwithvia: "mirror":{ by, counterpartyId, via, from: null, to, walletId }, actorhuman, domaincompliance. No person typed the address, so the first payment to it does not wait for a second person to confirm it. GET /api/v1/counterpartiesshows the address as any other. Nothing else in/api/v1changes.
2026-10-07: A bill in the business's own currency, in shadow mode
- In shadow mode, a bill typed into the invoice form in the business's own currency is added at its USDC amount, worked out at the day's rate from ExchangeRate-API (a US dollar is one USDC). Its
create_invoiceentry carriesbill{ currency, amount, perUsd, source, at }: the bill as written, how many of its currency made one dollar, where the rate came from, and when it was published.amountandcurrencystay the USDC figure the agent pays. - Nothing else in
/api/v1changes: the API still takes invoices in USDC or EURC.
2026-10-07: Shadow mode: a person agrees with each payment
- A workspace on Arc testnet can run in shadow mode. The business keeps paying its bills as it does today, and the agent pays nothing until a person agrees. Its ledger gains these entries, each sent to webhook endpoints as
ledger.appended:shadow_mode_started{ by, currency }andshadow_mode_ended{ by, currency }, with actorhumanand domainsystem. An owner turned it on for bills incurrency(ISO 4217), or turned it off.ap_payfor a payment held in shadow mode hasexecution.resultingStatus: "held"andexecution.heldBecause: "shadow_verdict", withguardrailBlocked: false: the decision passed every check. Amilestone_releaseheld the same way has the sameheldBecause.decision_verdict{ by, entrySeq, subject, subjectId, agentAction, verdict, reason }, with actorhumanand domainap. A person agreed (verdict: "agree") or disagreed ("disagree") with the agent's decision in entryentrySeq.subjectisinvoice,subjectIdis the invoice's id, andagentActionis the decision's entry action.reasonis the person's words: required for a disagreement,nullfor an agreement given without one.
- A payment a person agrees to is paid first, as Approve and pay pays it, to the address their card showed, with its
approval_paidentry. Itsdecision_verdictfollows once it is paid, or its transfer was tried; a payment refused before anything was sent writes no verdict. A disagreement can return the payable to the agent (approval_returned) or reject it (approval_rejected). Nothing else in/api/v1changes.
2026-10-07: A live treasury's own wallet changes its figures, or stops the agent
- Once a workspace that pays from its owner's own wallet is live on Arc mainnet, the owner or an admin can change the contract's figures, stop the agent's payments, and resume them from Go live. The treasury's own wallet sends each change. Each is recorded once per transaction, from the chain only, when the transaction's own logs show that change. Three ledger entries record them, each with actor
humanand domainsystem:agent_budget_changed{ by, from, to, txHash, onChain: { contract, txHash, signer } }when the wallet changed the figures.tois what that transaction set,nullfor a figure not set, andsigneriswalletorpasskey. The workspace's spending limit then follows what the contract holds. The entry now carriestxHashat the top ofdetailas well.spending_limit_stopped{ by, contract, txHash, signer }, a new entry: the wallet set its approval for the contract to 0. Unless the agent was paused already, or a later approval undid the stop, the agent is paused first, with anagent_pausedentry whose reason is "The owner stopped the agent's payments on Arc".spending_limit_resumed{ by, contract, txHash, signer, allowanceUsdc }, a new entry: the wallet approved the contract again.allowanceUsdcis the cap it approved,nullwhen it has none. The pause a stop set is lifted first, with anagent_resumedentry, while the approval still stands; any other pause stays.
- All of these reach webhook endpoints as
ledger.appended, andGET /api/v1/ledgerlists them. Nothing else in/api/v1changes.
2026-10-07: A passkey wallet can be the treasury
- On Arc mainnet, an owner can make the treasury a passkey wallet: a smart account owned by their passkey, set up in Go live with one confirmation. Its setup writes the same entries as a wallet in the owner's browser, with these differences:
treasury_wallet_chosen, a new entry with actorhumanand domainsystem, records the choice in place oftreasury_wallet_proven. Itsdetailis{ by, address, signer: "passkey", network }. A passkey wallet signs no message: its own approval of the contract, on chain, proves it is the owner's.spending_limit_enforcedgainssigner: "passkey". ItsdeployTxHashandapproveTxHashare the same transaction, which deployed and approved the contract in one user operation.treasury_recovery_registered{ by, recoveryAddress, txHash }records the address of the recovery phrase the owner registered as a recovery owner of the wallet.treasury_recovery_skipped{ by }records that they chose to go without one. A passkey wallet's workspace goes live only after one or the other.
- On both routes, choosing the wallet now creates the agent's wallet in the same step, so
agent_wallet_createdfollowstreasury_wallet_provenortreasury_wallet_chosenat once. - All of these reach webhook endpoints as
ledger.appended, andGET /api/v1/ledgerlists them. Nothing else in/api/v1changes.
2026-10-07: A workspace on Arc mainnet can pay from its owner's own wallet
- A workspace on Arc mainnet can keep its treasury in a wallet its owner holds. It pays from that wallet only through its spending limit contract, from an agent wallet Vestiarion creates for it. Its setup writes three new ledger entries, each with actor
humanand domainsystem, and each sent to webhook endpoints asledger.appended:treasury_wallet_proven: the owner's wallet proved it is theirs. Itsdetailis{ by, address, message, signature, network }: the wallet's address, and the message it signed with the signature, which anyone can check again.agent_wallet_created:{ by, address }, whereaddressis the agent's wallet, the only one that can pay through the contract.spending_limit_deployed:{ by, contract, txHash, dailyUsdc, weeklyUsdc }, the contract the owner's wallet deployed, its transaction and its figures,nullfor a figure not set.
spending_limit_enforcedfor such a workspace has the fields it has for a Circle wallet.treasuryis the owner's wallet andsetLimitsTxHashisnull, and two fields are added:walletHost: "external", andallowanceUsdc, the approval the owner's wallet gave the contract,nullwhen it has no cap.agent_budget_changedis written when the deployed figures differ from the workspace's spending limit, withonChain.txHashthe deployment.workspace_went_livefor such a workspace carriesdetail.walletHost: "external".- In
GET /api/v1/treasury, its operating account'saddressis the owner's wallet, and itsbalanceis what the contract can move: the wallet's USDC, or the approval if that is less. - The agent's payment decisions carry
onChainLimit, as they do wherever a limit is enforced on Arc. A person's payment goes through the contract too, and its entries do not change. Nothing else in/api/v1changes.
2026-10-06: A milestone release waits for its cash
- The agent no longer sends a milestone release that the operating wallet cannot cover, counting the releases before it in the same cycle and those still in flight. Its
milestone_releaseentry hasexecution.resultingStatus: "held"andexecution.heldBecause: "cash_shortfall", as an AP decision held for want of cash has. - On a milestone,
execution.cashNeededUsdcis the milestone's amount, andexecution.cashSeen.operatingis what the operating wallet had left for it after those releases.cashSeen.reserveis the reserve, andcashSeen.gasKeptUsdc, on Arc mainnet, is the USDC the wallet keeps for its own gas. On an AP decision,cashNeededUsdcalso counts the payables due before it, andcashSeen.operatingis the whole balance. - A release whose last send Circle never answered is not held for cash. It goes out again under the same key, which finds the transfer at Circle if the money already moved.
- Once cash has come in since and covers it, the next cycle reopens the milestone with a
milestone_reopenedentry whosefollowUp.changesreads "the cash it needs is there now (… USDC in the operating wallet and the reserve)", and decides it again. - A release from escrow is not affected. Nothing else in
/api/v1changes, and no other entry changes shape.
2026-10-06: A cycle can start when Circle says a payment settled
- A
cycle_completeentry'seventscan includepayment_settled. Circle said a transfer in flight settled or failed, and that cycle recorded which. Circle's notification started it, so itsbyis absent, unless a person's event started the same cycle. - A
cycle_completeentry'seventscan includepayment_receivedwithout a person too, when Circle said money arrived in the workspace's operating wallet and it paid a receivable. Itsbyis then absent, unless a person's event started the same cycle. - An
ar_receivedentry can be written as Circle's notification arrives, before that cycle, as the pay page's check writes it. The other entries are the ones the schedule writes. Nothing else in/api/v1changes.
2026-10-06: Webhook retries go out every 10 minutes
- The schedule that sends webhook retries, and anything still queued, now runs every 10 minutes. It ran on GitHub Actions, which started it only a few times a day, so a retry could wait hours past its backoff step. A delivery's body, headers and backoff steps do not change.
2026-10-06: A contractor on another chain is refused without naming a network
POST /api/v1/counterpartiesrefuses a contractor with another chain with "Only a vendor can be paid on another chain; a contractor's milestones are released on the workspace's own chain.", in place of "…released on Arc testnet.", so a workspace on Arc mainnet is not told a testnet. The code,invalid_request, does not change.- A
payment_stuckentry'sdetail.txHashnow carries the transaction hash Circle answers with when the payment had none recorded yet, where it wasnull. Its shape does not change, and nothing else in/api/v1changes.
2026-10-06: A payment that has not confirmed is told
- A new ledger entry,
payment_stuck, is written when a live payment has not confirmed 15 minutes after its attempt was sent, once for each attempt. Its actor isagent, and its domainapfor an invoice orcontractorfor a milestone. - Its
detail:invoiceIdormilestoneId,counterpartyId,amount,currency,idempotencyKey,attempt,submittedAt,minutes,circleAsked(whether Circle was asked this time),sendAnswered(false for a send Circle never answered),providerState(Circle's state when asked, such asSTUCK),txHashandnetwork. - Every webhook endpoint receives it as
ledger.appended, andGET /api/v1/ledgerlists it. Nothing else changes in/api/v1, and no other entry changes shape.
2026-10-06: Status says when an Arc mainnet workspace cannot pay yet, and a txHash on any network
GET /api/v1/statusanswersprovenance.paymentsandprovenance.yieldasunavailablefor a workspace on Arc mainnet that has its Circle account connected but is not live yet. Nothing pays there until it goes live, solivewould have been wrong.provenance.yieldisunavailableon a network with no yield reserve. Arc mainnet has none, so a live workspace there answerspayments: "live"andyield: "unavailable"; it used to answeryield: "simulate".- An invoice's
txHashis described as on the workspace's network, not on Arc testnet. Its value does not change. - A received payment's
ar_receivedentry and a newpay_link_createdentry name the workspace's network insummary. Entries already written stay as they are. - A workspace on Arc mainnet can now go live, on a deployment that has Arc mainnet switched on. Its
workspace_went_liveentry carriesdetail.network: "arc-mainnet", asorg_createddoes. - The TypeScript SDK 0.3.2 carries the new descriptions. Nothing else changes in
/api/v1, and no entry changes shape.
2026-10-06: Two approvals from the start on Arc mainnet, and its status said plainly
GET /api/v1/statusanswersprovenance.paymentsandprovenance.yieldasunavailablefor a workspace on Arc mainnet with no Circle account connected yet, as it does when stored credentials cannot be read, and while the deployment has Arc mainnet switched off. Nothing pays then, sosimulatewould have been wrong. The reference and the TypeScript SDK 0.3.1 describe all three.- An
org_createdentry for a workspace on Arc mainnet carriesdetail.startingLimits:{ dailyUsdc: 50, weeklyUsdc: 150, twoApprovalsAbove: 100 }. That workspace starts with two approvals above 100 USDC, and anapproval_policy_changedentry can never turn them off there. - Nothing else changes in
/api/v1, and no other entry changes shape.
2026-10-06: chain accepts ARC, and two entries name their network
POST /api/v1/counterpartiesacceptschain: "ARC", Arc mainnet's chain, for a workspace on Arc mainnet. Leavingchainout gives the workspace's own chain:ARCthere, andARC-TESTNETon Arc testnet, as before.- A chain the workspace's network does not pay on is refused with
invalid_request, naming it:ARCon Arc testnet, or a Sepolia chain on Arc mainnet. org_createdandworkspace_went_liveentries now carrydetail.network,arc-testnetorarc-mainnet.- The TypeScript SDK 0.3.0 types
chainwithARCtoo. - Nothing else changes in
/api/v1, and no other entry changes shape.
2026-10-05: The agent sends again on its own only what one approval may pay
- An
ap_reconcileormilestone_reconcileentry can now carrynotResubmittedBecause: "workspace.two_approvals", withexecution.resultingStatus: "held". The payment was never sent and is above the workspace's figure for two approvals. Two people's approvals of it had not been used to pay it, so the agent held it rather than sending it again. - Every ledger entry is still appended the same way, and its shape does not change.
- Nothing changes in
/api/v1.
2026-10-05: Approve and pay draws on the USYC reserve, and a person's cash back stays
- Approve and pay brings back what the operating wallet lacks. A person's paying approval of a new USDC payment from the operating wallet, on Arc testnet or through CCTP with its fee, may now first bring cash back from the reserve. It does so when the wallet cannot cover the payment and the reserve can cover the rest. It brings back the difference, rounded up to the next micro-USDC, with a fifth more of a CCTP fee, which is read again just before the burn. A CCTP payout whose fee could not be read is not covered. Pay now on a held milestone does the same.
- A new kind of
cash_brought_backentry: actorhuman, withdetail{ by, reason: "approval", invoiceId | milestoneId, amount, neededUsdc, feeCushionUsdc?, operatingBalance, reserveBalance, earnMode, executed, executionNote?, execution? }. It comes before the payment's own entry. - A redemption that did not move is recorded too, with
executed: falseand why inexecutionNote, and nothing is paid. One Arc testnet had not yet confirmed may still land; asking again for the same payment finds that same redemption rather than sending a second one. approval_paidandmilestone_approval_paidthen carryfromReserveUsdc.- When the wallet and the reserve together fall short, Approve and pay refuses, as before, before anything moves. No ledger entry is written for a refusal.
- A new kind of
- A person's Bring cash back stays for 24 hours. For 24 hours after a
cash_brought_backentry withreason: "person", the agent's treasury decisions sweep nothing.- Their entries (
hold, orredeem_from_usycfor what falls due) then carrypersonCashBack: { amount, at, until }. - A sweep the model chose anyway is recorded as a
hold, with what it chose inboundedByCode.
- Their entries (
- Nothing changes in
/api/v1.
2026-10-05: A person's payout to another chain takes the agent's route
- An
approval_paidentry for a new payment to another chain can now carrypayout.route: "gateway", withgatewayBalanceUsdc, on a person's first attempt. A person's Approve and pay now chooses the route as the agent does: Gateway when the workspace's Gateway balance covers the amount and Gateway's fee, and Gateway costs no more than CCTP; CCTP otherwise. Before, a person's first attempt always went through CCTP. - Approve and pay now refuses, before anything is sent, a CCTP payout the operating wallet cannot cover with its fee, and a Gateway payout the Gateway balance cannot cover. No ledger entry is written for a refusal.
- Nothing changes in
/api/v1.
2026-10-05: Two approvals above a figure the workspace sets
- A new guardrail rule,
workspace.two_approvals. Above the figure a workspace's owner sets, the agent never pays or schedules a payable, or releases a milestone: code holds it for two people. Its entry carriesguardrailBlocked: true,execution.resultingStatus: "held"andobserved.twoApprovalsAbove, the figure it was weighed against. A EURC payable is weighed at itsusdcValue. - New ledger actions, each with actor
human:approval_given(domainap) andmilestone_approval_given(domaincontractor): the first of two approvals, which sends nothing. Itsdetailis{ by, invoiceId | milestoneId, counterpartyId, amount, currency, address, usdcValue?, twoApprovalsAbove, fewApprovers? }.approval_policy_changed(domainsystem): an owner set, raised, lowered or turned off the figure. Itsdetailis{ by, from, to }, each a figure in USDC or null for off.
approval_paidandmilestone_approval_paidgainapprovals: [{ by, at }, …], the earlier first, andtwoApprovalsAbovewhen two people approved the payment. Theirsummarythen ends "(the second of two approvals)".- They also carry
fewApprovers: truewhen whoever entered the payment, or gave its address, gave one of the two because no one else could. As many of the two as can come from other people must.
- They also carry
- An
invoice_reopenedentry'sfollowUp.changescan say that two approvals were turned off, or the figure raised to cover the payment. Amilestone_reopenedentry's can say the same. - Nothing changes in
/api/v1.
2026-10-05: A payment Circle did not answer is looked for, never sent again blind
- A payment whose send Circle did not answer is now in flight, not held. Its decision's
execution.resultingStatusismatched, as for any payment Circle is still settling.- Vestiarion then looks for the send on Circle by its reference before anything is sent again.
- If Circle has it, it is recorded as the payment.
- If Circle has listed nothing 15 minutes after the send, the payment is sent as a new one.
- Reject and Return look for it the same way before they act.
- Payments can also be switched off from the database (
npm run payments -- off "<reason>"). Every running deployment stops within 10 seconds, with no redeploy. While they are off, the agent appends no entries. - Approve and pay still records a transfer that was already sent while payments are off, since that only reads Circle.
- Nothing changes in
/api/v1.
2026-10-05: Checked addresses, a stop switch, and no rejection over an unknown transfer
POST /api/v1/counterpartiesrefuses anaddressthat mixes capital and small letters when they do not match its EIP-55 checksum:400 invalid_request, with the messageaddress: This address's capital letters do not match its checksum, so a character is likely wrong.An address written in one case alone is taken as written, as before.- Payments can be switched off for every workspace by whoever runs the deployment (
PAYMENTS_DISABLED). While they are, no agent cycle runs, so the agent appends no entries and webhooks receive none from it. - When a payment's send ends without Circle saying what became of it, the invoice can be neither rejected nor returned until a person approves it, which asks Circle again under the same key. No ledger entry changes shape.
- On a deployment with no screening service, a live workspace's counterparties stay
unscreenedinstead of being screened against the demo list. Itscompliance_sweepentries say the screening is incomplete. - Otherwise nothing changes in
/api/v1.
2026-10-05: Two people before the first payment to an address
-
A new guardrail rule,
counterparty.new_payee. Wherever payments are real, the agent never makes a payment or milestone release that would be the first to an address unless two different parties stand behind it:- the payee sent the address and a member confirmed it; or
- one member gave it and another confirmed it.
Its entry carries
guardrailBlocked: trueandexecution.resultingStatus: "held". -
A decision on a first payment records
observed.newPayee: { addressBy, confirmedBy, twoParties }.addressByis a member id,"payee", or null when no entry says who gave it. -
approval_paidandmilestone_approval_paidgainfirstPayment: truewhen a person made an address's first payment. Approve and pay, and Pay now, now refuse the member who gave the address, unless they are the workspace's only approver. -
An
invoice_reopenedentry'sfollowUp.changescan namethe payee's address has received a confirmed payment sinceora second person now stands behind the payee's address. -
Nothing changes in
/api/v1.
2026-10-05: A EURC payable decided again when the rate changes what held it
- An
invoice_reopenedentry gainsreevaluationwhen a fresh quote cleared what held a EURC payable. Its shape is{ trigger, previousDecision: { seq, action, guardrailRule }, before: { rate, usdcValue, swapCostPercent }, after: { rate, usdcValue, swapCostPercent, quotedAt } }.triggeris one ofrate_available,swap_available,swap_cost_within_caporvalue_within_limit.followUp.changessays the same in words.
- The
ap_*decision that follows such a reopen in the same cycle gainsreevaluation: { reopenedSeq, trigger, previousDecisionSeq, previousAction }. Its ownfxis the rate it was decided at. - A
cycle_completeentry'seventscan includefx_changed. The FX watch started that cycle, every 5 minutes at most, not a person, so itsbyis absent. - Nothing changes in
/api/v1.
2026-10-05: The three-way match, checked in code
- A new guardrail rule,
invoice.match_incomplete. When the agent chooses to pay or schedule a payable whose goods are not confirmed received, or whose counterparty needs a purchase order and has none on file, code refuses it. Itsap_payorap_scheduleentry carriesguardrailBlocked: true,guardrailRule: "invoice.match_incomplete"andexecution.resultingStatus: "awaiting_info", and the invoice waits for its details. - An AP decision's
detail.observedgainspurchaseOrderRequired: whether the counterparty needed a purchase order when it was decided. Every counterparty needs one unless an owner or admin marked it as paid without them. - A new ledger action, delivered to webhooks as
ledger.appendedlike every entry:counterparty_purchase_orders_changed, actorhuman, domaincompliance. Itsdetailis{ by, counterpartyId, from, to }, wherefromandtosay whether the counterparty needed a purchase order before and after. - A
cycle_completeentry'seventscan includepurchase_orders_waived: a counterparty was marked as paid without purchase orders, so its payables that waited for one were decided again within a minute. - The
invoice_reopenedentry for such a payable namesthe counterparty is now paid without purchase ordersinfollowUp.changes. - Nothing changes in
/api/v1.
2026-10-04: A merge starts the cycle
- A
cycle_completeentry'seventscan now includepull_request_merged. A pull request was merged in a repository the workspace's GitHub connection covers, and a pending milestone waited on it, so the cycle that verifies and pays it started within a minute of the merge rather than at the next scheduled cycle. - Nothing changes in
/api/v1.
2026-10-04: Bounties from a pull request comment
- A new ledger action, delivered to webhooks as
ledger.appendedlike every entry:github_bounty_attached, actorhuman, domaincontractor. Someone who can write to a repository attached a bounty to a pull request with/bounty. Itsdetailis{ by, via: "github", installationId, login, pullRequest, author, amount, milestoneId, counterpartyId, commentUrl }.byis the member who connected GitHub, under whose name the milestone was added, andloginis the GitHub user who commented. See Show payments on GitHub. create_counterpartyandcreate_milestoneentries gainvia: "github",installationIdandloginfor the contractor and the milestone a bounty added.counterparty_address_changedentries gainvia: "github",installationId,loginandcommentUrlwhen a pull request's author set their address with/payto. Theirbyisnull, as for an address sent through a payee link, and the address waits for a member's confirmation the same way.- Nothing changes in
/api/v1.
2026-10-04: Emailed invoices finished by hand
- A
create_invoiceentry withvia: "email"no longer always carrieschanged: []. An owner or admin can now finish an emailed invoice in the invoice form on AP / AR, with Edit and add or Finish and add. Itsdocument.changedthen lists the fields they changed from what was read, as for an invoice added from a document. - Such an entry carries no
documentwhen the email could not be read and the invoice was typed in. - Nothing changes in
/api/v1.
2026-10-04: Cash back for milestones too
- A
cash_brought_backentry withreason: "payments_due_today"now also counts the verified milestones waiting to be paid inneededUsdcandpayments, so a cycle brings their cash back from the reserve before it releases them. A milestone whose USDC is locked in escrow is not counted. - A person's Pay now on a milestone for a pull request now gets its
pull_request_commentedentry once the payment is confirmed, rather than at the next cycle.
2026-10-04: Payments said on the pull request
- A workspace can connect GitHub from Settings, by installing the Vestiarion app on the repositories it chooses. See Show payments on GitHub.
- Three new ledger actions, delivered to webhooks as
ledger.appendedlike every entry:github_connected, withinstallationId,account,accountTypeandrepositorySelection;github_disconnected, withinstallationIdandaccount;pull_request_commented, withmilestoneId,pullRequest,commentUrl,amount,tokenandtxHash. It is written when the app commented on the pull request a milestone was paid for. The comment names the amount, the network, the paying workspace and the transaction, never the payee.
- Private pull requests verify in a repository the app is installed on, so
verify_milestone_githubcan now follow a private pull request's merge. - Nothing changes in
/api/v1.
2026-10-03: Invoices by email
- New ledger actions, delivered to webhooks like every entry:
invoice_inbox_on,invoice_inbox_changedandinvoice_inbox_off, actorhuman, domainsystem: an owner or admin turned on the workspace's address for invoices by email, replaced it, or turned it off. Theirdetailis{ by }; the address is never recorded.invoice_email_received, actorsystem, domainap: an email arrived at the address and was read. Itsdetailis{ inboxEmailId, from, authentication, read, document }: the sender with most of its name hidden, SPF/DKIM/DMARC as Resend reported them,readone ofready,needs_detailsorunreadable, and the document'skindandsha256, ornull.invoice_email_dismissed, actorhuman, domainap:{ by, inboxEmailId }.
create_invoiceentries gainvia: "email"andinboxEmailIdwhen a member added the payable from an email on AP / AR. Such an entry carriesdocumentas one added from a document does, withchanged: []. Nothing that arrives by email is added without a person.- Nothing changes in
/api/v1.
2026-10-03: Add milestones and payee links through the API
- Add a milestone,
POST /api/v1/milestones, with a read-and-write key.- It takes
{ contractorId, title, amount, verificationSource? }, checked by the rules of the console's Add milestone form, and answers201with the milestone, shaped as List milestones returns it. - The milestone starts
pending, and the API cannot verify it. A GitHub pull request inverificationSourceis verified by the agent once it is merged; any other link waits for a person. - It takes an
Idempotency-Key, as every write does. - It is recorded as
create_milestonewithvia: "api"andapiKeyId.
- It takes
- Create a payee link,
POST /api/v1/payee-links, with a read-and-write key.- It takes
{ counterpartyId }, a vendor or a contractor, and answers201with{ id, counterpartyId, url, expiresAt }. urlis in that answer only, which is sent withCache-Control: no-store.- The operation keeps no outcome for an
Idempotency-Key, which would store the link. A repeat makes a new link, and the unused one stops working. - It is recorded as
payee_link_createdwithvia: "api"andapiKeyId. The address a payee enters through it waits for a person to confirm it, as before.
- It takes
- A write now checks the key's creator as they are now. Only owners and admins can add records. If an owner moves the creator to approver or viewer, the key keeps reading, and every write, invoices and counterparties included, answers
403 forbidden: "This key's issuer can no longer add records in this workspace." - A milestone records who added it, from the console, Pay a freelancer or the API. So the self-approval rule now applies to milestones too. When the agent held a milestone on its own judgment, the person who added it cannot choose Pay now for it, unless they are the workspace's only approver. Milestones added before keep no creator.
- MCP gains
create_milestoneandcreate_payee_link.create_payee_linkis marked destructive, because a new link revokes the unused one. @vestiarion/sdk0.2.0 addsmilestones.createandpayeeLinks.create.- Settings: the box that gives a key write access is now Can also add records.
2026-10-03: Add an invoice from Slack
create_invoiceentries gainvia: "slack"andlinkIdwhen an owner or admin added the payable from a message in Slack with Add invoice. Such an entry carriesdocumentas one added from a document on AP / AR does, withchanged: [].- The Slack app asks for one more permission,
files:read, to read the file someone chooses. A Slack connected before this is connected again from Settings with Reconnect Slack; its members stay connected. - Nothing changes in
/api/v1.
2026-10-03: A member's API keys end with their membership
- A workspace API key now works only while the person who created it is a member of the workspace. When they leave, are removed by an owner or an admin, or delete their account, every active key they created in that workspace, read-only or read-and-write, is revoked in the same step, and from then on answers
401 unauthorizedon/api/v1and on MCP, like any revoked key. Keys that other members created, and the person's keys in workspaces they still belong to, keep working. - Each such key gets its own
api_key_revokedentry, delivered to webhooks like every entry, right after the member'smember_leftormember_removed. Itsdetailgainsreason:member_left,member_removed(withmember, the person removed, whilebyis who removed them) oraccount_deleted. A key revoked in Settings now carriesreason: "person". - A key can no longer be created for someone who is not a member of the workspace.
- A read-and-write key whose issuer has left can no longer add records, so a
create_counterpartyorcreate_invoiceentry withvia: "api"always names its issuer inby. - Nothing was revoked when this shipped: no active key had outlived its creator's membership.
2026-10-03: The TypeScript SDK on npm
npm install @vestiarion/sdkinstalls it from the npm registry.- Version 0.1.0 there is the same tarball, byte for byte, as
https://www.vestiarion.xyz/sdk/vestiarion-sdk-0.1.0.tgz, which keeps working.
2026-10-03: A member's notifications move to Settings
telegram_disconnectedentries for a chat its member disconnected from Vestiarion now carryvia: "settings": the Telegram card moved from Members to the Notifications section at the top of Settings, with the switch for the email about payments that need a decision. Entries made before keepvia: "members_page";via: "telegram"andvia: "blocked"are unchanged.- Nothing else changes in the ledger, the webhooks or
/api/v1.
2026-10-03: A TypeScript SDK
@vestiarion/sdk0.1.0, installed withnpm install https://www.vestiarion.xyz/sdk/vestiarion-sdk-0.1.0.tgz. It is a typed client for every/api/v1operation, with no dependencies, for Node 20 or later, Deno, Bun and edge runtimes. See TypeScript SDK.- Its types are generated from the OpenAPI document, so they follow each change listed here.
listAllandpagesfollowpage.nextCursorto the end of a collection.- Requests are retried after:
- a
429, when itsRetry-Afteris 60 seconds or less; - a
5xx; - a timeout or a network failure.
- a
- Every write carries an
Idempotency-Key, so a retry never adds a record twice. verifyWebhookchecks a delivery'sVestiarion-Signature.verifyLedgerEntrychecks an entry's body hash, Ed25519 signature and chain hash.- Nothing in the API or the webhooks changed.
2026-10-03: The agent's decisions in Slack
- New ledger actions, domain
system, delivered to webhooks like every entry:slack_installed, actorhuman: an owner or admin connected a Slack workspace from Settings, and picked the channel the agent's decisions go to. Itsdetailis{ by, teamId, channelId }.slack_uninstalled: the workspace's Slack was disconnected, with every member's Slack link. Actorhumanwhen an owner or admin chose Remove Slack (via: "settings"); actorsystemwhen Slack said the app was removed from its workspace (via: "slack"), withbynull. Itsdetailis{ by, teamId, via }.slack_member_connected, actorhuman: a member connected their own Slack account. Itsdetailis{ by, linkId }, plusvia: "install"for the account of the person who connected the workspace.slack_member_disconnected, actorhuman: a member disconnected their own Slack account, with/vestiarion disconnect(via: "slack") or from Settings (via: "settings"). Itsdetailis{ by, userId, linkId, via }. A member removed from the workspace loses the link with the membership, and that is recorded as the removal.slack_decisions_limit_changed, actorhuman: an owner set the most a payment approved from Slack may be, or turned deciding from Slack off. Itsdetailis{ by, from, to }, in USDC,nullfor off.
approval_paid,approval_rejectedandapproval_returnedentries gainvia: "slack"andlinkIdwhen a member decided the payable from its message in Slack, andagent_pauseddoes when they paused the agent with/vestiarion pause. Everything else in them is what the console writes. Entries for actions taken in the console carry novia, as before.- A cycle's journal has a new stage,
slack, aftertelegram, the last. It needs no other stage to have succeeded. - Nothing changes in
/api/v1.
2026-10-03: A payable held for an unconfirmed address goes back to the agent once it is confirmed
- A payable the agent held because its counterparty's address changed and no one had confirmed it (
guardrailRule: "counterparty.address_unconfirmed",observed.addressUnconfirmed: true) now goes back to the agent when a person confirms the address: aninvoice_reopenedentry whosefollowUp.changesreads "the counterparty's new address has since been confirmed", then a new decision in the same cycle. Until now it stayed held until a person approved it. Approving it still pays it, and confirms the address. - The API's two write examples are now responses captured in testnet-2.
2026-10-03: Add counterparties and invoices through the API
- New operations:
POST /api/v1/counterpartiesandPOST /api/v1/invoices. Each takes a JSON body of at most 64 KB, checked by the console form's rules, and answers201with the record, shaped as its list returns it. A body that does not validate, including one with a field the operation does not take, answers400 invalid_request, naming the field. AcounterpartyIdthe workspace does not hold answers400too. - A new scope,
write. A key is read-only, as every existing key stays, or reads and writes; an owner or admin chooses when creating it. A read-only key on a write answers403 forbidden.api_key_createdlistsscopes: ["read", "write"]for such a key. Idempotency-Keyon both writes. A repeat with the same key and body within 24 hours gets the first answer back, withIdempotent-Replayed: true. The same key with a different body, or while the first request is still being handled, answers the new error codeconflict(409). A5xxanswer, and a body that fails validation, are not kept, and a key whose first request never finished is free again after 10 minutes.- Writes are limited to 30 a minute per key; over that,
429 rate_limitedwithRetry-After: 60. Reads stay unlimited. create_counterpartyandcreate_invoiceentries for records added through the API carryvia: "api"andapiKeyId, withbythe key's issuer, ornullonce their account is gone. Such acreate_counterpartyalso carriesaddressNeedsConfirmation: an address added through the API waits for a person to confirm it, and the agent holds payments to it (counterparty.address_unconfirmed) until then.- A payable added through the API starts a cycle, whose
cycle_completeentry listsinvoice_addedinevents, as one added in the console does. - MCP: two new tools,
create_counterpartyandcreate_invoice, annotatedreadOnlyHint: false,destructiveHint: false,idempotentHint: false, with an optionalidempotencyKey. A read-only key gets the403as a tool error. - The OpenAPI document describes each write's request body, its
Idempotency-Keyheader and its201.
2026-10-03: A sweep's yield is counted over how long the cash would stay
- In treasury entries (
sweep_to_usyc,redeem_from_usyc,hold, actoragent),economics.expectedHoldDaysis now how long the swept cash would stay in the reserve, on average over the next 30 days. What falls due is paid from the operating wallet first, and only what it cannot cover comes back, on its day. Before, it was the days until the next obligation.economics.projectedYieldUsdfollows, and the written policy'sreferenceDecisionwith it.
2026-10-03: Code bounds the treasury's moves, and a payable to a client waits for a person
- A new value of
guardrailRule:counterparty.client_payable. The agent holds a payment, or a schedule, to a counterparty whose role isclient, for a person: a client pays the business, so a payable to one is a refund, or an invoice entered in the wrong direction. A person may still approve it. - Treasury entries (
sweep_to_usyc,redeem_from_usyc,hold, actoragent, domaintreasury):decisionis now the move code allowed. A sweep takes at most the cash above the 7-day buffer. A redemption brings back at most 115% of what falls due within 14 days, less the operating balance, and at least the written policy's.- When code changed the model's move,
boundedByCode: { chosen: { action, amount }, reason }keeps what the model chose and why, anddecision.reasoningends with "[Code limited this: …]". agreedWithReferencenow also needs the amount within 5% ofreferenceDecision.amount, or 0.01 USDC.
ar_reminders_ongainsreplacedLink: true only when turning reminders on replaced a link made before October 3, which stops working.madeNewLinkis also true when the receivable had no link.
2026-10-03: The agent reminds clients of what they owe
- New ledger actions, domain
ar, delivered to webhooks like every entry:ar_reminders_onandar_reminders_off, actorhuman: an owner or admin turned the agent's reminders on or off for a receivable.detailis{ by, invoiceId, counterpartyId }, and forar_reminders_onalsolinkIdandmadeNewLink(a link made before October 3 was replaced so the reminders can carry it).ar_reminder_sent, actoragent: the agent emailed the client a reminder.detailis{ invoiceId, counterpartyId, to, number, tone, daysFromDue, amount, currency, linkId, decision, referenceDecision, decisionMode, agreedWithReference }.tois the address with most of its name hidden;numberis 1 to 4;toneisfriendly,firmorfinal;daysFromDueis negative before the due date.toneLimited: { chosen, sent }is there when code sent a softer tone than the model chose.ar_reminder_deferred, actoragent: the agent decided to wait before reminding.detailis{ invoiceId, counterpartyId, until, daysFromDue, remindersSent, decision, referenceDecision, decisionMode, agreedWithReference }.
- Turning reminders on starts a cycle; its
cycle_completeentry lists the new event kindreminders_oninevents. - A cycle's journal has a new stage,
collections, betweenproposalsandnotices. It runs only whenreceiptscompleted. counterparty_notice_email_changednow covers a counterparty's billing email, which also receives a client's reminders; itssummaryreads "Billing email for name: address", or "... removed".
2026-10-03: The agent's decisions in Telegram
- New ledger actions, domain
system, delivered to webhooks like every entry:telegram_connected, actorhuman: a member connected their own Telegram chat to the workspace, from Members. Itsdetailis{ by, username }, whereusernameis the Telegram username with most of it hidden (@li***), ornull.telegram_disconnected: a chat no longer gets the workspace's decisions. Actorhumanwhen the member disconnected it, from Members (via: "members_page") or with/disconnectin the chat (via: "telegram"); actorsystemwhen Telegram answered that the member had blocked the bot (via: "blocked"). Itsdetailis{ by, userId, via, username }, withbynullforblocked. A member removed from the workspace loses the connection with the membership, and that is recorded as the removal.
create_invoiceentries gainvia: "telegram"when a member added the payable by tapping Add on an invoice the bot read. Such an entry carriesdocumentas one added from a document on AP / AR does, withchanged: [].- A cycle's journal has a new stage,
telegram, afternotices, the last. It needs no other stage to have succeeded. - Nothing changes in
/api/v1.
2026-10-03: Cash comes back from the reserve for payments
- New ledger action
cash_brought_back, domaintreasury, delivered to webhooks like every entry: USDC came back from the reserve to the operating wallet.- Actor
agent: each cycle, before it decides payments, the agent brings back what the USDC payables due today need beyond the operating balance. Itsdetailis{ reason: "payments_due_today", amount, neededUsdc, payments, operatingBalance, reserveBalance, executed, executionNote, earnMode, execution? }.executionholds the transactions of a real USYC redemption. When nothing could move,executedisfalse,executionNotesays why, and the entry'ssummarybegins "Could not bring"; while the agent is paused,heldBecauseisagent_paused. - Actor
human: an owner or admin chose Bring cash back. Itsdetailis{ by, reason: "person", amount, all, reserveBalance, earnMode, execution? }, whereallsays they brought back everything. It moves cash even while the agent is paused, and starts a cycle, whosecycle_completeentry lists the new event kindcash_returnedinevents.
- Actor
- The redemption itself is also a
treasury_actionsrow withaction: "redeem_from_usyc", as the treasury stage's are. - An AP decision held because the cash was not there carries
execution.heldBecause: "cash_shortfall", withexecution.cashNeededUsdc(what it needed, with the payables due before it) andexecution.cashSeen: { operating, reserve }(the balances it saw). Once cash has come in since and covers it, the next cycle reopens the payable with aninvoice_reopenedentry whosefollowUp.changesreads "the cash it needs is there now (… USDC in the operating wallet and the reserve)", and decides it again. - A cycle's journal has a new stage,
liquidity, betweenservicesandap.
2026-10-03: Payment notices
- New ledger actions, delivered to webhooks like every entry:
payment_notice_sent, actorsystem, domainaporcontractor: a payee was emailed that a payment to it was confirmed. Itsdetailis{ invoiceId or milestoneId, counterpartyId, to, amount, token, txHash }, wheretois the address with most of its name hidden (li***@example.com).counterparty_notice_email_changed, actorhuman, domaincompliance: a person set, changed or cleared where a counterparty's payment notices go. Itsdetailis{ by, counterpartyId, from, to }, both addresses hidden the same way,nullfor none.
create_counterpartyentries gainnoticeEmail, hidden the same way, ornull.- The address itself is not part of
/api/v1/counterparties.
2026-10-03: Add what a held payable was missing
- New ledger action
invoice_details_added, actorhuman, domainap, delivered to webhooks like every entry: a person added the purchase order a held, flagged or awaiting-information payable lacked, or marked its goods or services received. Itsdetailis{ by, invoiceId, counterpartyId, added }, whereaddedholdspoReference,goodsReceived: true, or both. Nothing already on the invoice changes, and itsstatusstays as it was. - At its next cycle the agent reopens the payable with an
invoice_reopenedentry whosefollowUp.changesnames what was added, and decides it again. Adding details starts that cycle within seconds, and itscycle_completeentry lists the new event kinddetails_addedinevents. - In
/api/v1/invoices, the payable'spoReferenceandgoodsReceivedshow what was added.
2026-10-03: A sandbox screens against the bundled watchlist
GET /api/v1/statusreportsscreening: "simulate"for a sandbox workspace, whatever the deployment configures; a live workspace reportslivewhen OpenSanctions is configured, as before.- A sandbox's counterparties are screened against the bundled watchlist at every cycle, and their
compliance_sweepentries name that source. One screened by OpenSanctions before is screened again against the watchlist at its next cycle.
2026-10-03: Nothing is paid to a counterparty never screened
- A new value of
guardrailRule:counterparty.unscreened. The agent holds a payment, a schedule or a milestone release to a counterparty whoseriskLevelis stillunscreened, because screening could not run when it was added. The decision is made again once screening gives a verdict. A counterparty whose later screening fails keeps its earlier verdict, as before.
2026-10-03: The spending limit, enforced on Arc
- New ledger actions, actor
human, domainsystem, delivered to webhooks like every entry:spending_limit_enforced: a person enforced the agent's spending limit on Arc testnet. Itsdetailis{ by, contract, agent, treasury, dailyUsdc, weeklyUsdc, deployTxHash, approveTxHash, setLimitsTxHash }, whereagentis the agent's own wallet andtreasurythe operating wallet.spending_limit_unenforced: a person turned it off. Itsdetailis{ by, contract, txHash }.
agent_budget_changedgainsonChain: { contract, txHash }when the figures were changed on the contract too.- While the limit is enforced, the agent's payment decisions (
ap_*andmilestone_*entries, actoragent) carryonChainLimit: { contract, agent, ref, covered, uncoveredBecause?, verdict }.coveredsays whether the payment can go through the contract;verdictis the contract's answer before anything was sent:{ state: "allowed" },{ state: "refused", error, spent?, amount?, limit? },{ state: "unreadable", reason }, ornullwhen it was not asked. - Two new values of
guardrailRule:workspace.onchain_limit(the contract would refuse the payment) andworkspace.onchain_limit_route(the payment is in EURC, or to another chain, which the contract cannot carry). - A payment sent through the contract has, as its transaction, a call to the contract's
pay(address,uint256,bytes32)by the agent's wallet. Its logs hold the USDC transfer from the operating wallet to the payee.
2026-10-03: A workspace's only approver may approve what they entered
- When the person who entered a payable, or added a milestone, is the only member of the workspace who may approve payments (the only owner, admin or approver), they may now approve it themselves. The
approval_paidormilestone_approval_paidentry then carriessoleApprover: truein itsdetail, and itssummaryends "(entered and approved by the workspace's only approver)". An approval by anyone else carries neither. Once a second member may approve, the person who entered a record cannot approve it again.
2026-10-02: The agent's reasoning is written in plain English
- New decisions'
agentReasoningin/api/v1/invoicesand/api/v1/milestones, anddetail.decision.reasoningin ledger entries, are written as 2 to 4 plain-English sentences, without the field names of the facts the agent was shown. Nothing about earlier records changes: the API and the ledger return what was stored.
2026-10-02: One review dismisses every screening match
- A
screening_match_dismissedentry can now dismiss several matches at once: the ones the person reviewed together. ItsdetailgainsmatchedEntities: [{ id, caption, score }], every match it dismissed.matchedEntityId,matchedCaptionandmatchedScorestill name the counterparty's verdict match, the first in the list. - Screening now reads every candidate it needs. Previously, after five dismissals of one name, a re-screen could read
clearwhile further matches were never looked at. Such a counterparty may now be screenedmediumorhighagain, with arisk_level_changedentry.
2026-10-02: A person decides a held milestone
- Milestones can be
closed. In/api/v1/milestones,statusmay beclosed: a person closed the milestone without paying it, and it is never paid after.?status=closedlists them. Every milestone has two new fields,nullunless it is closed:closedAt: when it was closed;closeReason: the reason the person gave.
- New ledger actions, delivered to webhooks like every entry:
milestone_approval_paid(actorhuman, domaincontractor): a person paid a held milestone. Itsdetailis{ by, milestoneId, counterpartyId, amount, currency, overrode, heldFor, txRef, status, attempt?, retriedAfter? }.statusispaid,verified(submitted, not yet confirmed) orheld(the transfer failed).heldForsays what it was held for: for exampletransfer_failed,agent_heldoroutflow_budget.retriedAfteris present when Circle had failed the previous attempt, which this one sent again.
milestone_closed(actorhuman, domaincontractor): a person closed a held milestone without paying it. Itsdetailis{ by, milestoneId, counterpartyId, amount, currency, heldFor, reason }.
2026-10-02: The agent buys payee history over x402
- New public endpoint:
GET /api/x402/payee-history?address=0x…. It is paid per call over x402: 0.001 USDC on Arc testnet (eip155:5042002), schemeexact, settled through Circle Gateway batching (GatewayWalletBatched, GatewayWallet0x0077777d7EBA4688BDeF3E311b846F25870A19B9).- Without a
PAYMENT-SIGNATUREheader it answers402with the offer inPAYMENT-REQUIRED. - With a payment Circle's facilitator verifies and settles, it answers
200with{ address, workspacesPaid, paymentsConfirmed, firstPaidAt, lastPaidAt, asOf, seller, priceUsdc }and the settlement inPAYMENT-RESPONSE. - A missing or malformed address answers
400before any offer. When the history cannot be read, it answers503and nothing is charged.
- Without a
- New ledger actions:
service_purchased(actoragent, domaincompliance). Itsdetailis{ purchaseId, counterpartyId, address, seller, priceUsdc, payer, payTo, nonce, settlement, result }.service_purchase_refused(actoragent, domaincompliance). Itsdetailis{ purchaseId, counterpartyId, address, seller, rule, reason }.ruleis one ofseller.not_allowed,offer.mismatch,price.above_max,budget.dayorpurse.short.service_purchase_failed(actoragent, domaincompliance). Itsdetailis{ purchaseId, counterpartyId, address, seller, reason }.service_budget_funded(actorhuman, domaintreasury). Itsdetailis{ by, amountUsdc, signer, depositor, txHash, balanceUsdc }.
- AP decision entries and
milestone_release/milestone_holdentries carryobserved.addressHistorywhen the agent bought the counterparty's address history within 7 days:{ about, workspacesPaid, paymentsConfirmed, firstPaidAt, lastPaidAt, boughtAt, priceUsdc }. - A cycle's
detail.stagesincludesservices, which runs afterrecurringand beforeap.
2026-10-02: Batches through the operating wallet's own executeBatch
- A batch of milestones is now one call to the operating wallet's own
executeBatch, as Circle documents for its smart accounts. The wallet sends USDC to each payee in turn, and if one transfer fails, none happens. - The first version sent batches through Arc's Multicall3From. Multicall3From keeps the sender only when the sender signed the transaction itself, and a Circle smart account's transaction is sent by Circle's bundler. Circle refused that batch at estimation (
ESTIMATION_ERROR), and no money moved. Its milestones were held, and theirmilestone_releaseentries carryexecution.batchwithresultingStatus: "held". - For a short time in between, workspaces with live wallets paid each milestone alone.
2026-10-02: Several milestones in one transaction
- When a cycle releases two or more milestones paid in USDC on Arc testnet, they go out in one transaction. Each is still decided, checked and signed on its own. A milestone locked in escrow is always released on its own.
- A
milestone_releaseentry for a milestone paid this way carriesexecution.batch:{ key, size }.keyidentifies the batch, andsizeis how many milestones it paid.execution.txRefis the batch's transaction, shared with the other milestones in it.execution.feeUsdis this milestone's share of the transaction's fee.
- In
/api/v1/milestones, several milestones can have the sametx_ref. A transaction hash no longer identifies one payment: key on the milestone'sid.
2026-10-02: The agent proposes limits from people's approvals
- When people approve at least two payments to one counterparty above its payment limit within 30 days, and reject none, the agent may propose raising the limit. The counterparty must be screened clear. An owner or admin accepts or dismisses the proposal in Approvals.
- New ledger actions, in the
compliancedomain:policy_proposal_made(actoragent). Itsdetailis{ proposalId, counterpartyId, kind, fromLimit, toLimit, evidence, reasoning, decisionMode, referenceLimit, agreedWithReference }.kindisraise_limit.evidencelists the approvals it rests on:{ invoiceId, amountUsdc, approvedAt, approvedBy, agentAction, guardrailRule }.policy_proposal_declined(actoragent): the model decided not to propose. Itsdetailis{ counterpartyId, currentLimit, evidence, reasoning, decisionMode, agreedWithReference }.policy_proposal_accepted(actorhuman). Itsdetailis{ by, proposalId, counterpartyId, fromLimit, toLimit, currentLimit }. Acounterparty_limit_changedentry precedes it, as for any limit change.policy_proposal_dismissed(actorhuman). Itsdetailis{ by, proposalId, counterpartyId, toLimit }.
- A cycle's
detail.stagesincludesproposals, which runs last, afterforecast.
2026-10-02: Recurring payments
- An owner or admin can set up a payment that repeats every N days, weeks or months. Each period's invoice is created as it comes near and decided like any other.
- New ledger actions, in the
apdomain:recurring_payable_created(actorhuman). Itsdetailis{ by, recurringId, counterpartyId, amount, currency, memo, poReference, goodsReceived, everyCount, everyUnit, startsOn, endsOn }.recurring_invoice_created(actoragent), when a cycle creates a period's invoice. Itsdetailis{ invoiceId, recurringId, period, counterpartyId, amount, currency, goodsReceived }.periodis the invoice's due date,YYYY-MM-DD.recurring_payable_stopped(actorhuman). Itsdetailis{ by, recurringId }.
- A cycle's
detail.stagesincludesrecurring, which runs afterfollow_upand beforeap. - An event cycle's
detail.eventscan includerecurring_added: someone set up a recurring payment. - Two invoices created for different periods of one recurring payment are never reported as duplicates of each other. Their decision entries'
observed.duplicateCheckreflects that.
2026-10-02: A real USYC reserve
- A live workspace's owner or admin can turn on a real USYC reserve on Arc testnet, once Circle has allowlisted its operating and reserve wallets. Until then, the reserve stays simulated, as before.
- New ledger action
usyc_reserve_enabled, in thetreasurydomain, appended when the reserve is turned on. Itsdetailis{ by, operatingAddress, reserveAddress }. - Treasury decision entries (
sweep_to_usyc,redeem_from_usyc,hold) of a workspace with a real reserve:- carry
earnMode: "live"; - carry
usycSubscriptionsOpen: whether USYC could be bought then, ornullwhen that could not be read; - when a move was made, carry
execution. A sweep's is{ approveTxHash, depositTxHash, shares, price }; a redemption's is{ redeemTxHash, shares, price }.sharesis in USYC,pricein USDC per USYC.
- carry
- A sweep decided while USYC cannot be bought has
executed: false, and anexecutionNotesaying so. - In
GET /api/v1/status,data.provenance.yieldreadslivefor such a workspace. - The reserve account's
balanceis its USYC's value in USDC at the latest price, read from Arc testnet every cycle. Itsapyis the fund's yield over at least the last 5 days, from the same oracle.
2026-10-02: The agent's spending limit
- An owner or admin can set what the agent may pay on its own per UTC day and per 7 days, in USDC. A payment past either is held for a person.
- New value of
guardrailRule,workspace.outflow_budget, on anap_payormilestone_releaseentry: paying it would have taken the agent past its limit.- The entry's
execution.heldBecauseisoutflow_budget. - A payable goes to Approvals as
held. A milestone stayshelduntil the limit has room for it.
- The entry's
- New field
outflowBudgeton anap_payormilestone_releaseentry, present when a limit is set:{ dailyUsdc, weeklyUsdc, spentToday, spentThisWeek, remaining, binding }.- It is what the limit left when the payment was weighed.
bindingisdayorweek, whichever figure left less.
- Milestone decision entries now carry
guardrailRule:counterparty.high_risk,counterparty.payment_limit,workspace.outflow_budget, ornull. - New ledger action
agent_budget_changed, in thesystemdomain, appended when someone changes the limit.- Its
detailis{ by, from, to }.fromandtoare each{ dailyUsdc, weeklyUsdc }, andnullmeans no figure.
- Its
- What counts against the limit is what the agent's own
ap_payandmilestone_releasedecisions sent: entries whoseexecution.resultingStatusispaidormatched, at their USDC value. A payment a person approves does not count. invoice_reopenedandmilestone_reopenedentries can list the change "the agent's spending limit has room for it again" or "the agent's spending limit was removed".- An event cycle's
detail.eventscan includebudget_raised: someone raised or removed a figure of the limit.
2026-10-01: Receivables paid on Arc
- New ledger action
pay_link_created, in theardomain: an owner or admin made a link for a client to pay a receivable. Itsdetailis{ by, invoiceId, linkId }. - New ledger action
ar_received, in theardomain, appended by the agent when a transfer that arrived in the operating wallet settles an open receivable.- Its
detailis{ invoiceId, counterpartyId, amount, currency, txHash, from, circleTxId, matchedBy, receivedAt }. matchedByissenderwhen the client's address on file sent it, andamountwhen it was the only open receivable of that currency and amount.
- Its
- A receivable's
statusbecomesreceived, withsettledAtandtxRefset, when a transfer settles it. - A cycle's
detail.stagesincludesreceipts, which runs afterreconcile. - An event cycle's
detail.eventscan includepayment_received: a client's "I have paid" check found the receivable paid.
2026-10-01: Dismissing a screening match
- New ledger action
screening_match_dismissed, in thecompliancedomain, delivered as aledger.appendedevent. It is appended when a member who can decide approvals dismisses a counterparty's screening match as not the same person.- Its
detailis{ by, counterpartyId, matchedEntityId, matchedCaption, matchedScore, screenedName, reason }. matchedEntityIdis the screening service's id for the entity dismissed;screenedNameis the counterparty's name when it was dismissed.
- Its
- Screening skips a dismissed entity for that counterparty while its name stays the same, and judges the next match, if any. The counterparty is screened again at once, so a
screen_counterpartyentry with its new verdict follows. - An event cycle's
detail.eventscan includematch_dismissed.
2026-10-01: Held milestones decided again
- New ledger action
milestone_reopened, in thecontractordomain, delivered as aledger.appendedevent. The agent appends it when it returns a held milestone toverifiedbecause a fact its decision rested on changed: the contractor's risk level or payment limit, the milestone's verification source, or the agent was paused when it held it.- Its
detailis{ milestoneId, previousStatus, followUp: { action, reason, changes } }.previousStatusisheld,followUp.actionisreopen, andchangeslists each fact that moved, in words. - The milestone's next decision entry follows in the same cycle.
- Its
- A milestone's
statuscan now go fromheldback toverifiedwithout anyone verifying it again. - An event cycle's
detail.eventscan includelimit_raised: someone raised a counterparty's payment limit and screening allows more than zero.
2026-10-01: EURC payments funded by a swap
- A live workspace can pay a EURC payable after swapping USDC for the EURC it needs, through Circle's Stablecoin Service on Arc testnet.
- New ledger action
fx_swap, in thetreasurydomain, delivered as aledger.appendedevent when a swap ends.- Its
detailis{ paysInvoiceId, swapId, state, usdcIn, eurcMinimum, eurcEstimated, eurcReceived, usdcPerEurc, costPercent, provider, adapter, approveTxHash, swapTxHash, failure, reasoning, resumed }. stateisconfirmedorfailed.eurcReceivedis the EURC the swap's transaction sent to the operating wallet, read from its receipt, ornullwhen it could not be read.resumedistruefor a swap whose first answer was lost, finished by a later cycle. Itsreasoningis thennull.- It carries
paysInvoiceId, notinvoiceId: it is not a decision on the invoice.
- Its
- New fields on a EURC payable's decision entry:
usdcDueWithin7Days;swapOffer:{ usdcIn, eurcEstimated, eurcMinimum, usdcPerEurc, costPercent, provider }when a swap was offered, ornull;swapUnavailable: why there was none, ornull;swap:{ swapId, state, usdcIn, eurcReceived, swapTxHash, reason }for the swap made to fund the payment, ornull.stateisconfirmed,pendingorfailed.decision.fundWithSwapistruewhen the model chose to pay with the swap. It appears only on a payable the wallet's EURC was short of.swapOffer.costPercentis what each EURC costs through the swap above the rate the payable was weighed at, in percent, rounded up to two places.
- Two new values of
guardrailRule:fx.swap_cost_above_cap, for a swap costing more than 3% above the quoted rate;fx.swap_usdc_short, for a swap that would leave the USDC below what falls due in USDC within 7 days.
- When a swap does not go through:
- A failed swap holds the payable with
guardrailRule: null, as a failed transfer does. Its reason is inswap.reason. - A swap still in flight at Circle leaves the payable
pending. The next cycle finishes the swap, then decides the payable again.
- A failed swap holds the payable with
2026-10-01: Milestone escrow
- A live workspace can lock a milestone's USDC in its own escrow contract on Arc testnet. Three new ledger actions, in the
contractordomain, are delivered asledger.appendedevents:escrow_deployed, once per workspace. Itsdetailis{ by, address, payer, deployer, circleContractId, txHash }.escrow_funded, when a milestone is locked. Itsdetailis{ by, milestoneId, contract, holdId, payee, amountUsdc, refundAfter, fundTxHash }.fundTxHashisnullwhen the hold was found already on chain and recorded.escrow_refunded, when a hold is taken back after its refund date. Itsdetailis{ by, milestoneId, contract, holdId, amountUsdc, refundTxHash }.
- A milestone locked in escrow is paid by releasing its hold rather than by a transfer. Its release decision's
execution.txRefis that release transaction on Arc testnet.
2026-10-01: Payment receipts
- An owner or admin can share a paid payable's receipt as a public link. Three new ledger actions, in the
apdomain, are delivered asledger.appendedevents:receipt_shared, appended once per payment, the first time it is shared. Itsdetailis{ receipt, records }and holds no names and no user ids:receiptis{ amount, token, paidAt, payee, chain, txHash, route, sourceTxHash?, feeUsdc? };chainandtxHashare where the payee was paid: the transfer on Arc testnet, or the mint on the payee's chain;routeisdirect,cctporgateway;sourceTxHashis a CCTP payout's burn;recordsis{ seq, hash }of the entry that recorded the payment.
receipt_link_renewed, when a new link replaces an earlier one or a revoked receipt is shared again. Itsdetailis{ by, receiptId }.receipt_revoked, when a receipt's link is turned off. Itsdetailis{ by, receiptId }.- None of the three carries
invoiceIdindetail: a receipt's entries are about sharing a payment, not deciding an invoice.
2026-10-01: Payouts from a Gateway balance
- A payout to a payee on another chain can go from the workspace's Circle Gateway balance as well as through CCTP. Its decision entry's
payout.routeis thengateway,payout.feeUsdcis Gateway's fee, andpayout.gatewayBalanceUsdcis the Gateway balance it was weighed against. - A decision entry for a USDC payout to another chain also carries
payout.quotes: { cctpFeeUsdc, gatewayFeeUsdc }: both routes' fees as read for that decision, eachnullwhen there was none.gatewayFeeUsdcisnullfor a workspace with no Gateway balance. - An
approval_paidentry for a new payment to another chain carries the samepayout, read when the person approved:{ chain, route, domain, feeUsdc, quotes }, withgatewayBalanceUsdcwhen the route isgateway. An approval that only records a transfer already sent carries none. - A payout keeps the route its first attempt took. A new value of
guardrailRule,bridge.gateway_balance_short, holds one that went through Gateway when the Gateway balance no longer covers it with its fee. - For a Gateway payout:
- the decision entry's
execution.txRefis the mint on the payee's chain, withexecution.destinationChainandexecution.mintTxHash. No Arc transaction belongs to one Gateway payout: Gateway burns on Arc in batches; GET /api/v1/invoicesreturns that mint as the invoice's transaction once it is paid. Until then the invoice ismatched, as a CCTP payout is.
- the decision entry's
- Three new ledger actions, in the
treasurydomain, delivered asledger.appendedevents:gateway_signer_created, whosedetailis{ by, signer, circleWalletId };gateway_delegate_added, whosedetailis{ by, depositor, signer, txHash };gateway_deposit, whosedetailis{ by, amountUsdc, depositor, signer, approveTxHash, depositTxHash, balanceUsdc }.balanceUsdcis the Gateway balance once it includes the deposit, ornullwhen Gateway had not counted the deposit yet.
2026-10-01: Invoices read from a document
- A
create_invoiceentry for an invoice read from a document carriesdocumentin itsdetail:kind:pdf,email(an.emlfile: its text and the text of its PDF attachments) ortext;sha256: the hash of the document's bytes, or of the pasted text;reader: the model that read it (anthropic,openai,deepseek), orheuristicfor the rule-based reader;changed: the form fields the member changed from what was read, amongamount,currency,dueDate,poReference,earlyPayDiscountPct,discountDeadline,memoandcounterpartyId.
- An invoice typed in carries no
document. The document itself is not stored.
2026-10-01: First screens in the compliance sweep
- Each entry in a
compliance_sweepentry'sdetail.screenednow carriesfirstScreen:truewhen the counterparty had no verdict before.changedis stilltruefor a first screen. - When a sweep includes first screens, its
summarycounts them apart: "Screened 6 of 6 counterparties: 6 for the first time, 0 changed". A sweep of re-screens only still reads "Re-screened 6 of 6 counterparties; 0 changed".
2026-10-01: Payees on other chains
- A counterparty's
chainis one ofARC-TESTNET,BASE-SEPOLIA,ARB-SEPOLIAorETH-SEPOLIA.GET /api/v1/counterpartiesreturns it as before. - A payee on a chain other than Arc testnet is paid from Arc through CCTP V2 with Circle's Forwarding Service.
- Its decision entry (
ap_pay,ap_hold,ap_flag_fraud,ap_request_info,ap_schedule) carriespayout: { chain, route: "cctp", domain, feeUsdc }indetail, wherechainis the chain id (BASE-SEPOLIA) andfeeUsdcisnullwhen Circle gave no fee. - Only a vendor can be paid on another chain; a contractor's milestones are released on Arc testnet.
- Its
executioncarriesdestinationChainandmintTxHashonce the payment was sent.execution.txRefis the burn on Arc testnet, orcctp:<Circle transaction id>while the burn has no hash yet. mintTxHashisnulluntil the Forwarding Service mints. A laterap_reconcileentry carries it.
- Its decision entry (
- Three new values of
guardrailRule, each of which holds the payable for a person:bridge.fee_above_cap, when the fee is above 10% of the amount;bridge.fee_unavailable, when Circle gave no fee;bridge.unsupported_token, for an invoice in EURC to a payee on another chain.
- A bridged invoice is
matchedfrom the burn until the mint, thenpaid.GET /api/v1/invoicesshows it so. One still not minted two hours after it was sent isheldfor a person, by anap_reconcileentry saying so.
2026-10-01: Invoices in EURC
-
An invoice can be in EURC as well as USDC.
GET /api/v1/invoicesreturns itscurrency, which is nowUSDCorEURC;amountandpaidAmountare in that currency. -
A EURC payable is paid in EURC from the operating wallet. Its decision entry (
ap_pay,ap_hold,ap_flag_fraud,ap_request_info,ap_schedule) carriescurrencyindetail, and, for EURC only:usdcValue, its value in USDC, which is what counts against the counterparty's limit;fx: { rate, source: "circle-stablecoin-quote", quotedAt, usdcMinimum }, ornullwhen Circle gave no quote;eurcBalance, the operating wallet's EURC as read for the decision, ornullwhen payments are simulated or the balance could not be read.
Those five decision entries carry
currency: "USDC"for a USDC invoice.ap_reconcilecarries nocurrency. -
Two new values of
guardrailRulefor a EURC payable, both of which hold it for a person:fx.rate_unavailable, when there was no quote to weigh it at, andtreasury.insufficient_eurc, when the wallet's EURC cannot cover the payment or could not be read. As with every rule,guardrailRuleis set when code refuses a payment or schedule the model decided on; a payable the model held itself for the same reason hasguardrailRule: null, withusdcValue: nullor aneurcBalancebelowobserved.amountin itsdetail. -
A duplicate is the same amount only in the same currency. A purchase order billed in one currency and again in the other is reported as
purchase_order_rebilled, which goes to the model and does not block on its own. -
approval_paidand thecreate_invoiceandimport_invoiceentries gaincurrencyindetail, and their summaries name it. -
The invoice CSV import takes an optional
currencycolumn. A blank or missing value means USDC.
2026-10-01: Milestones added in the app
- A member can now add a contractor milestone on the Contractors page. It starts
pendingand unverified, like any milestone inGET /api/v1/milestones. - Its
verificationSourceis the evidence link the member gave, ornull: a GitHub pull request in its canonical form (https://github.com/<owner>/<repo>/pull/<number>, which the cycle checks for a merge as before), or any otherhttps://address, which only a person verifies. - A new ledger action, delivered as a
ledger.appendedevent:create_milestone, in thecontractordomain withactor: "human". Itsdetailis{ by, milestoneId, counterpartyId, counterpartyName, amount, verificationSource }, withamountas the decimal string entered. - A new event kind,
milestone_added, may appear in an event cycle'sdetail.events. It is raised only for a milestone whose evidence is a pull request, so the merge is checked within a minute.
No /api/v1 endpoint, parameter or response schema changed.
2026-10-01: Payment timing
- An invoice can carry early-payment terms: a percent off and the date it lapses, set on the invoice form or by CSV import.
GET /api/v1/invoicesnow returnsearlyPayDiscount: { percent, deadline } | nullfor any invoice that carries them. - A payable the agent has committed to pay later reaches status
scheduled, decided again each cycle until the day it pays.GET /api/v1/invoices'sstatusfilter now acceptsscheduled. GET /api/v1/invoicesalso returnsscheduledFor(an ISO timestamp, ornull) andpaidAmount: what actually left, once an invoice's status ispaid.paidAmountstaysnullbefore then, even while a submitted transfer already carries an amount.- A new ledger action, delivered as a
ledger.appendedevent:ap_schedule, in theapdomain, recorded when the agent schedules a payable. Itsdetailcarriesdecision: { action: "schedule", payOn, reasoning, confidence },timingandtimingRule(the policy's figures, and any correction made to the model's date),requestedPayOnwhen a date was corrected,terms: { earlyPayDiscount },observed, andexecution.resultingStatus: "scheduled". - Every
ap_*decision entry (ap_pay,ap_hold,ap_flag_fraud,ap_request_info,ap_schedule) now carriestiming,timingRuleandtermsin itsdetail; an entry for a previously scheduled invoice also carriesscheduledFor. ap_payandapproval_paidgainamountPaidanddiscountTakenindetail: bothnullwhen nothing went out, or the discounted amount and the percent taken when an invoice was paid by its discount deadline.cycle_complete'sdetail.outcomesgainsscheduledCount.- A duplicate is now also refused against a payable already
scheduled, already being paid (matched), or being decided by a person on Approvals (processing), not only one alreadypaidorreceived. The refusing entry's reasoning names which of these it repeats.
2026-09-30: Payee links
- Two new ledger actions, delivered as
ledger.appendedevents, both in thecompliancedomain withactor: "human":payee_link_created, whosedetailis{ by, counterpartyId, linkId, expiresAt };payee_link_revoked, whosedetailis{ by, counterpartyId, linkId }.
- A
counterparty_address_changedentry made by a payee through a payee link hasby: null, and carriesvia: "payee_link"andlinkIdnext tocounterpartyId,fromandto. - Such a change waits for confirmation like any other; a later
counterparty_address_confirmedrecords who confirmed it.
No /api/v1 endpoint, parameter or response schema changed.
2026-09-30: What started a cycle
- A
cycle_completeledger entry'sdetailcan now carrytrigger, which says what started the cycle:"schedule"for the six-hourly run;"manual"for Run cycle now;"event"when something in the workspace gave the agent a decision to make.
- An event cycle's
detailalso carriesevents, the kinds that led to it:invoice_added,milestone_verified,payable_returned,address_confirmed,agent_resumedandsample_loaded.by, when present, is the person whose action started the cycle. - These fields are visible on
ledger.appendedevents and inGET /api/v1/ledger. - A cycle no longer starts while another one in the same workspace is running, so one workspace's cycles do not overlap.
No /api/v1 endpoint, parameter or response schema changed.
2026-09-30: Failed-payment retry
- An
approval_paidledger entry'sdetailcan now carryattempt, the transfer attempt this approval ended on (starting at 1), and, only when that attempt is a retry,retriedAfter:{ providerTxId, providerState, failureReason }for the earlier attempt Circle ended in a terminal failure. Both are visible onledger.appendedevents and inGET /api/v1/ledger. - Circle's
STUCKtransfer state is no longer a terminal failure; it is now reported the same way a transfer stillpendingis. OnlyCANCELLED,DENIEDandFAILEDend a transfer attempt.
No /api/v1 endpoint, parameter or response schema changed.
2026-09-30: Ledger signing key rotation
- An owner can rotate a workspace's ledger signing key from Settings. The rotation is a ledger entry, delivered as a
ledger.appendedevent like every other:ledger_key_rotated, in thesystemdomain, withactor: "human". Itsdetailis{ from, to, by }: the retired key's id, the new key's id, and the owner who rotated. See Key identity and rotation. - From that entry on,
signingKeyIdis the new key's id. Earlier entries keep the old id and keep verifying against the retired key. ledgerRetiredKeyCountinGET /api/v1/statusnow counts the workspace's own retired keys.
No /api/v1 endpoint, parameter or response schema changed.
2026-09-30: Counterparty limit changes
- A new ledger action, delivered as a
ledger.appendedevent:counterparty_limit_changed, in thecompliancedomain. Itsdetailis{ by, counterpartyId, from, to, currentLimit }, wherefromandtoare the configured limits in USDC andcurrentLimitis the limit the counterparty's risk now allows. A client's limit may benull.
No /api/v1 endpoint, parameter or response changed.
2026-09-30: Counterparty address changes
- Two new ledger actions, delivered as
ledger.appendedevents like every other entry, both in thecompliancedomain:counterparty_address_changed, whosedetailis{ by, counterpartyId, from, to }.fromortoisnullwhen there was no address before, or it was cleared.counterparty_address_confirmed, whosedetailis{ by, counterpartyId, address, via }.viais"approval"when approving a payment confirmed it, and"confirm"when someone confirmed it on the counterparty.
- An agent decision entry (
ap_payand the otherap_*actions) can now carryguardrailRule: "counterparty.address_unconfirmed". It means the payment was held because the counterparty's address changed and no one has confirmed it. Itsobservedobject gainsaddressUnconfirmed, a boolean. - An
ap_reconcileentry can now carrynotResubmittedBecause: "counterparty.address_unconfirmed", beside the existing"counterparty.high_risk". A payment that never reached the network is not sent again to a changed address that no one has confirmed; it is held for a person.
No /api/v1 endpoint, parameter or response changed.
2026-09-29: MCP server
- A remote MCP server at
https://www.vestiarion.xyz/api/mcp, over Streamable HTTP. An AI agent connects with a workspace API key, sent asAuthorization: Bearer <key>, and reads that workspace's records through one tool per/api/v1read operation. A tool returns the operation's JSON exactly. See MCP server. - A missing, malformed, unknown or revoked key answers
401with aWWW-Authenticateheader; a key without thereadscope answers403. - There are no write tools, and no OAuth.
No /api/v1 endpoint, parameter or response changed.
2026-09-29: Webhooks sent right after each append
- A
ledger.appendeddelivery now goes out right after the request that appended its entry (approving a payment, pausing the agent, changing a member, a key or an endpoint), not on the next scheduled dispatch. Entries appended by the agent's scheduled run still go out right after that run. The 10-minute schedule remains for retries. See Timing.
No payload, header or signature changed.
2026-09-29: Developer docs, OpenAPI document and llms.txt
- These docs, at
/docs: a quickstart, guides, and a reference page for every endpoint, with a Try it panel that sends a real request with your key. GET /api/v1/openapi.json: an OpenAPI 3.1 document for every/api/v1endpoint. It is public and needs no key.- A Markdown view of every page at its URL plus
.md, and/llms.txtand/llms-full.txt: see AI integration. - Cursors are checked per endpoint. A
cursorthat the endpoint could not have issued, such as a ledger cursor sent to/invoicesor an altered one, now answers400 invalid_request. It could reach the database before and answer500. See Pagination.
No other endpoint, parameter or response changed.
2026-09-29: Signed webhooks
- An owner or an admin can add up to 5 HTTPS endpoints per workspace in Settings. Each one receives a
ledger.appendedevent for every new ledger entry, and awebhook.testevent on demand. See Webhooks. - Every delivery is signed with HMAC-SHA256 in the
Vestiarion-Signatureheader, using the endpoint's own secret, shown once when it is added. See Verifying signatures. - Delivery is at least once and not in order. A failed delivery is retried up to 7 attempts in total, and an endpoint is disabled after 20 consecutive failed attempts. See Retries and disabling.
2026-09-29: Workspace API keys
/api/v1now authenticates with a workspace API key,vxk_<prefix>_<secret>, sent asAuthorization: Bearer <key>. An owner or an admin creates keys on the workspace's Settings page; each key is shown once and reads only its own workspace. See Authentication.- Breaking: the platform token,
AGENT_API_TOKEN, no longer opens/api/v1, and answers401. It had read only the founding workspace. Move any caller that used it to a workspace key. - A missing, malformed, unknown or revoked key answers the same
401 unauthorized. A key whose scopes do not cover a route answers403 forbidden. GET /api/v1/statusreports the calling key's own workspace, and itsconfigurationno longer includes the deployment'sdatabaseblock.