Request price streams for trades that deliver digital assets directly to third-party beneficiary wallets instead of your Zodia Markets account. The price channel works identically to standard price streams, but requires two additional fields to specify the destination. *** ## Prerequisites Before requesting third-party settlement prices: ### Beneficiary Setup Beneficiaries must be configured: * Complete beneficiary onboarding and verification either via Customer Portal or your Relationship Manager. Each destination wallet address must be: * Added to the beneficiary's wallet list * Verified through Zodia Markets compliance process * Enabled and active for trading ### 3. Network Configuration Ensure the settlement network type is available for your account: * **ZM_TRANSFER** is the default for crypto settlement * Contact your Relationship Manager for additional network options > ⚠️ **Important** > > Orders will be rejected if: > > * Beneficiary ID is not found or not approved > * The Beneficiary does not have a valid Wallet Address for the chosen asset or it is not whitelisted or enabled > * The payout currency is not specified *** ## How It Differs from Standard Price Subscriptions ### Third Party Settlement Price Subscription ```json { "messageType": "subscribe", "instrument": "USDC.USD", "quantity": "500000", "currency": "USD", "accountGrpUuid": "a6898bdd-856b-4259-b6e2-6ef66f2282e1", "tenor": "T", "beneficiaryDetails": { "beneficiaryId": "5fff78ca-d87f-424f-90bf-96b1906a284b", "payoutCurrency": "USDC" }, "tag": "echo" } ``` **Key differences:** * ✅ Add `beneficiaryDetails` block * ✅ Add `beneficiaryId` field * ✅ Add `payoutCurrency` field * ✅ Everything else remains identical *** ## Additional Request Fields Add these fields to your standard price subscription request: | Field | Required | Type | Description | | :--------------- | :---------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `beneficiaryId` | Conditional | String | UUID of pre-configured beneficiary. [Get Beneficiaries](#https://docs.zodiamarkets.com/reference/get-beneficiary-list) on how to retrieve list of beneficiary UUID | | `payoutCurrency` | Conditional | String | Payout currency. Must be a currency that is contained within the instrument being subscribed to. | | `networkId` | No | String | Not usually required unless using a specific network. Contact your Relationship Manager for more info. | All other fields remain the same as [standard price subscriptions →](#https://docs.zodiamarkets.com/reference/subscribe-to-price-channel). *** ## Responses Subscription success response messages remain identical to standard price streams except for the addition of the `networkId`, which will provide the network the payout will be executed on. For crypto payouts, this will be **ZM_TRANSFER**. Price updates do **not** include beneficiary or network information. Use the `quoteId` to execute orders which will reference your subscription's beneficiary configuration. ```json Subscription Ack { "chanId": "", "timestamp": 1773243625433, "messageType": "subscribe", "success": true, "message": "Subscribed", "subscriptionId": "838164a8-e795-4cfc-852b-c8dc3da8ca58", "tag": "e4795b61-55e2-4474-a1eb-53b85227b778", "instrument": "USDC.USD", "quantity": "500000.00000000", "code": "", "tenor": "T", "settleDate": "", "networkId": "ZM_TRANSFER" } ``` *** ## Executing Orders with Third Party Settlement When you execute an order on a third-party settlement price stream, the asset will be delivered to the specified beneficiary's wallet. The message format remains the same as a normal trade request with the exception of providing an additional field `paymentReason`. ```json Order Request { "accountGrpUuid": "2073252c-81ed-41be-bf4d-d51b8f2246b8", "clientRequestId": "5abc86ae-53cd-4f31-bbf4-8e598c7f6805", "messageType": "order", "quoteId": "Nu5EdH+siTnz9ch...", "side": "BUY", "paymentReason": "VASA" } ``` *** ### Payment Reason Codes The `paymentReason` field must be set to one of the following ISO codes: #### Crypto & Assets | ISO Code | Display Name | Definition / Use Case | | -------- | ------------------------ | ------------------------------------------------- | | `VASA` | Virtual Asset Settlement | Third-party settlement of crypto/digital assets. | | `INVS` | Investment | Retail purchase of crypto/stocks via an exchange. | | `NETT` | Netting | Settlement of a net position between two parties. | | `TREA` | Treasury Payment | Internal liquidity or wholesale asset movements. | #### Property | ISO Code | Display Name | Definition / Use Case | | -------- | ----------------- | ------------------------------------------- | | `PLPR` | Property Purchase | Mandatory for final house/land completion. | | `PLRE` | Property Deposit | Deposit or reservation fee for property. | | `RENT` | Rent | Payment to a landlord or letting agent. | | `UTIL` | Utilities | Gas, water, electricity, or telecoms bills. | #### Commercial | ISO Code | Display Name | Definition / Use Case | | -------- | ---------------- | --------------------------------------------------- | | `GDSV` | Goods & Services | General retail or service purchase ("Catch-all"). | | `SUPP` | Supplier Payment | Payment to a regular business supplier. | | `SERV` | Service Charges | Professional fees or service-related costs. | | `SUBS` | Subscription | Recurring software, gym, or media fees. | | `ADVA` | Advance Payment | Payment before delivery (**Flagged as High Risk**). | #### Personal | ISO Code | Display Name | Definition / Use Case | | -------- | ----------------------- | -------------------------------------------------------------- | | `GIFT` | Gift | Personal gift to family or friends. | | `CASH` | Transfer to own account | Moving money between accounts owned by the same person/entity. | | `CHAR` | Charity | Donation to a registered charity. | | `OTHR` | Other / Personal | Standard P2P transfer (use sparingly). | #### Financial | ISO Code | Display Name | Definition / Use Case | | -------- | ---------------- | ---------------------------------------- | | `SAVE` | Savings | Transfer to a savings account or ISA. | | `LOAN` | Loan Repayment | Paying back a bank loan or debt. | | `TAXS` | Tax Payment | Payment to HMRC (VAT, Income Tax). | | `FEXP` | Foreign Exchange | Standard fiat-to-fiat currency exchange. | #### Employment | ISO Code | Display Name | Definition / Use Case | | -------- | -------------- | --------------------------------------- | | `SALA` | Salary / Wages | Regular employment income. | | `PENS` | Pension | Payment into or from a retirement fund. | > 📘 **Automatic Beneficiary Association** > > The `quoteId` is tied to your subscription, which includes the `beneficiaryId` and `payoutCurrency`. You don't need to specify beneficiary details in the order request.
*** ## Error Handling ### Beneficiary Not Found **Causes:** * Invalid beneficiary UUID * Beneficiary not configured for your account * Beneficiary not yet approved ### Beneficiary Wallet Not Found **Causes:** * No wallet address configured for this beneficiary * Wallet not whitelisted for the requested asset * No wallet address configured for this asset * Wallet disabled or pending approval ### Invalid Network ID **Cause:** Network ID not available for your account **Solution:** Contact your Relationship Manager to enable additional network types *** ## Comparison: Standard vs Third Party Settlement

Aspect	Standard Settlement	Third Party Settlement
Asset destination	Your Zodia Markets account and delivery to your named wallet	Beneficiary's wallet
Subscription fields	Standard fields only	* `beneficiaryId` + `payoutCurrency`
Order fields	Standard fields only	* `paymentReason`
Setup required	None	Beneficiary and wallet configuration
Price updates	Identical	`networkId`
Order execution	Identical format	Identical format
Settlement time	Standard T+0 or T+1	Standard T+0 or T+1