Mercury
@shrug/mercuryv2026.08.18.1
01README
Mercury banking API (/api/v1) read-only source model: discover accounts and snapshot transactions as the canonical BankTxn[] contract (settled-only by default). Bearer token auth (vaulted, read-only token — no IP allowlist). The amount-sign convention (negative == outgoing debit) lives in one tested decider, verified against a live response.
02Models
@shrug/mercuryv2026.08.02.1mercury.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| ownerDrawFrom? | string | Income window start (YYYY-MM-DD). Default (unset) ⇒ today UTC. |
| ownerDrawTo? | string | Income window end (YYYY-MM-DD). Default (unset) ⇒ today UTC. |
| ownerDrawTaxPct? | number | Tax set-aside rate, 0..1. Default (unset) ⇒ 0.30. |
| ownerDrawAmount? | number | Explicit draw amount in dollars. Omitted ⇒ the report SUGGESTS the |
| ownerDrawModelName? | string | Model INSTANCE name used in the report's emitted |
| ownerDrawTaxSourceAccountId? | string | internalTransfer source for the tax reserve (general savings). |
| ownerDrawTaxDestAccountId? | string | internalTransfer destination for the tax reserve (the tax-reserve account). |
| ownerDrawSourceAccountId? | string | sendMoney source for the external-ACH draw (operating account). |
| ownerDrawRecipientId? | string | Mercury recipient id for the draw's sendMoney leg. |
fn listAccounts()
Discover Mercury accounts — DEPOSIT accounts (`GET /accounts`) plus the
fn listTransactions(accountId: string, start?: string, end?: string)
Snapshot an account's transactions as canonical BankTxn[] (§6).
| Argument | Type | Description |
|---|---|---|
| accountId | string | Mercury account id (from listAccounts) |
| start? | string | Filter: start date (YYYY-MM-DD) |
| end? | string | Filter: end date (YYYY-MM-DD) |
fn internalTransfer(sourceAccountId: string, destinationAccountId: string, amount: number, note?: string, dryRun: boolean, confirm?: string)
WRITE (WI-2, design §4/§7): move funds between the org's OWN Mercury
| Argument | Type | Description |
|---|---|---|
| sourceAccountId | string | Source account id — a DEPOSIT account (from listAccounts) |
| destinationAccountId | string | Destination account id — one of the org's own accounts |
| amount | number | Transfer amount in dollars (>= 0.01) |
| note? | string | Optional note — part of the idempotency intent and the POST body |
| dryRun | boolean | When true (default) validate + preview only, NO write. A live send |
| confirm? | string | On dryRun=false, MUST equal the idempotencyKey shown by the dry-run |
fn listRecipients()
Discover Mercury recipients (`GET /recipients`, WI-3): the source of
fn sendMoney(accountId: string, recipientId: string, amount: number, paymentMethod: enum, note?: string, externalMemo?: string, dryRun: boolean, confirm?: string)
WRITE (WI-3, design §4/§7): send an EXTERNAL owner's-draw ACH from an
| Argument | Type | Description |
|---|---|---|
| accountId | string | Funding account id — a DEPOSIT account (from listAccounts). |
| recipientId | string | Recipient id — a pre-registered recipient (listRecipients) |
| amount | number | Send amount in dollars (>= 0.01) |
| paymentMethod | enum | Payment rail. v1 supports ACH only (no wire/check/international). |
| note? | string | Optional internal note — part of the idempotency intent AND the body |
| externalMemo? | string | Optional recipient-facing memo — sent in the body but NOT part of |
| dryRun | boolean | When true (default) validate + preview only, NO write. A live send |
| confirm? | string | On dryRun=false, MUST equal the idempotencyKey shown by the dry-run |
Resources
accounts(infinite)— A snapshot of Mercury accounts (`/accounts`) for id discovery
transactions(infinite)— A snapshot of canonical BankTxn[] (§6) for one account (`/account/{id}/transactions`)
internalTransfer(infinite)— The record of an internalTransfer (WI-2): a dry-run preview or a live
recipients(infinite)— A snapshot of Mercury recipients (`GET /recipients`, WI-3) — the source
sendMoney(infinite)— The record of a sendMoney (WI-3): a dry-run preview or a live external
03Reports
@shrug/mercury/owner-drawmodel
owner_draw.ts
Owner-draw planner: income over a window, tax reserve + draw split, current balances, and the copy-pasteable internalTransfer/sendMoney commands (no writes)
mercurybankingowner-draw
04Previous Versions
2026.08.02.1
Credit-account (IO card) discovery: listAccounts merges GET /credit; nullable kind; toCreditAccount; resilient deposit-only degrade. Includes prior unpublished mcc/owner-draw config signals.
2026.07.19.1
05Stats
A
100 / 100
Downloads
1
Archive size
55.2 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License declared1/1earned
- Verified public repository2/2earned
Repository
https://github.com/shrugpw/swamp-mercury06Platforms
07Labels