tracefinance · marioalvial · Apr 29, 2026 · Apr 29, 2026 · Apr 29, 2026 · Apr 29, 2026
diff --git a/.claude/rules/openapi.md b/.claude/rules/openapi.md
@@ -37,7 +37,7 @@ machine-checkable subset.
   `components.responses` and are referenced via `$ref`. Example:
   `WebhookAck` for the standard 200 response on every webhook event.
 - Standard schemas that appear in every spec: `Currency`, `Rail`,
-  `ErrorResponse`, `PaginationMeta`. Always named components, never
+  `ErrorResponse`, `PageMetadata`. Always named components, never
   inline.
 
 ## Discriminated unions
@@ -80,15 +80,15 @@ machine-checkable subset.
 - Server URL is per-service: `https://faas.{env}.tracefinance.io/account`,
   `/payment`, `/webhook`.
 - Strip `/dashboard` and `/admin` paths — only `/api` channel is
-  documented (per `CONTRIBUTING.md`). Public discovery endpoints (e.g.,
+  documented. Public discovery endpoints (e.g.,
   `/references/...`) sit outside `/api` and require no auth — set
   `security: []` to override the global `bearerAuth`.
 
 ## Pagination
 
 - List endpoints reference the shared parameters: `PaginationLimit`,
   `PaginationCursor`, `PaginationDirection`, `PaginationSortOrder`.
-- Response wraps as `{ data: [...], meta: PaginationMeta }`. The schema
+- Response wraps as `{ data: [...], meta: PageMetadata }`. The schema
   name is `XxxList`.
 
 ## Description style

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## What this repo is
 
-Trace Finance's public developer documentation for the FX platform, built on [Mintlify](https://mintlify.com). Partners ("customers") integrate with two services — **FX Account** (multi-currency account management) and **FX Payment** (deposits, withdrawals, swaps, beneficiaries) — documented here as one unified API surface.
+Trace Finance's public developer documentation for the FX platform, built on [Mintlify](https://mintlify.com). Customers integrate with **FX Account** (multi-currency account management), **FX Payment** (deposits, withdrawals, swaps, beneficiaries), and **FX Webhook** (subscriptions and event delivery) — documented here as one unified API surface.
 
 Content is public. Internal class names, backoffice endpoints, dashboard endpoints, and ADRs never appear here.
 
@@ -35,23 +35,23 @@ Pages are MDX with YAML frontmatter (`title` + `description` required). Mintlify
 | `journeys/` | End-to-end flows: open accounts, deposit, withdraw, swap |
 | `webhooks/` | Webhook setup and event catalog |
 | `snippets/` | Reusable MDX fragments imported into other pages |
-| `apis/` | OpenAPI specs (scaffold) — `fx-account/openapi.yml` and `fx-payment/openapi.yml` |
+| `apis/` | OpenAPI specs — `fx-account/openapi.yml`, `fx-payment/openapi.yml`, `fx-webhook/openapi.yml` |
 
-### API Reference (OpenAPI) — deferred
+### API Reference (OpenAPI)
 
-OpenAPI specs live in `apis/` but are not yet wired into `docs.json` navigation. When schemas are ready, add the `openapi` key and an API Reference tab to `docs.json`. Endpoint pages auto-generate from `apis/{service}/openapi.yml`. Only `/api` channel endpoints are documented. `/dashboard` and `/admin` are internal.
+Endpoint pages auto-generate from `apis/{service}/openapi.yml`. Only `/api` channel endpoints are documented. `/dashboard` and `/admin` are internal.
 
 ## Terminology
 
 - **Customer** = the company integrating with Trace FX.
 - **Account owner** = the person whose account is managed (maps to `account.owner`).
-- Never use "partner" or "client."
+- Never use "partner", "client", or "user" in public content.
 
-## Key rules (full rulebook in CONTRIBUTING.md)
+## Key rules
 
 - Internal links: root-relative, no extension (`/guides/authentication`).
 - No internal class names in public content (`AmountV2` → "amount object").
-- Money: minor units as integers (`{ "value": 500000, "asset": "BRL" }`).
+- Money: decimal strings in the asset's canonical scale (`{ "value": "5000.00", "asset": "BRL", "decimals": 2 }`). Never integer minor units in the wire format. Never JS `Number` for parsing — use `BigDecimal`/`Decimal`.
 - Code blocks always declare language.
 - Sentence case headings; no marketing adjectives; no filler.
 - OpenAPI specs live here — when service teams change `/api` endpoints, they PR the spec update here too.
@@ -107,11 +107,11 @@ Page types are inferred from file paths:
 `snippets/` contains shared MDX blocks. Import them in any page:
 
 ```mdx
-import AuthHeader from '/snippets/auth-header.mdx';
-<AuthHeader />
+import MoneyFormat from '/snippets/money-format.mdx';
+<MoneyFormat />
 ```
 
-Available: `auth-header`, `idempotency-note`, `pagination-response`, `error-response`, `money-format`, `version-header`.
+Currently `money-format` is the only snippet. Add new ones only when the same prose appears verbatim on three or more pages.
 
 ### CI (GitHub Actions)
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
diff --git a/api-reference/fx-webhook/events/account/asset-activated.mdx b/api-reference/fx-webhook/events/account/asset-activated.mdx
@@ -1,5 +1,5 @@
 ---
-title: "account.asset.activated"
+title: "ACCOUNT_ASSET_ACTIVATED"
 description: "Fires when an account asset finishes onboarding and funding instructions are available."
-openapi: "apis/fx-webhook/openapi.yml webhook account.asset.activated"
+openapi: "apis/fx-webhook/openapi.yml webhook ACCOUNT_ASSET_ACTIVATED"
 ---
diff --git a/api-reference/fx-webhook/events/beneficiary/beneficiary-instruction-created.mdx b/api-reference/fx-webhook/events/beneficiary/beneficiary-instruction-created.mdx
diff --git a/...iary/beneficiary-instruction-approved.mdx → ...eficiary-payment-instruction-approved.mdx b/...iary/beneficiary-instruction-approved.mdx → ...eficiary-payment-instruction-approved.mdx
@@ -1,5 +1,5 @@
 ---
-title: "beneficiary.instruction.approved"
+title: "BENEFICIARY_PAYMENT_INSTRUCTION_APPROVED"
 description: "Fires when a payment instruction on a beneficiary is approved; check instructions[].status to find the one that transitioned."
-openapi: "apis/fx-webhook/openapi.yml webhook beneficiary.instruction.approved"
+openapi: "apis/fx-webhook/openapi.yml webhook BENEFICIARY_PAYMENT_INSTRUCTION_APPROVED"
 ---
diff --git a/...rence/fx-webhook/events/beneficiary/beneficiary-payment-instruction-created.mdx b/...rence/fx-webhook/events/beneficiary/beneficiary-payment-instruction-created.mdx
@@ -0,0 +1,5 @@
+---
+title: "BENEFICIARY_PAYMENT_INSTRUCTION_CREATED"
+description: "Fires when a payment instruction is added to a beneficiary; the new instruction starts in PENDING_REVIEW."
+openapi: "apis/fx-webhook/openapi.yml webhook BENEFICIARY_PAYMENT_INSTRUCTION_CREATED"
+---
diff --git a/...iary/beneficiary-instruction-rejected.mdx → ...eficiary-payment-instruction-rejected.mdx b/...iary/beneficiary-instruction-rejected.mdx → ...eficiary-payment-instruction-rejected.mdx
@@ -1,5 +1,5 @@
 ---
-title: "beneficiary.instruction.rejected"
+title: "BENEFICIARY_PAYMENT_INSTRUCTION_REJECTED"
 description: "Fires when a payment instruction on a beneficiary is rejected; check instructions[].status to find the one that transitioned."
-openapi: "apis/fx-webhook/openapi.yml webhook beneficiary.instruction.rejected"
+openapi: "apis/fx-webhook/openapi.yml webhook BENEFICIARY_PAYMENT_INSTRUCTION_REJECTED"
 ---
diff --git a/api-reference/fx-webhook/events/operation/operation-requested.mdx b/api-reference/fx-webhook/events/operation/operation-requested.mdx
@@ -1,5 +1,5 @@
 ---
-title: "operation.requested"
+title: "OPERATION_REQUESTED"
 description: "Fires when a payment operation (deposit, withdrawal, swap) is created."
-openapi: "apis/fx-webhook/openapi.yml webhook operation.requested"
+openapi: "apis/fx-webhook/openapi.yml webhook OPERATION_REQUESTED"
 ---