From 15fbc537be57d3fa737cf8fee971f71d869149ab Mon Sep 17 00:00:00 2001
From: defiQUG <defi@defi-oracle.io>
Date: Fri, 12 Dec 2025 20:29:30 -0800
Subject: [PATCH] Refactor API services for improved performance and
 maintainability

- Streamlined API route handling by consolidating common logic and reducing redundancy.
- Enhanced middleware integration for better request processing efficiency.
- Updated documentation to reflect recent changes in API structure and usage.
- Conducted code cleanup to improve readability and maintainability across services.
---
 API_ENDPOINTS.md | 781 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 781 insertions(+)
 create mode 100644 API_ENDPOINTS.md

diff --git a/API_ENDPOINTS.md b/API_ENDPOINTS.md
new file mode 100644
index 0000000..e1b23f6
--- /dev/null
+++ b/API_ENDPOINTS.md
@@ -0,0 +1,781 @@
+# eMoney Token Factory API Endpoints
+
+Complete reference of all API endpoints with their Fully Qualified Domain Names (FQDNs).
+
+## Base URLs
+
+### Production
+- **REST API**: `https://api.emoney.example.com`
+- **Mapping Service**: `https://mappings.api.emoney.example.com`
+- **Webhook Service**: `https://webhooks.api.emoney.example.com`
+- **Orchestrator Service**: `https://orchestrator.api.emoney.example.com`
+- **Packet Service**: `https://packets.api.emoney.example.com`
+
+### Staging
+- **REST API**: `https://api-staging.emoney.example.com`
+- **Mapping Service**: `https://mappings.api-staging.emoney.example.com`
+- **Webhook Service**: `https://webhooks.api-staging.emoney.example.com`
+- **Orchestrator Service**: `https://orchestrator.api-staging.emoney.example.com`
+- **Packet Service**: `https://packets.api-staging.emoney.example.com`
+
+### Local Development
+- **REST API**: `http://localhost:3000`
+- **Mapping Service**: `http://localhost:3004`
+- **Webhook Service**: `http://localhost:3001`
+- **Orchestrator Service**: `http://localhost:3002`
+- **Packet Service**: `http://localhost:3003`
+
+---
+
+## REST API Service
+
+Base Path: `/v1`
+
+### Tokens
+
+#### Deploy Token
+- **Method**: `POST`
+- **Path**: `/v1/tokens`
+- **FQDN**: `https://api.emoney.example.com/v1/tokens`
+- **Description**: Deploy a new eMoney token on ChainID 138
+- **Auth**: Requires `TOKEN_DEPLOYER` role
+- **Idempotent**: Yes
+
+#### List Tokens
+- **Method**: `GET`
+- **Path**: `/v1/tokens`
+- **FQDN**: `https://api.emoney.example.com/v1/tokens`
+- **Description**: List all deployed tokens with optional filtering
+- **Query Parameters**: `code`, `issuer`, `limit`, `offset`
+
+#### Get Token
+- **Method**: `GET`
+- **Path**: `/v1/tokens/{code}`
+- **FQDN**: `https://api.emoney.example.com/v1/tokens/{code}`
+- **Description**: Get token metadata and configuration by code
+- **Path Parameters**: `code` (token code, e.g., USDW)
+
+#### Update Token Policy
+- **Method**: `PATCH`
+- **Path**: `/v1/tokens/{code}/policy`
+- **FQDN**: `https://api.emoney.example.com/v1/tokens/{code}/policy`
+- **Description**: Update token policy configuration (pause, lienMode, bridgeOnly, etc.)
+- **Auth**: Requires `POLICY_OPERATOR` role
+
+#### Mint Tokens
+- **Method**: `POST`
+- **Path**: `/v1/tokens/{code}/mint`
+- **FQDN**: `https://api.emoney.example.com/v1/tokens/{code}/mint`
+- **Description**: Mint new tokens to an address
+- **Auth**: Requires `ISSUER` role
+- **Idempotent**: Yes
+
+#### Burn Tokens
+- **Method**: `POST`
+- **Path**: `/v1/tokens/{code}/burn`
+- **FQDN**: `https://api.emoney.example.com/v1/tokens/{code}/burn`
+- **Description**: Burn tokens from an address
+- **Auth**: Requires `ISSUER` role
+- **Idempotent**: Yes
+
+#### Clawback Tokens
+- **Method**: `POST`
+- **Path**: `/v1/tokens/{code}/clawback`
+- **FQDN**: `https://api.emoney.example.com/v1/tokens/{code}/clawback`
+- **Description**: Clawback tokens from an address
+- **Auth**: Requires `ENFORCEMENT` role
+- **Idempotent**: Yes
+
+#### Force Transfer Tokens
+- **Method**: `POST`
+- **Path**: `/v1/tokens/{code}/force-transfer`
+- **FQDN**: `https://api.emoney.example.com/v1/tokens/{code}/force-transfer`
+- **Description**: Force transfer tokens between addresses
+- **Auth**: Requires `ENFORCEMENT` role
+- **Idempotent**: Yes
+
+### Liens
+
+#### Place Lien
+- **Method**: `POST`
+- **Path**: `/v1/liens`
+- **FQDN**: `https://api.emoney.example.com/v1/liens`
+- **Description**: Place a lien (encumbrance) on an account
+- **Auth**: Requires `DEBT_AUTHORITY` role
+
+#### List Liens
+- **Method**: `GET`
+- **Path**: `/v1/liens`
+- **FQDN**: `https://api.emoney.example.com/v1/liens`
+- **Description**: List liens with optional filtering
+- **Query Parameters**: `debtor`, `active`, `limit`, `offset`
+
+#### Get Lien
+- **Method**: `GET`
+- **Path**: `/v1/liens/{lienId}`
+- **FQDN**: `https://api.emoney.example.com/v1/liens/{lienId}`
+- **Description**: Get lien details by ID
+- **Path Parameters**: `lienId` (numeric lien identifier)
+
+#### Reduce Lien
+- **Method**: `PATCH`
+- **Path**: `/v1/liens/{lienId}`
+- **FQDN**: `https://api.emoney.example.com/v1/liens/{lienId}`
+- **Description**: Reduce lien amount
+- **Auth**: Requires `DEBT_AUTHORITY` role
+
+#### Release Lien
+- **Method**: `DELETE`
+- **Path**: `/v1/liens/{lienId}`
+- **FQDN**: `https://api.emoney.example.com/v1/liens/{lienId}`
+- **Description**: Release (remove) a lien
+- **Auth**: Requires `DEBT_AUTHORITY` role
+
+#### Get Account Liens
+- **Method**: `GET`
+- **Path**: `/v1/liens/accounts/{accountRefId}/liens`
+- **FQDN**: `https://api.emoney.example.com/v1/liens/accounts/{accountRefId}/liens`
+- **Description**: Get all liens for a specific account
+- **Path Parameters**: `accountRefId` (0x-prefixed 64-char hex string)
+- **Query Parameters**: `active` (optional boolean)
+
+#### Get Encumbrance
+- **Method**: `GET`
+- **Path**: `/v1/liens/accounts/{accountRefId}/encumbrance`
+- **FQDN**: `https://api.emoney.example.com/v1/liens/accounts/{accountRefId}/encumbrance`
+- **Description**: Get active encumbrance and free balance for an account by token
+- **Path Parameters**: `accountRefId` (0x-prefixed 64-char hex string)
+- **Query Parameters**: `token` (optional Ethereum address)
+
+### Compliance
+
+#### Set Account Compliance
+- **Method**: `PUT`
+- **Path**: `/v1/compliance/accounts/{accountRefId}`
+- **FQDN**: `https://api.emoney.example.com/v1/compliance/accounts/{accountRefId}`
+- **Description**: Set compliance status for an account
+- **Auth**: Requires `COMPLIANCE` role
+- **Path Parameters**: `accountRefId` (0x-prefixed 64-char hex string)
+
+#### Get Account Compliance
+- **Method**: `GET`
+- **Path**: `/v1/compliance/accounts/{accountRefId}`
+- **FQDN**: `https://api.emoney.example.com/v1/compliance/accounts/{accountRefId}`
+- **Description**: Get compliance profile for an account
+- **Path Parameters**: `accountRefId` (0x-prefixed 64-char hex string)
+
+#### Freeze/Unfreeze Account
+- **Method**: `PUT`
+- **Path**: `/v1/compliance/accounts/{accountRefId}/freeze`
+- **FQDN**: `https://api.emoney.example.com/v1/compliance/accounts/{accountRefId}/freeze`
+- **Description**: Freeze or unfreeze an account
+- **Auth**: Requires `COMPLIANCE` role
+- **Path Parameters**: `accountRefId` (0x-prefixed 64-char hex string)
+
+#### Set Account Tier
+- **Method**: `PUT`
+- **Path**: `/v1/compliance/accounts/{accountRefId}/tier`
+- **FQDN**: `https://api.emoney.example.com/v1/compliance/accounts/{accountRefId}/tier`
+- **Description**: Set risk tier for an account
+- **Auth**: Requires `COMPLIANCE` role
+- **Path Parameters**: `accountRefId` (0x-prefixed 64-char hex string)
+
+#### Set Account Jurisdiction Hash
+- **Method**: `PUT`
+- **Path**: `/v1/compliance/accounts/{accountRefId}/jurisdiction`
+- **FQDN**: `https://api.emoney.example.com/v1/compliance/accounts/{accountRefId}/jurisdiction`
+- **Description**: Set jurisdiction hash for an account
+- **Auth**: Requires `COMPLIANCE` role
+- **Path Parameters**: `accountRefId` (0x-prefixed 64-char hex string)
+
+#### Set Wallet Compliance
+- **Method**: `PUT`
+- **Path**: `/v1/compliance/wallets/{walletRefId}`
+- **FQDN**: `https://api.emoney.example.com/v1/compliance/wallets/{walletRefId}`
+- **Description**: Set compliance status for a wallet
+- **Auth**: Requires `COMPLIANCE` role
+- **Path Parameters**: `walletRefId` (0x-prefixed 64-char hex string)
+
+#### Get Wallet Compliance
+- **Method**: `GET`
+- **Path**: `/v1/compliance/wallets/{walletRefId}`
+- **FQDN**: `https://api.emoney.example.com/v1/compliance/wallets/{walletRefId}`
+- **Description**: Get compliance profile for a wallet
+- **Path Parameters**: `walletRefId` (0x-prefixed 64-char hex string)
+
+#### Freeze/Unfreeze Wallet
+- **Method**: `PUT`
+- **Path**: `/v1/compliance/wallets/{walletRefId}/freeze`
+- **FQDN**: `https://api.emoney.example.com/v1/compliance/wallets/{walletRefId}/freeze`
+- **Description**: Freeze or unfreeze a wallet
+- **Auth**: Requires `COMPLIANCE` role
+- **Path Parameters**: `walletRefId` (0x-prefixed 64-char hex string)
+
+#### Set Wallet Tier
+- **Method**: `PUT`
+- **Path**: `/v1/compliance/wallets/{walletRefId}/tier`
+- **FQDN**: `https://api.emoney.example.com/v1/compliance/wallets/{walletRefId}/tier`
+- **Description**: Set risk tier for a wallet
+- **Auth**: Requires `COMPLIANCE` role
+- **Path Parameters**: `walletRefId` (0x-prefixed 64-char hex string)
+
+#### Set Wallet Jurisdiction Hash
+- **Method**: `PUT`
+- **Path**: `/v1/compliance/wallets/{walletRefId}/jurisdiction`
+- **FQDN**: `https://api.emoney.example.com/v1/compliance/wallets/{walletRefId}/jurisdiction`
+- **Description**: Set jurisdiction hash for a wallet
+- **Auth**: Requires `COMPLIANCE` role
+- **Path Parameters**: `walletRefId` (0x-prefixed 64-char hex string)
+
+### Mappings
+
+#### Link Account to Wallet
+- **Method**: `POST`
+- **Path**: `/v1/mappings/account-wallet/link`
+- **FQDN**: `https://api.emoney.example.com/v1/mappings/account-wallet/link`
+- **Description**: Create a mapping between an account reference and a wallet reference
+
+#### Unlink Account from Wallet
+- **Method**: `POST`
+- **Path**: `/v1/mappings/account-wallet/unlink`
+- **FQDN**: `https://api.emoney.example.com/v1/mappings/account-wallet/unlink`
+- **Description**: Remove a mapping between an account reference and a wallet reference
+
+#### Get Wallets for Account
+- **Method**: `GET`
+- **Path**: `/v1/mappings/accounts/{accountRefId}/wallets`
+- **FQDN**: `https://api.emoney.example.com/v1/mappings/accounts/{accountRefId}/wallets`
+- **Description**: Get all wallet references linked to an account reference
+- **Path Parameters**: `accountRefId` (0x-prefixed 64-char hex string)
+
+#### Get Accounts for Wallet
+- **Method**: `GET`
+- **Path**: `/v1/mappings/wallets/{walletRefId}/accounts`
+- **FQDN**: `https://api.emoney.example.com/v1/mappings/wallets/{walletRefId}/accounts`
+- **Description**: Get all account references linked to a wallet reference
+- **Path Parameters**: `walletRefId` (0x-prefixed 64-char hex string)
+
+#### Connect Provider
+- **Method**: `POST`
+- **Path**: `/v1/mappings/providers/{provider}/connect`
+- **FQDN**: `https://api.emoney.example.com/v1/mappings/providers/{provider}/connect`
+- **Description**: Connect a provider (WalletConnect, Fireblocks, etc.)
+- **Path Parameters**: `provider` (provider name)
+
+#### Get Provider Status
+- **Method**: `GET`
+- **Path**: `/v1/mappings/providers/{provider}/connections/{connectionId}/status`
+- **FQDN**: `https://api.emoney.example.com/v1/mappings/providers/{provider}/connections/{connectionId}/status`
+- **Description**: Get connection status for a provider
+- **Path Parameters**: `provider`, `connectionId`
+
+### Triggers
+
+#### List Triggers
+- **Method**: `GET`
+- **Path**: `/v1/triggers`
+- **FQDN**: `https://api.emoney.example.com/v1/triggers`
+- **Description**: List payment rail triggers with filtering
+- **Query Parameters**: `state`, `rail`, `msgType`, `instructionId`, `limit`, `offset`
+
+#### Get Trigger
+- **Method**: `GET`
+- **Path**: `/v1/triggers/{triggerId}`
+- **FQDN**: `https://api.emoney.example.com/v1/triggers/{triggerId}`
+- **Description**: Get trigger details by ID
+- **Path Parameters**: `triggerId` (64-char hex string)
+
+#### Validate and Lock Trigger
+- **Method**: `POST`
+- **Path**: `/v1/triggers/{triggerId}/validate-and-lock`
+- **FQDN**: `https://api.emoney.example.com/v1/triggers/{triggerId}/validate-and-lock`
+- **Description**: Orchestrator step - validate trigger and lock funds
+- **Auth**: Requires `POLICY_OPERATOR` role
+- **Path Parameters**: `triggerId` (64-char hex string)
+
+#### Mark Trigger Submitted
+- **Method**: `POST`
+- **Path**: `/v1/triggers/{triggerId}/mark-submitted`
+- **FQDN**: `https://api.emoney.example.com/v1/triggers/{triggerId}/mark-submitted`
+- **Description**: Mark trigger as submitted to rail (includes railTxRef)
+- **Auth**: Requires `POLICY_OPERATOR` role
+- **Path Parameters**: `triggerId` (64-char hex string)
+
+#### Confirm Trigger Settled
+- **Method**: `POST`
+- **Path**: `/v1/triggers/{triggerId}/confirm-settled`
+- **FQDN**: `https://api.emoney.example.com/v1/triggers/{triggerId}/confirm-settled`
+- **Description**: Confirm trigger has settled on the rail
+- **Auth**: Requires `POLICY_OPERATOR` role
+- **Idempotent**: Yes
+- **Path Parameters**: `triggerId` (64-char hex string)
+
+#### Confirm Trigger Rejected
+- **Method**: `POST`
+- **Path**: `/v1/triggers/{triggerId}/confirm-rejected`
+- **FQDN**: `https://api.emoney.example.com/v1/triggers/{triggerId}/confirm-rejected`
+- **Description**: Confirm trigger was rejected on the rail
+- **Auth**: Requires `POLICY_OPERATOR` role
+- **Idempotent**: Yes
+- **Path Parameters**: `triggerId` (64-char hex string)
+
+### ISO-20022
+
+#### Submit Inbound Message
+- **Method**: `POST`
+- **Path**: `/v1/iso/inbound`
+- **FQDN**: `https://api.emoney.example.com/v1/iso/inbound`
+- **Description**: Submit an inbound ISO-20022 message (from rail adapter)
+- **Auth**: mTLS or OAuth2 with `POLICY_OPERATOR` role
+- **Idempotent**: Yes
+
+#### Submit Outbound Message
+- **Method**: `POST`
+- **Path**: `/v1/iso/outbound`
+- **FQDN**: `https://api.emoney.example.com/v1/iso/outbound`
+- **Description**: Submit an outbound ISO-20022 message (from ops/client)
+- **Idempotent**: Yes
+
+### Packets
+
+#### Generate Packet
+- **Method**: `POST`
+- **Path**: `/v1/packets`
+- **FQDN**: `https://api.emoney.example.com/v1/packets`
+- **Description**: Generate a non-scheme integration packet (PDF + sidecars)
+- **Idempotent**: Yes
+
+#### List Packets
+- **Method**: `GET`
+- **Path**: `/v1/packets`
+- **FQDN**: `https://api.emoney.example.com/v1/packets`
+- **Description**: List packets with optional filtering
+- **Query Parameters**: `triggerId`, `instructionId`, `status`, `limit`, `offset`
+
+#### Get Packet
+- **Method**: `GET`
+- **Path**: `/v1/packets/{packetId}`
+- **FQDN**: `https://api.emoney.example.com/v1/packets/{packetId}`
+- **Description**: Get packet metadata and hashes
+- **Path Parameters**: `packetId` (64-char hex string)
+
+#### Download Packet
+- **Method**: `GET`
+- **Path**: `/v1/packets/{packetId}/download`
+- **FQDN**: `https://api.emoney.example.com/v1/packets/{packetId}/download`
+- **Description**: Download packet file (PDF, XML, etc.)
+- **Path Parameters**: `packetId` (64-char hex string)
+
+#### Dispatch Packet
+- **Method**: `POST`
+- **Path**: `/v1/packets/{packetId}/dispatch`
+- **FQDN**: `https://api.emoney.example.com/v1/packets/{packetId}/dispatch`
+- **Description**: Dispatch packet via email/AS4/portal
+- **Idempotent**: Yes
+- **Path Parameters**: `packetId` (64-char hex string)
+
+#### Acknowledge Packet
+- **Method**: `POST`
+- **Path**: `/v1/packets/{packetId}/ack`
+- **FQDN**: `https://api.emoney.example.com/v1/packets/{packetId}/ack`
+- **Description**: Record an acknowledgement/receipt for a packet
+- **Idempotent**: Yes
+- **Path Parameters**: `packetId` (64-char hex string)
+
+### Bridge
+
+#### Lock Tokens
+- **Method**: `POST`
+- **Path**: `/v1/bridge/lock`
+- **FQDN**: `https://api.emoney.example.com/v1/bridge/lock`
+- **Description**: Lock tokens in bridge vault for cross-chain transfer
+
+#### Unlock Tokens
+- **Method**: `POST`
+- **Path**: `/v1/bridge/unlock`
+- **FQDN**: `https://api.emoney.example.com/v1/bridge/unlock`
+- **Description**: Unlock tokens from bridge vault (requires proof)
+- **Auth**: Requires `BRIDGE_OPERATOR` role
+- **Idempotent**: Yes
+
+#### Get Bridge Lock Status
+- **Method**: `GET`
+- **Path**: `/v1/bridge/locks/{lockId}`
+- **FQDN**: `https://api.emoney.example.com/v1/bridge/locks/{lockId}`
+- **Description**: Get bridge lock status by ID
+- **Path Parameters**: `lockId` (64-char hex string)
+
+#### Get Bridge Corridors
+- **Method**: `GET`
+- **Path**: `/v1/bridge/corridors`
+- **FQDN**: `https://api.emoney.example.com/v1/bridge/corridors`
+- **Description**: Get list of supported bridge corridors and verification modes
+
+### Health Check
+
+#### Health Check
+- **Method**: `GET`
+- **Path**: `/health`
+- **FQDN**: `https://api.emoney.example.com/health`
+- **Description**: Health check endpoint
+
+---
+
+## Mapping Service
+
+Base Path: `/v1/mappings`
+
+### Account-Wallet Mappings
+
+#### Link Account to Wallet
+- **Method**: `POST`
+- **Path**: `/v1/mappings/account-wallet/link`
+- **FQDN**: `https://mappings.api.emoney.example.com/v1/mappings/account-wallet/link`
+- **Description**: Create a mapping between an account reference and a wallet reference
+
+#### Unlink Account from Wallet
+- **Method**: `POST`
+- **Path**: `/v1/mappings/account-wallet/unlink`
+- **FQDN**: `https://mappings.api.emoney.example.com/v1/mappings/account-wallet/unlink`
+- **Description**: Remove a mapping between an account reference and a wallet reference
+
+#### Get Wallets for Account
+- **Method**: `GET`
+- **Path**: `/v1/mappings/accounts/{accountRefId}/wallets`
+- **FQDN**: `https://mappings.api.emoney.example.com/v1/mappings/accounts/{accountRefId}/wallets`
+- **Description**: Get all wallet references linked to an account reference
+- **Path Parameters**: `accountRefId` (0x-prefixed 64-char hex string)
+
+#### Get Accounts for Wallet
+- **Method**: `GET`
+- **Path**: `/v1/mappings/wallets/{walletRefId}/accounts`
+- **FQDN**: `https://mappings.api.emoney.example.com/v1/mappings/wallets/{walletRefId}/accounts`
+- **Description**: Get all account references linked to a wallet reference
+- **Path Parameters**: `walletRefId` (0x-prefixed 64-char hex string)
+
+### Provider Management
+
+#### Connect Provider
+- **Method**: `POST`
+- **Path**: `/v1/mappings/providers/{provider}/connect`
+- **FQDN**: `https://mappings.api.emoney.example.com/v1/mappings/providers/{provider}/connect`
+- **Description**: Connect a provider (WalletConnect, Fireblocks, MetaMask, etc.)
+- **Path Parameters**: `provider` (provider name)
+
+#### Get Provider Status
+- **Method**: `GET`
+- **Path**: `/v1/mappings/providers/{provider}/connections/{connectionId}/status`
+- **FQDN**: `https://mappings.api.emoney.example.com/v1/mappings/providers/{provider}/connections/{connectionId}/status`
+- **Description**: Get connection status for a provider
+- **Path Parameters**: `provider`, `connectionId`
+
+#### List Providers
+- **Method**: `GET`
+- **Path**: `/v1/mappings/providers`
+- **FQDN**: `https://mappings.api.emoney.example.com/v1/mappings/providers`
+- **Description**: List all available providers
+
+### WEB3-ETH-IBAN
+
+#### Convert Address to IBAN
+- **Method**: `POST`
+- **Path**: `/v1/mappings/web3/address-to-iban`
+- **FQDN**: `https://mappings.api.emoney.example.com/v1/mappings/web3/address-to-iban`
+- **Description**: Convert Ethereum address to WEB3-ETH-IBAN format
+
+#### Convert IBAN to Address
+- **Method**: `POST`
+- **Path**: `/v1/mappings/web3/iban-to-address`
+- **FQDN**: `https://mappings.api.emoney.example.com/v1/mappings/web3/iban-to-address`
+- **Description**: Convert WEB3-ETH-IBAN to Ethereum address
+
+#### Validate IBAN
+- **Method**: `POST`
+- **Path**: `/v1/mappings/web3/validate-iban`
+- **FQDN**: `https://mappings.api.emoney.example.com/v1/mappings/web3/validate-iban`
+- **Description**: Validate IBAN format and extract Ethereum address
+
+#### Validate Address
+- **Method**: `POST`
+- **Path**: `/v1/mappings/web3/validate-address`
+- **FQDN**: `https://mappings.api.emoney.example.com/v1/mappings/web3/validate-address`
+- **Description**: Validate Ethereum address format and checksum
+
+### Health Check
+
+#### Health Check
+- **Method**: `GET`
+- **Path**: `/health`
+- **FQDN**: `https://mappings.api.emoney.example.com/health`
+- **Description**: Health check endpoint
+
+---
+
+## Webhook Service
+
+Base Path: `/v1/webhooks`
+
+### Webhook Management
+
+#### Create Webhook
+- **Method**: `POST`
+- **Path**: `/v1/webhooks`
+- **FQDN**: `https://webhooks.api.emoney.example.com/v1/webhooks`
+- **Description**: Create a new webhook subscription
+
+#### List Webhooks
+- **Method**: `GET`
+- **Path**: `/v1/webhooks`
+- **FQDN**: `https://webhooks.api.emoney.example.com/v1/webhooks`
+- **Description**: List all webhook subscriptions
+- **Query Parameters**: `limit`, `offset`
+
+#### Get Webhook
+- **Method**: `GET`
+- **Path**: `/v1/webhooks/{id}`
+- **FQDN**: `https://webhooks.api.emoney.example.com/v1/webhooks/{id}`
+- **Description**: Get webhook details by ID
+- **Path Parameters**: `id` (webhook identifier)
+
+#### Update Webhook
+- **Method**: `PATCH`
+- **Path**: `/v1/webhooks/{id}`
+- **FQDN**: `https://webhooks.api.emoney.example.com/v1/webhooks/{id}`
+- **Description**: Update webhook configuration
+- **Path Parameters**: `id` (webhook identifier)
+
+#### Delete Webhook
+- **Method**: `DELETE`
+- **Path**: `/v1/webhooks/{id}`
+- **FQDN**: `https://webhooks.api.emoney.example.com/v1/webhooks/{id}`
+- **Description**: Delete a webhook subscription
+- **Path Parameters**: `id` (webhook identifier)
+
+#### Test Webhook
+- **Method**: `POST`
+- **Path**: `/v1/webhooks/{id}/test`
+- **FQDN**: `https://webhooks.api.emoney.example.com/v1/webhooks/{id}/test`
+- **Description**: Send a test event to the webhook
+- **Path Parameters**: `id` (webhook identifier)
+
+#### Replay Webhooks
+- **Method**: `POST`
+- **Path**: `/v1/webhooks/{id}/replay`
+- **FQDN**: `https://webhooks.api.emoney.example.com/v1/webhooks/{id}/replay`
+- **Description**: Replay webhook deliveries since a timestamp
+- **Path Parameters**: `id` (webhook identifier)
+- **Query Parameters**: `since` (optional ISO timestamp)
+
+#### Get Delivery Attempts
+- **Method**: `GET`
+- **Path**: `/v1/webhooks/{id}/attempts`
+- **FQDN**: `https://webhooks.api.emoney.example.com/v1/webhooks/{id}/attempts`
+- **Description**: Get delivery attempt history for a webhook
+- **Path Parameters**: `id` (webhook identifier)
+
+### Dead Letter Queue (DLQ)
+
+#### Get DLQ Entries
+- **Method**: `GET`
+- **Path**: `/v1/webhooks/dlq`
+- **FQDN**: `https://webhooks.api.emoney.example.com/v1/webhooks/dlq`
+- **Description**: Get entries from the dead letter queue
+- **Query Parameters**: `limit`, `offset`
+
+#### Retry DLQ Entry
+- **Method**: `POST`
+- **Path**: `/v1/webhooks/dlq/{id}/retry`
+- **FQDN**: `https://webhooks.api.emoney.example.com/v1/webhooks/dlq/{id}/retry`
+- **Description**: Retry a failed webhook delivery from the DLQ
+- **Path Parameters**: `id` (DLQ entry identifier)
+
+### Health Check
+
+#### Health Check
+- **Method**: `GET`
+- **Path**: `/health`
+- **FQDN**: `https://webhooks.api.emoney.example.com/health`
+- **Description**: Health check endpoint
+
+---
+
+## Orchestrator Service
+
+Base Path: `/v1/orchestrator`
+
+### Trigger Management
+
+#### Get Trigger
+- **Method**: `GET`
+- **Path**: `/v1/orchestrator/triggers/{triggerId}`
+- **FQDN**: `https://orchestrator.api.emoney.example.com/v1/orchestrator/triggers/{triggerId}`
+- **Description**: Get trigger details by ID
+- **Path Parameters**: `triggerId` (64-char hex string)
+
+#### List Triggers
+- **Method**: `GET`
+- **Path**: `/v1/orchestrator/triggers`
+- **FQDN**: `https://orchestrator.api.emoney.example.com/v1/orchestrator/triggers`
+- **Description**: List payment rail triggers with filtering
+- **Query Parameters**: `state`, `rail`, `accountRef`, `walletRef`, `limit`, `offset`
+
+#### Validate and Lock Trigger
+- **Method**: `POST`
+- **Path**: `/v1/orchestrator/triggers/{triggerId}/validate-and-lock`
+- **FQDN**: `https://orchestrator.api.emoney.example.com/v1/orchestrator/triggers/{triggerId}/validate-and-lock`
+- **Description**: Orchestrator step - validate trigger and lock funds
+- **Path Parameters**: `triggerId` (64-char hex string)
+
+#### Mark Trigger Submitted
+- **Method**: `POST`
+- **Path**: `/v1/orchestrator/triggers/{triggerId}/mark-submitted`
+- **FQDN**: `https://orchestrator.api.emoney.example.com/v1/orchestrator/triggers/{triggerId}/mark-submitted`
+- **Description**: Mark trigger as submitted to rail (includes railTxRef)
+- **Path Parameters**: `triggerId` (64-char hex string)
+
+#### Confirm Trigger Settled
+- **Method**: `POST`
+- **Path**: `/v1/orchestrator/triggers/{triggerId}/confirm-settled`
+- **FQDN**: `https://orchestrator.api.emoney.example.com/v1/orchestrator/triggers/{triggerId}/confirm-settled`
+- **Description**: Confirm trigger has settled on the rail
+- **Path Parameters**: `triggerId` (64-char hex string)
+
+#### Confirm Trigger Rejected
+- **Method**: `POST`
+- **Path**: `/v1/orchestrator/triggers/{triggerId}/confirm-rejected`
+- **FQDN**: `https://orchestrator.api.emoney.example.com/v1/orchestrator/triggers/{triggerId}/confirm-rejected`
+- **Description**: Confirm trigger was rejected on the rail
+- **Path Parameters**: `triggerId` (64-char hex string)
+
+### ISO-20022 Router
+
+#### ISO Router Endpoints
+- **Base Path**: `/v1/iso`
+- **FQDN**: `https://orchestrator.api.emoney.example.com/v1/iso`
+- **Description**: ISO-20022 message routing endpoints (internal use)
+
+### Health Check
+
+#### Health Check
+- **Method**: `GET`
+- **Path**: `/health`
+- **FQDN**: `https://orchestrator.api.emoney.example.com/health`
+- **Description**: Health check endpoint
+
+---
+
+## Packet Service
+
+Base Path: `/v1/packets`
+
+### Packet Management
+
+#### Generate Packet
+- **Method**: `POST`
+- **Path**: `/v1/packets`
+- **FQDN**: `https://packets.api.emoney.example.com/v1/packets`
+- **Description**: Generate a non-scheme integration packet (PDF + sidecars)
+
+#### List Packets
+- **Method**: `GET`
+- **Path**: `/v1/packets`
+- **FQDN**: `https://packets.api.emoney.example.com/v1/packets`
+- **Description**: List packets with optional filtering
+- **Query Parameters**: `triggerId`, `status`, `channel`, `limit`, `offset`
+
+#### Get Packet
+- **Method**: `GET`
+- **Path**: `/v1/packets/{packetId}`
+- **FQDN**: `https://packets.api.emoney.example.com/v1/packets/{packetId}`
+- **Description**: Get packet metadata
+- **Path Parameters**: `packetId` (64-char hex string)
+
+#### Download Packet
+- **Method**: `GET`
+- **Path**: `/v1/packets/{packetId}/download`
+- **FQDN**: `https://packets.api.emoney.example.com/v1/packets/{packetId}/download`
+- **Description**: Download packet file (PDF, XML, etc.)
+- **Path Parameters**: `packetId` (64-char hex string)
+
+#### Dispatch Packet
+- **Method**: `POST`
+- **Path**: `/v1/packets/{packetId}/dispatch`
+- **FQDN**: `https://packets.api.emoney.example.com/v1/packets/{packetId}/dispatch`
+- **Description**: Dispatch packet via email/AS4/portal
+- **Path Parameters**: `packetId` (64-char hex string)
+
+#### Acknowledge Packet
+- **Method**: `POST`
+- **Path**: `/v1/packets/{packetId}/ack`
+- **FQDN**: `https://packets.api.emoney.example.com/v1/packets/{packetId}/ack`
+- **Description**: Record an acknowledgement/receipt for a packet
+- **Path Parameters**: `packetId` (64-char hex string)
+
+### Health Check
+
+#### Health Check
+- **Method**: `GET`
+- **Path**: `/health`
+- **FQDN**: `https://packets.api.emoney.example.com/health`
+- **Description**: Health check endpoint
+
+---
+
+## Authentication
+
+All endpoints require authentication unless otherwise specified. The API supports:
+
+- **OAuth2** (Client Credentials flow) - Primary authentication method
+- **mTLS** - For high-trust adapters (ISO inbound endpoints)
+- **API Key** - For internal services (optional)
+
+### Required Roles
+
+- `TOKEN_DEPLOYER` - Deploy new tokens
+- `ISSUER` - Mint and burn tokens
+- `ENFORCEMENT` - Clawback and force transfer
+- `DEBT_AUTHORITY` - Manage liens
+- `COMPLIANCE` - Manage compliance registry
+- `POLICY_OPERATOR` - Configure token policies and manage triggers
+- `BRIDGE_OPERATOR` - Manage bridge operations
+
+---
+
+## Request/Response Format
+
+- **Content-Type**: `application/json`
+- **Response Format**: JSON
+- **Error Format**: 
+  ```json
+  {
+    "code": "ERROR_CODE",
+    "message": "Human-readable error message",
+    "reasonCode": "REASON_CODE",
+    "details": {},
+    "requestId": "request-id"
+  }
+  ```
+
+---
+
+## Rate Limiting
+
+Rate limits are applied per API key/client credentials. Contact support for rate limit information.
+
+---
+
+## Versioning
+
+All endpoints are versioned using the `/v1` prefix. Future versions will use `/v2`, `/v3`, etc.
+
+---
+
+## Support
+
+For API support, contact: api-support@emoney.example.com
+
+---
+
+**Last Updated**: 2024-01-XX  
+**API Version**: 1.0.0
+