Schemas

Minor-unit integer string. A negative value appears only on signed ledger rows; every creating request uses MoneyPositive and the router rejects zero or negative amounts.

ISO 4217 code or a stablecoin symbol (USDC, USDC.e, pathUSD).

Minor-unit integer string. A negative value appears only on signed ledger rows; every creating request uses MoneyPositive and the router rejects zero or negative amounts.

ISO 4217 code or a stablecoin symbol (USDC, USDC.e, pathUSD).

Minor-unit integer string. A negative value appears only on signed ledger rows; every creating request uses MoneyPositive and the router rejects zero or negative amounts.

ISO 4217 code or a stablecoin symbol (USDC, USDC.e, pathUSD).

A money value. amount is a minor-unit integer as a string; decimals states the scale so a client never re-derives it (USDC is 6). Floats never appear on a money path.

Asset symbol to send on chain (e.g. USDC, USDC.e).

Numeric chain id, when chain alone does not pin a single concrete network — e.g. tempo covers both Moderato (testnet, 42431) and Mainnet (4217), and asset's contract address is not guaranteed distinct across them (a signer must not infer the network from the symbol alone). Absent when the rail has no such ambiguity.

On-chain contract address asset resolves to on chain, verbatim case, when this attempt has one frozen (e.g. the TIP-20 token address a Tempo Pay splitter accepts). The authoritative send target for an in-app signer — never re-derive it from asset against a local registry, which can drift from what the attempt actually froze. Absent when the rail's asset has no single on-chain contract identity.

A money value. amount is a minor-unit integer as a string; decimals states the scale so a client never re-derives it (USDC is 6). Floats never appear on a money path.

A money value. amount is a minor-unit integer as a string; decimals states the scale so a client never re-derives it (USDC is 6). Floats never appear on a money path.

On-chain memo / reference when the rail requires one; never on Tempo pay-ins.

The third party that moves the funds on this leg, when one does (relay on a crypto_relay payment). Absent when the payer pays the destination directly.

D-111's classification. Binding on every BankDepositInstructions consumer, present and future: classify the beneficiary name the provider actually returned on THIS record — never derived from the currency or the rail, and never invented when the provider returned no name at all (null, explicit, never merely omitted). own_name: an ordinary beneficiary name (the holder's own, or — for a payment-links payer session — whatever name the provider actually returned). provider_name: the beneficiary is the provider's own settlement entity (e.g. Bridge's "Bridge Building S.A." prefix — KNOWN FALSE POSITIVE: a genuine beneficiary whose own name happens to start with "bridge", e.g. "Bridgewater Ltd", also reads as provider_name; tightening the match is a follow-up, not fixed here). developer_name: a memo-matched, flexible-amount collection account issued in the developer's own name ("Swaps") — payment-links bank-rail pay-ins are EXPECTED to route through exactly this shape, though that expectation has not yet been confirmed against a live provider response for that specific endpoint.

UK Faster Payments — 6-digit domestic sort code, alongside account_number.

Mexico SPEI — the 18-digit interbank account key (replaces account_number/routing_number for this rail).

Brazil PIX — the key the payer sends to; often the only field this rail populates.

The transfer memo/reference text. When matching is reference, this is what the provider matches the deposit BY — the payer must type it into their bank transfer exactly, or the deposit lands unmatched on a pooled account. When matching is account_number, this is recommended (it speeds up reconciliation) but never required — the deposit is already matched by the account it landed on. Absent matching altogether (a record from before this field existed), treat reference as required, matching this schema's pre-existing behavior.

How the provider attributes THIS deposit to the payer, independent of holder_kind. reference: a memo-matched transfer on a pooled account — the provider matches by the reference text alone, which the payer must type exactly, or the deposit is unmatched. account_number: the account itself (account_number/iban/clabe/sort_code, whichever this rail populates) is unique to this customer, so the provider matches by account rather than memo; reference, when present, is recommended for faster reconciliation but is never required to complete the payment. Omitted when the provider payload carries no field this schema could use to decide (e.g. pix, where a Pix key alone is already a complete, self-matching destination).

A1-2: required (still nullable) — every producer already emits null rather than omitting the field when there is no next page, so this only removes a third, unused wire state (absent) a strict client had to handle for nothing.

Prefixed, opaque. The prefix is part of the contract; the suffix is never parsed.

The account's id. Never looked up directly by a business key or a session — reached only as "the selected account" (GET /account) or via GET /accounts (mine).

individual or business. Follows the account owner's customer (customers.get, GET /customers/{id}): it is the type Swaps has recorded for that customer, not a live read from our verification partner. Swaps sets it whenever a customer of the owner is recorded or changes type, in either direction (business when any owner has a business customer). Until the owner has a customer, the type the account was opened with. Not writable through PATCH /account, and customers.create does not write it. A test-mode account keeps the type it was created with. Not itself a KYB projection (RESOURCE-MODEL §2.4).

ISO 3166-1 alpha-2. null until a source column exists (проверить — public.users has none today).

null until a source column exists (проверить — public.users has none today). Always null for an sk_test_ key (test mode).

Reason for a restricted/suspended/blocked state stays internal — never on the wire.

L4-9 — an EXPLICIT opt-in support contact for the payer surfaces (PaymentSession.merchant_contact on /pay/<token>). NEVER derived from email above (the login e-mail), KYC, Bridge or settlement data — null until the holder sets it here. Also null for an sk_test_ key: withheld in test mode, not unset.

BL-25 (D-PF-9a) — the persona's market for the embedded Buy & sell widget, which previously had no signal to resolve country/currency from and fell back to the public-site default regardless of who was signed in. A read-only projection over the same static country→currency registry the public-site widget itself defaults from (_shared/services/config.ts's countries.json, ISO 4217 local currency per ISO 3166-1 alpha-2 country) — never a live/provider-routed pick, so this carries no money path. Not itself writable. Resolved, in order of trust, from country above (declared once at POST /accounts, validated against this same registry there), then the holder's Bridge KYC address country (not published as its own field), then the public-site no-signal default. Always present — source names which case applied, and a consumer MUST treat source: 'default' as "no persona signal at all" rather than seed anything from it (it is the exact value an anonymous, signed-out visitor gets).

For an sk_test_ key (test mode) always {marketing: false, product_tips: true}, not the owner's values; a test-mode dashboard session sees its own.

Cross-device UI preferences persisted server-side (R18 TA-G9) — not UI-private, since prod already syncs them. For an sk_test_ key (test mode) always {}, not the owner's values; a test-mode dashboard session sees its own.

Present only when ?expand=readiness (or ?expand=readiness,setup_guide) is requested on GET /account AND that expansion succeeded (API-PERF-1 M5, fix round 1) — the exact GET /account/readiness payload, merged in. Absent, never null, when not requested; also absent, with a matching entry in expand_errors, when requested but the expansion itself failed (an unresolvable owner or a Bridge outage) — a failed expansion never fails the account read.

Present only when ?expand=setup_guide (or ?expand=readiness,setup_guide) is requested on GET /account AND that expansion succeeded (API-PERF-1 M5, fix round 1) — the exact GET /account/setup_guide payload, merged in. Absent, never null, when not requested; also absent, with a matching entry in expand_errors, when requested but the expansion itself failed.

Present only when at least one requested ?expand= field could not be computed (API-PERF-1 fix round 1). The account read itself, and any OTHER requested expansion that DID succeed, are still published — this names exactly which field is missing and why, rather than failing the whole response the way the standalone GET /account/readiness/GET /account/setup_guide routes do on the same failure. Absent entirely when ?expand= is unset, or when every requested field succeeded.

Who is making this request, on this account: the credential type and, for a session, the caller's membership role. Read it before offering an owner/admin-only action (e.g. changing display_name with PATCH /account, API keys, the wallet families) instead of learning it from a 403 role_denied. It comes from the same resolved credential the role gate checks, never a second lookup. Present on GET /account and PATCH /account, and on the one GET /accounts item this request's credential resolved to (the selected account). Absent, not null, on any other account (the other GET /accounts items, POST /accounts): this request never resolved a role there — select that account with Swaps-Account and read GET /account. Published in test and live mode alike.

The account's name. 1–80 characters; leading and trailing whitespace is trimmed, and a value that is empty after trimming is refused with 400 invalid_request, param: display_name. Only an account owner or admin may change it (a member gets 403). Payment links, the payer page, receipts and invoice emails show the profile name of the person the link is recorded under (for a link created through /v1, the account's first owner), not this account name. On a live account, saving this name also sets it for each owner who belongs to no other live account, so their payers see it at once. An owner who belongs to more than one live account keeps their current name on all of them until payer names are resolved per account.

L4-9 — the opt-in support contact the payer surfaces may show (§0.12 PATCH null-clears convention): omitted leaves it unchanged, an object sets it, explicit null clears it back to unset. At least one of email/url must be present on a set (never a bare {}).

ISO 3166-1 alpha-2. Optional — unset until the holder declares one. Fix round 1 (P2): validated against the same countries.json registry market (on Account) reads from — case/whitespace-normalized on write, an unrecognised value is a 400 invalid_request (param: 'country'), never silently stored and never able to disagree with the resolved market.country for the same account.

A1-2: required (still nullable) — every producer already emits null rather than omitting the field when there is no next page, so this only removes a third, unused wire state (absent) a strict client had to handle for nothing.

Short supporting facts rendered under the body copy (e.g. a pending-count sentence).

Present, and true, only when the Bridge customer status this card was built from is the last persisted snapshot because the live read failed (Customer.degraded). The card then states no verified identity. Absent on a live read.

Present, and true, only when the Bridge customer status this guide was built from is the last persisted snapshot because the live read failed (Customer.degraded). verify_identity and confirm_eligible then report done: false even where the snapshot says verified, and next_step never names a step withheld for that reason: it is the step a live read of the same status names. Absent on a live read.

Pointer to the backing /v1 resource — read it there for the full projection.

The underlying object's own status string, verbatim. Not a shared cross-product vocabulary — collisions between products' status words are named in R18 §5 and are not resolved by this field.

This resource's own six-bucket set (draft, pending, processing, completed, failed, returned) — not a vocabulary shared with payment_links (open, needs_attention, paid, ended) or with payouts/payroll_runs/orders (needs_you, in_progress, done). Read each of those resources' own status_group for their set.

A money value. amount is a minor-unit integer as a string; decimals states the scale so a client never re-derives it (USDC is 6). Floats never appear on a money path.

Nullable — absent when no fresh conversion exists. Never inflate the figure by omitting a stale one.

Null when this row has no single owning provider (e.g. a payroll run).

A1-2: required (still nullable) — every producer already emits null rather than omitting the field when there is no next page, so this only removes a third, unused wire state (absent) a strict client had to handle for nothing.

One (product, status_group) cell of ActivitySummary.by_product_status (K8c, §52 C4-D14) — an honest count plus a minor-unit sum, never client math. amount is null when the cell has no rows, when its rows carry more than one currency OR the same currency at more than one decimal scale (summing across either would need an FX rate or a rescale this endpoint does not fabricate), or when a row's amount could not be parsed: count still reflects every row in the cell, but a sum that quietly excluded the unparseable row's contribution, or combined mismatched scales, would be a wrong number, not an honest one.

One (product, status_group) cell of ActivitySummary.by_product_status (K8c, §52 C4-D14) — an honest count plus a minor-unit sum, never client math. amount is null when the cell has no rows, when its rows carry more than one currency OR the same currency at more than one decimal scale (summing across either would need an FX rate or a rescale this endpoint does not fabricate), or when a row's amount could not be parsed: count still reflects every row in the cell, but a sum that quietly excluded the unparseable row's contribution, or combined mismatched scales, would be a wrong number, not an honest one.

One (product, status_group) cell of ActivitySummary.by_product_status (K8c, §52 C4-D14) — an honest count plus a minor-unit sum, never client math. amount is null when the cell has no rows, when its rows carry more than one currency OR the same currency at more than one decimal scale (summing across either would need an FX rate or a rescale this endpoint does not fabricate), or when a row's amount could not be parsed: count still reflects every row in the cell, but a sum that quietly excluded the unparseable row's contribution, or combined mismatched scales, would be a wrong number, not an honest one.

One (product, status_group) cell of ActivitySummary.by_product_status (K8c, §52 C4-D14) — an honest count plus a minor-unit sum, never client math. amount is null when the cell has no rows, when its rows carry more than one currency OR the same currency at more than one decimal scale (summing across either would need an FX rate or a rescale this endpoint does not fabricate), or when a row's amount could not be parsed: count still reflects every row in the cell, but a sum that quietly excluded the unparseable row's contribution, or combined mismatched scales, would be a wrong number, not an honest one.

One (product, status_group) cell of ActivitySummary.by_product_status (K8c, §52 C4-D14) — an honest count plus a minor-unit sum, never client math. amount is null when the cell has no rows, when its rows carry more than one currency OR the same currency at more than one decimal scale (summing across either would need an FX rate or a rescale this endpoint does not fabricate), or when a row's amount could not be parsed: count still reflects every row in the cell, but a sum that quietly excluded the unparseable row's contribution, or combined mismatched scales, would be a wrong number, not an honest one.

One (product, status_group) cell of ActivitySummary.by_product_status (K8c, §52 C4-D14) — an honest count plus a minor-unit sum, never client math. amount is null when the cell has no rows, when its rows carry more than one currency OR the same currency at more than one decimal scale (summing across either would need an FX rate or a rescale this endpoint does not fabricate), or when a row's amount could not be parsed: count still reflects every row in the cell, but a sum that quietly excluded the unparseable row's contribution, or combined mismatched scales, would be a wrong number, not an honest one.

Per-product × lifecycle-status totals for the product hub sub-lines and Today tiles (K8c, §52 C4-D14) — the same six products and six status groups as by_product/by_status_group, crossed. Computed over the same capped read as the rest of this resource.

Prefixed, opaque. The prefix is part of the contract; the suffix is never parsed.

The exact same catalogue as EventType, as the RESPONSE-side form (Event.type, WebhookEvent.type, WebhookEndpoint.event_types): an unrecognized member is an opaque string, never a deserialization failure, because a delivery may carry a type added after the client was generated. A REQUEST that names a type still validates against the closed EventType and answers 400 invalid_request for an unknown name. Kept as its own schema so the open-enum marker never reaches a request field. x-swaps-event-status is the same generated live/catalogued marking as on EventType.

The Swaps-Version this event was minted under.

Null for events with no originating API request (a webhook reducer, a cron sweep, a watcher).

The affected resource's own allowlisted projection at the time of the event — never the raw internal row. Deliberately THINNER than a GET of the same resource: fields that need gateway-only computation (a payment link's payable_rails/payable_rail_kinds, its line items) are never recomputed here, so they are absent from this projection even where GET would carry them — never guessed or backfilled from a stale value.

A short, human-readable summary of the event, built server-side from the producer's own record of what happened (e.g. 3 rows · USD, Jamie Rivera · bank account) — never a substitute for data.object, and never more than what the resource's own published projections already disclose, and never an internal actor's identity (an account's approving user, an operator) unless that identity is itself a published field elsewhere the same caller can already read. Populated per event type by the producer that emits it (K7b ships it for payroll_run.*/payroll_item.*); absent, not an empty string, where no producer has one yet.

The exact same catalogue as EventType, as the RESPONSE-side form (Event.type, WebhookEvent.type, WebhookEndpoint.event_types): an unrecognized member is an opaque string, never a deserialization failure, because a delivery may carry a type added after the client was generated. A REQUEST that names a type still validates against the closed EventType and answers 400 invalid_request for an unknown name. Kept as its own schema so the open-enum marker never reaches a request field. x-swaps-event-status is the same generated live/catalogued marking as on EventType.

The receiving endpoint's pinned Swaps-Version.

A1-2: required (still nullable) — every producer already emits null rather than omitting the field when there is no next page, so this only removes a third, unused wire state (absent) a strict client had to handle for nothing.

Prefixed, opaque. The prefix is part of the contract; the suffix is never parsed.

Public https only. Rejected at create/update time if it is a swaps.app host or a Swaps project's own supabase.co host, or resolves to a private, link-local, loopback or otherwise reserved destination (SSRF hardening); the delivery worker re-resolves and re-checks the SAME way immediately before every send attempt and never follows a redirect — a 3xx response is recorded as a failed delivery attempt, not a success. This narrows, but does not eliminate, a DNS-rebinding window: the guard's own resolution and the subsequent fetch() are two separate DNS lookups a hostile or compromised resolver could answer differently (docs/api/WEBHOOKS.md §7).

Event types this endpoint receives. Empty means "all" (every type this account can ever emit, present and future). An unknown or retired name is 400 invalid_request, at create and update alike (validated against the closed EventType at that time — this response echo is open only because it is an A1-2 response field, not because an unrecognized value can actually appear here). A type marked catalogued in EventType's x-swaps-event-status is accepted but delivers nothing until its outbox allowlist ships.

Set only when enabled is false: manual (the owner disabled it via update) or auto_disabled_repeated_failures (K9's own auto-disable after too many consecutive fully-exhausted deliveries — see webhook_deliveries.status). Null whenever enabled is true.

The signing secret's own non-secret prefix (e.g. whsec_ab12) — always present once an endpoint has a secret, safe to display anywhere the full secret is not (it never re-derives the full value).

The full signing secret, in cleartext. Present ONLY in the response to create and rotate_secret — stored hashed thereafter, never returned again and never re-derivable.

Public https only. A private, link-local, loopback or otherwise reserved destination is rejected, and so is any swaps.app host or a Swaps project's own supabase.co host (the platform never delivers to itself).

Subset of the closed event registry this endpoint receives. Omitted or empty means "all". An unknown or retired name is 400 invalid_request. A type marked catalogued in EventType's x-swaps-event-status is accepted but delivers nothing until its outbox allowlist ships.

Public https only. A private, link-local, loopback or otherwise reserved destination is rejected, and so is any swaps.app host or a Swaps project's own supabase.co host (the platform never delivers to itself).

An unknown or retired name is 400 invalid_request.

Setting false disables the endpoint (disabled_reason becomes manual) and halts future deliveries — past deliveries stay in the log. Setting true re-enables it and clears disabled_reason, including one an auto-disable had set.

A1-2: required (still nullable) — every producer already emits null rather than omitting the field when there is no next page, so this only removes a third, unused wire state (absent) a strict client had to handle for nothing.

Prefixed, opaque. The prefix is part of the contract; the suffix is never parsed.

How many delivery attempts this row has made so far (the worker's own retry schedule; see docs/api/WEBHOOKS.md).

pending: never yet attempted, due now. succeeded: a 2xx response — terminal. failed: the most recent attempt failed and a further retry is already scheduled at next_attempt_at (automatic — no action needed). exhausted: every scheduled attempt failed and no further retry will happen — replay it explicitly with webhook_deliveries.replay.

The HTTP status the endpoint returned, or null if the attempt never got a response (timeout, DNS/SSRF refusal, connection error).

Round-trip time in milliseconds for the most recent attempt. The response BODY is never stored.

A short machine-readable failure reason for the most recent attempt (e.g. timeout, connection_refused, non_2xx_response, url_not_allowed). Never the endpoint's response body.

Set once, when status first becomes succeeded.

A1-2: required (still nullable) — every producer already emits null rather than omitting the field when there is no next page, so this only removes a third, unused wire state (absent) a strict client had to handle for nothing.

Prefixed, opaque. The prefix is part of the contract; the suffix is never parsed.

rail: crypto only.

rail: crypto only. Case-preserved verbatim — never lowercased.

rail: iban only.

rail: iban or swift.

rail: ach only.

rail: ach, faster_payments or swift.

rail: faster_payments only.

rail: pix only.

rail: pix only.

rail: spei only.

rail: swift only.

rail: crypto only — the latest screening of address on network by this account, from screenings.create or address_book.recheck. network is matched the way screenings.create reads chain (a chain id or name, case-insensitive), so an entry saved as Ethereum carries a screening recorded under chain 1. Null only when no such screening exists: no /v1 screening of it yet (checks made in the v1 dashboard are not carried over, so null does not mean never checked), or screening does not cover the entry — a network such as Tempo, or an address that cannot exist on its network — and its address_book.recheck answers 409 network_not_supported, never an Ethereum verdict.

screened_at of screening; null exactly when screening is null — a check made in the v1 dashboard is not carried over.

self for the holder's own destination, third-party once a beneficiary attestation exists.

Null until a beneficiary attestation exists. Set to individual/legal_entity/vasp_customer by address_book.beneficiary.update; set to self_verified/self_unverified by the dashboard's proof-of-control flow (not itself exposed on /v1).

Read-only. Null until the destination is verified through the dashboard's proof-of-control flow — that verification step is not exposed on /v1 (out of scope for this operation). micro_deposit is published because a live v1 writer already uses it, even though today's DB CHECK constraint has not been widened to accept it (a separate v1 bug) — publishing it now costs nothing, no consumers exist yet.

Read-only. Non-null rows are what the address-book hub counts as "verified".

Read-only. A Supabase Storage object key in a private bucket — not a directly fetchable public URL.

True once a transfer through this destination triggered EU TFR / MiCA / FATF R.16 evaluation.

Null until a transfer through this destination has been Travel-Rule-attested. Stamped only by the transfer-time attestation (attestTransfer, mid-transfer) — never written by any /v1 operation, including address_book.beneficiary.update.

The saved beneficiary's name. Null until a beneficiary attestation exists. Set by address_book.beneficiary.update. No pattern/length constraint on this READ shape, deliberately — so a row already stored before a request-side constraint existed can never fail the whole list/get response, the same failure mode finding #5 flagged for proof_of_control_method. The constraint lives on the request schema (TravelRuleAttestationCreateRequest) instead.

ISO 3166-1 alpha-2, uppercased on write. Null until a beneficiary attestation exists.

The counterparty VASP's name. Only set when beneficiary_subtype is vasp_customer.

ISO 3166-1 alpha-2, uppercased on write. Only set when beneficiary_subtype is vasp_customer.

Saved as sent; any network can be saved. Screening covers only the networks ScreeningCreateRequest.chain lists — an entry on any other reads screening: null and its address_book.recheck answers 409 network_not_supported.

Case-preserved verbatim — never lowercase a BTC, Tron or Solana address.

Legal name of the account owner, as the bank holds it (a person's full name or a company's registered name). A payment link settles to this destination under this name. Blank after trimming is refused. Stored trimmed and not returned on a read.

Legal name of the account owner, as the bank holds it (a person's full name or a company's registered name). A payment link settles to this destination under this name. Blank after trimming is refused. Stored trimmed and not returned on a read.

Legal name of the account owner, as the bank holds it (a person's full name or a company's registered name). A payment link settles to this destination under this name. Blank after trimming is refused. Stored trimmed and not returned on a read.

Legal name of the account owner, as the bank holds it (a person's full name or a company's registered name). A payment link settles to this destination under this name. Blank after trimming is refused. Stored trimmed and not returned on a read.

Legal name of the account owner, as the bank holds it (a person's full name or a company's registered name). A payment link settles to this destination under this name. Blank after trimming is refused. Stored trimmed and not returned on a read.

Legal name of the account owner, as the bank holds it (a person's full name or a company's registered name). SWIFT destinations are not a payment-link settlement destination today: activate answers 422 settlement_rail_unsupported; use iban, ach, faster_payments, pix or spei. Blank after trimming is refused. Stored trimmed and not returned on a read.

ISO 3166-1 alpha-2, either case (uppercased on write).

Required when beneficiary_subtype is vasp_customer; refused blank, exactly like the dashboard form.

ISO 3166-1 alpha-2, either case (uppercased on write). Only meaningful when beneficiary_subtype is vasp_customer.

A1-2: required (still nullable) — every producer already emits null rather than omitting the field when there is no next page, so this only removes a third, unused wire state (absent) a strict client had to handle for nothing.

Prefixed, opaque. The prefix is part of the contract; the suffix is never parsed.

Case-preserved verbatim.

Derived, coarser than risk_level. Still a signal, never a block decision.

A suggestion the caller may act on — never an authorization by itself.

Free-form, source-shaped detail — never re-typed per source.

The sources actually checked, so a client can see what was not.

Case-preserved verbatim — never lowercase a BTC, Tron or Solana address.

The network to screen on, by chain id or name, case-insensitive: Ethereum (1, eth), BNB Chain (56, bsc), Polygon (137), Arbitrum (42161), Optimism (10), Base (8453), Avalanche (43114), bitcoin, tron, solana, xrp (XRP Ledger), ton, cardano, cosmos. Any other value — blank, tempo, litecoin — whatever the address, and an address that cannot exist on the named network (an EVM address on bitcoin, a Bitcoin address on tron) are refused 409 network_not_supported; nothing is ever screened as Ethereum by default. An address is judged by the named network's own address format; on solana that is any base58 string of 32–44 characters.

A1-2: required (still nullable) — every producer already emits null rather than omitting the field when there is no next page, so this only removes a third, unused wire state (absent) a strict client had to handle for nothing.

Prefixed, opaque. The prefix is part of the contract; the suffix is never parsed.

True when this report was served from the 30-day cache rather than spending a fresh credit.

A1-2: required (still nullable) — every producer already emits null rather than omitting the field when there is no next page, so this only removes a third, unused wire state (absent) a strict client had to handle for nothing.

The origin transaction hash to trace forward from (the incident transfer, e.g. the transaction that sent funds to a scammer) — a trace always starts from a specific transaction, never a bare address, since an address alone has no single "flow" to follow.

Prefixed, opaque. The prefix is part of the contract; the suffix is never parsed.

A short risk brief on each side of the transaction.

Signed credit delta — negative for a consumption, positive for a purchase, refund or grant.

The screened address this event relates to, when one exists.

A1-2: required (still nullable) — every producer already emits null rather than omitting the field when there is no next page, so this only removes a third, unused wire state (absent) a strict client had to handle for nothing.

Lifetime, exact row count of every credit_events entry for this account, across all type values — never capped by limit/cursor pagination and never limited to the page currently returned in data. Omitted (not null, not 0) on the rare failure of the underlying count query — a caller must treat a missing field as "unknown right now", not as zero.

Displayed side by side with GET /v1/credits's own total_checks as "N events · M reports" — never summed. The two counters are not on the same basis and are not reconcilable against each other: events_total is an append-only row count (it includes the refund row itself, alongside the consume_free/consume_paid row it refunds), while total_checks is a net counter that is incremented on consume and DECREMENTED, clamped at zero, on refund. Summing them double-counts every refunded check, and the two drift further apart with every refund an account accumulates.

A Stripe Checkout session url — redirect the holder there to complete the purchase.

Prefixed, opaque. The prefix is part of the contract; the suffix is never parsed.

sk_live_ or sk_test_, matching livemode.

The Swaps-Version this key pins requests to when the caller sends no Swaps-Version header (API-CANON §3, RESOURCE-MODEL §0.6). A request that does send the header overrides this default for that call only; this field is unaffected.

A key created before the screenings.* rename may still list the legacy screening.read/screening.write.

<resource>.<read|write>. The legacy screening.read/screening.write are deprecated aliases, accepted until the next Swaps-Version date and stored as screenings.read/screenings.write.

Optional; defaults to the current Swaps-Version when omitted.

Prefixed, opaque. The prefix is part of the contract; the suffix is never parsed.

sk_live_ or sk_test_, matching livemode.

The Swaps-Version this key pins requests to when the caller sends no Swaps-Version header (API-CANON §3, RESOURCE-MODEL §0.6). A request that does send the header overrides this default for that call only; this field is unaffected.

A key created before the screenings.* rename may still list the legacy screening.read/screening.write.

The full sk_live_… / sk_test_… value, in cleartext. Present only in the FIRST live response to create/roll — stored hashed thereafter, never returned again and never re-derivable. A replayed Idempotency-Key against the same request gets the same body back with this field redacted to null, never the cleartext a second time (AuthenticatedRoute.secretFields, the same mechanism K9 introduced for webhook_endpoints.create/.rotate_secret).

A1-2: required (still nullable) — every producer already emits null rather than omitting the field when there is no next page, so this only removes a third, unused wire state (absent) a strict client had to handle for nothing.

Prefixed, opaque. The prefix is part of the contract; the suffix is never parsed.

The operationId this call resolved to, e.g. screenings.create.

A1-2: required (still nullable) — every producer already emits null rather than omitting the field when there is no next page, so this only removes a third, unused wire state (absent) a strict client had to handle for nothing.

A Money value that must be zero or positive (never negative) — for a real figure that may legitimately be zero, e.g. a free/included line item's unit price. Money itself permits a leading - for signed ledger rows; this variant never does.

Optional unit of measure. Design-forward (RESOURCE-MODEL v2 amendment, R11 PL-G4) — not a confirmed backend column.

Prefixed, opaque. The prefix is part of the contract; the suffix is never parsed.

refunded reads "Refunded" to the merchant and "Returned" to the payer on the same underlying value (R11 §3) — one enum member, two audience labels.

Labelled "Memo" on Payment Links merchant screens; the crypto-processing surfaces label this same field "Description" (R19 CP-G15) — one field, two display labels, never two schema fields.

A short, non-technical, server-minted id in CP-<n> form (e.g. CP-1042), unique per merchant. Set by the server at creation, never accepted as input. Distinct from invoice_number above, which is an optional, merchant-typed reference that may repeat or be null, and from id (the pl_-prefixed identifier), whose raw form is not meant to be shown to a payer or merchant as a reference number. Present on every payment link, not only crypto-processing ones.

A money value. amount is a minor-unit integer as a string; decimals states the scale so a client never re-derives it (USDC is 6). Floats never appear on a money path.

System-set at activation, never an input (RESOURCE-MODEL §2.1 invariants). Enum values are not published in RESOURCE-MODEL; left open rather than invented.

Computed grouping of payable_rails into the three UI kinds (RESOURCE-MODEL §2.1 v2 amendment; R11 PL-G5).

Editable while the link is draft, active or viewed (RESOURCE-MODEL §2.1). R11 PL-G3 flags a design screen that disables editing on viewed — not ratified as a rule change, so the contract keeps viewed editable.

System-set at activation, never an input (RESOURCE-MODEL §2.1 invariants; RESOURCE-MODEL §2.1 v2 amendment). Null on a draft that has not activated yet.

BL-39 (C4-D27) — the token identity frozen from settlement_snapshot at ACTIVATION, never a live chain read and never derived from a rate. null on a draft (no snapshot yet) or a non-Tempo settlement — Bridge bank/crypto destinations have no single payer-facing "token" this field describes. Carries no amount of its own.

BL-50 — the saved /v1/address_book entry create/update set as where this link's funds land. null until chosen. Read from the SAME reference activate freezes into settlement_snapshot (never cleared by activation), so it keeps reading the live destination after the link goes live too — distinct from settlement_asset above, which is the token identity frozen at that one moment.

C5-SHORT-LINK — the link's short public code (e.g. 7fq3k2c): 7 characters of lowercase Crockford base32 without the vowels a/e (so also no i, l, o, u). Minted by the server from a cryptographic random source when the link is created, for every link (draft or live, live or test mode), never accepted as input, never derived from ids, amounts, e-mails or names, and never changed afterwards. Unique across the project's links. It resolves to the payer session through GET /v1/payment_sessions/by_code/{short_code}, so treat it like url: share it with the payer only.

C5-SHORT-LINK — <payer host>/p/<short_code> (e.g. https://swaps.app/p/7fq3k2c), on the same per-project payer host as url and under the same rule: null exactly when url is null. Not yet a working payer link: it resolves only once the /p/:code page is live on that host, and only while the /v1 API is enabled; share url until then.

RESOURCE-MODEL §2.1 v2 amendment, R11 PL-G1.

crypto_relay (R19 X2) is a payer rail behind the crypto_relay_rail flag (off in production), never a stored restriction. A settlement_kind: crypto_only link offers crypto_tempo, plus crypto_relay where its gate admits it (the same on payable_rails and in the payer session): that flag and an admitted route (founder_accepted per founder §52.34, or proven; see K13-CRYPTO-RELAY-ROUTES.md). A1-2: open on THIS response field only — an unrecognized rail here is an opaque string, never a deserialization failure. The same vocabulary on PaymentLinkCreateRequest/PaymentLinkUpdateRequest stays closed: a merchant choosing an unknown rail is a real request error, not a fact to tolerate.

The rails the payer is offered now (one exception below), recomputed on every read; not a snapshot (RESOURCE-MODEL §2.1 v2 amendment). A later read can differ from an earlier one when a rail flag, a Relay route or the Relay cap changes. crypto_relay is listed exactly when the payer session of this link offers it (the same gate: the crypto_relay_rail flag for this merchant, the per-invoice cap, an admitted route for the link's Tempo settlement network, a USD link). If that gate cannot be read, crypto_relay is left out and the read still succeeds, where the payer session answers 503 temporarily_unavailable. Exception: an individual (direction: p2p) merchant whose Bridge fiat pay-in is not active yet is listed with its bank rails, although the payer session withholds them (C4-D23; tracked in #3977). Open-enum like allowed_rails above (queue item #3560) — the same forward-compatibility reasoning applies to a computed field.

A crypto_only settlement suppresses every fiat rail, so this reads [crypto] (RESOURCE-MODEL §2.1 v2 amendment; R19 §2.1).

Set only while status is processing and a payment arrived short of amount (§8.4). received reports the single MOST RECENT short payment recorded for this link's CURRENT attempt — one deposit's figure, not a running total of everything the link has received — and is null when that deposit's settled amount could not be confirmed (shown to the merchant as "needs review"). null while processing with nothing recorded, and again once the link leaves processing for a later full payment or a cancellation. A no-funds failure on an attempt moves the link to viewed and clears this field to null; it does NOT reopen the link to processing. The flag CAN reappear, but only when a LATER attempt creates a new transfer and puts the link back into processing — if that new attempt also under-pays, its own event is what reappears here, never an earlier attempt's superseded figure. The key itself may be absent when the underlying signal could not be read — that is not the same as null.

A1-2: required (still nullable) — every producer already emits null rather than omitting the field when there is no next page, so this only removes a third, unused wire state (absent) a strict client had to handle for nothing.

Present only with ?expand=summary (LIST-SUMMARY-1). Computed server-side over every link matching the request's status_group, q, client_id and settlement_kind (never cursor/limit), in one grouped query. by_status_group uses the status_group buckets exactly; they overlap (viewed/processing are both open and needs_attention), so they do not add up to total.

The amount of every matching paid or settled link, summed exactly per currency (minor units, same Money rules as PaymentLink.amount), sorted by currency. Empty when none. The link's requested amount, not a settlement ledger.