Developers

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 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.

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 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.

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.

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.

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.

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 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).

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.

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.

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.

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.

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.

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.

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.