From 2da16058c18505cd8595a66491a4936ea5432e1f Mon Sep 17 00:00:00 2001 From: Jeremy Date: Fri, 10 Jul 2026 23:39:54 +0000 Subject: [PATCH 1/7] feat: add onChainTransaction to transaction source/destination Adds an optional onChainTransaction (transactionHash + network) to BaseTransactionSource and BaseTransactionDestination for legs whose counterparty is an external crypto wallet. network references a new reusable CryptoNetwork enum (environment-qualified: mainnet vs devnet/testnet/regtest). Reconciliation instructions' transactionHash is now scoped purely to the inter-VASP settlement leg, with the external-wallet endpoint hash living only on the source/destination. Additive, no version bump. --- mintlify/openapi.yaml | 39 ++++++++++++++++++- openapi.yaml | 39 ++++++++++++++++++- .../common/ReconciliationInstructions.yaml | 10 ++++- .../schemas/crypto/CryptoNetwork.yaml | 19 +++++++++ .../BaseTransactionDestination.yaml | 7 ++++ .../transactions/BaseTransactionSource.yaml | 7 ++++ .../transactions/OnChainTransaction.yaml | 12 ++++++ 7 files changed, 129 insertions(+), 4 deletions(-) create mode 100644 openapi/components/schemas/crypto/CryptoNetwork.yaml create mode 100644 openapi/components/schemas/transactions/OnChainTransaction.yaml diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 06b0316a3..ea8af3f40 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -16939,6 +16939,36 @@ components: - UMA_ADDRESS description: Type of transaction destination example: ACCOUNT + CryptoNetwork: + type: string + enum: + - ETHEREUM_MAINNET + - ETHEREUM_TESTNET + - SOLANA_MAINNET + - SOLANA_DEVNET + - BASE_MAINNET + - BASE_TESTNET + - POLYGON_MAINNET + - POLYGON_TESTNET + - TRON_MAINNET + - TRON_TESTNET + - SPARK_MAINNET + - SPARK_REGTEST + description: A blockchain network, including the environment (mainnet vs devnet/testnet/regtest) so an on-chain transaction can be looked up on the correct explorer. Sandbox transactions report the devnet/testnet/regtest variant (e.g. SOLANA_DEVNET). + example: SOLANA_MAINNET + OnChainTransaction: + type: object + required: + - transactionHash + - network + properties: + transactionHash: + type: string + description: On-chain transaction hash of the crypto transfer for this leg of the transaction. + example: 4Nd1m6Qkq7RfKuE5vQ9qP9Tn6H94Ueqb4xXHzsAbd8WgpD9k6oRnJm2pQ7sT1uV3wX5yZ6aB8cD9eF0gH1i + network: + $ref: '#/components/schemas/CryptoNetwork' + description: Blockchain network (incl. environment) the transaction settled on. BaseTransactionDestination: type: object required: @@ -16950,6 +16980,9 @@ components: type: string description: Currency code for the destination example: EUR + onChainTransaction: + $ref: '#/components/schemas/OnChainTransaction' + description: On-chain transaction that delivered funds to this destination, when the destination is an external crypto wallet. Populated once the crypto transfer has settled; absent for fiat/UMA destinations and for the internal settlement leg of a UMA payment (see `reconciliationInstructions`). AccountTransactionDestination: title: Account Destination allOf: @@ -17084,6 +17117,9 @@ components: type: string description: Currency code for the source example: USD + onChainTransaction: + $ref: '#/components/schemas/OnChainTransaction' + description: On-chain transaction that delivered funds from this source, when the source is an external crypto wallet. Populated once the crypto transfer has settled; absent for fiat/UMA sources and for the internal settlement leg of a UMA payment (see `reconciliationInstructions`). AccountTransactionSource: title: Account Source allOf: @@ -17188,6 +17224,7 @@ components: ReconciliationInstructions: type: object minProperties: 1 + description: Instructions for reconciling a payment with this transaction. For the on-chain transaction to or from an external crypto wallet that is the transaction's own source or destination, use the `onChainTransaction` on the relevant source or destination instead. properties: reference: type: string @@ -17195,7 +17232,7 @@ components: example: UMA-Q12345-REF transactionHash: type: string - description: Transaction hash for the crypto transfer that delivered funds to the transaction destination, when available. + description: Transaction hash of the internal settlement transfer used to deliver a UMA payment — the inter-VASP settlement leg (e.g. USDC on Solana to the receiving partner), when available. This is not a transfer to a customer's own wallet; for that, see the `onChainTransaction` on the transaction's source or destination. example: '0x9f2c6b6f4b6c8f2a8d9e0b1c2d3e4f5061728394a5b6c7d8e9f00112233445566' IncomingRateDetails: description: 'Details about the rate and fees for an incoming transaction. Note: `gridApiFixedFee` is denominated in the receiving currency, so its equivalent value in the sending currency fluctuates with the FX rate. As a result, the total fee on a subsequent quote for the same transfer may differ even if the underlying fee structure is unchanged.' diff --git a/openapi.yaml b/openapi.yaml index 06b0316a3..ea8af3f40 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -16939,6 +16939,36 @@ components: - UMA_ADDRESS description: Type of transaction destination example: ACCOUNT + CryptoNetwork: + type: string + enum: + - ETHEREUM_MAINNET + - ETHEREUM_TESTNET + - SOLANA_MAINNET + - SOLANA_DEVNET + - BASE_MAINNET + - BASE_TESTNET + - POLYGON_MAINNET + - POLYGON_TESTNET + - TRON_MAINNET + - TRON_TESTNET + - SPARK_MAINNET + - SPARK_REGTEST + description: A blockchain network, including the environment (mainnet vs devnet/testnet/regtest) so an on-chain transaction can be looked up on the correct explorer. Sandbox transactions report the devnet/testnet/regtest variant (e.g. SOLANA_DEVNET). + example: SOLANA_MAINNET + OnChainTransaction: + type: object + required: + - transactionHash + - network + properties: + transactionHash: + type: string + description: On-chain transaction hash of the crypto transfer for this leg of the transaction. + example: 4Nd1m6Qkq7RfKuE5vQ9qP9Tn6H94Ueqb4xXHzsAbd8WgpD9k6oRnJm2pQ7sT1uV3wX5yZ6aB8cD9eF0gH1i + network: + $ref: '#/components/schemas/CryptoNetwork' + description: Blockchain network (incl. environment) the transaction settled on. BaseTransactionDestination: type: object required: @@ -16950,6 +16980,9 @@ components: type: string description: Currency code for the destination example: EUR + onChainTransaction: + $ref: '#/components/schemas/OnChainTransaction' + description: On-chain transaction that delivered funds to this destination, when the destination is an external crypto wallet. Populated once the crypto transfer has settled; absent for fiat/UMA destinations and for the internal settlement leg of a UMA payment (see `reconciliationInstructions`). AccountTransactionDestination: title: Account Destination allOf: @@ -17084,6 +17117,9 @@ components: type: string description: Currency code for the source example: USD + onChainTransaction: + $ref: '#/components/schemas/OnChainTransaction' + description: On-chain transaction that delivered funds from this source, when the source is an external crypto wallet. Populated once the crypto transfer has settled; absent for fiat/UMA sources and for the internal settlement leg of a UMA payment (see `reconciliationInstructions`). AccountTransactionSource: title: Account Source allOf: @@ -17188,6 +17224,7 @@ components: ReconciliationInstructions: type: object minProperties: 1 + description: Instructions for reconciling a payment with this transaction. For the on-chain transaction to or from an external crypto wallet that is the transaction's own source or destination, use the `onChainTransaction` on the relevant source or destination instead. properties: reference: type: string @@ -17195,7 +17232,7 @@ components: example: UMA-Q12345-REF transactionHash: type: string - description: Transaction hash for the crypto transfer that delivered funds to the transaction destination, when available. + description: Transaction hash of the internal settlement transfer used to deliver a UMA payment — the inter-VASP settlement leg (e.g. USDC on Solana to the receiving partner), when available. This is not a transfer to a customer's own wallet; for that, see the `onChainTransaction` on the transaction's source or destination. example: '0x9f2c6b6f4b6c8f2a8d9e0b1c2d3e4f5061728394a5b6c7d8e9f00112233445566' IncomingRateDetails: description: 'Details about the rate and fees for an incoming transaction. Note: `gridApiFixedFee` is denominated in the receiving currency, so its equivalent value in the sending currency fluctuates with the FX rate. As a result, the total fee on a subsequent quote for the same transfer may differ even if the underlying fee structure is unchanged.' diff --git a/openapi/components/schemas/common/ReconciliationInstructions.yaml b/openapi/components/schemas/common/ReconciliationInstructions.yaml index ee58c1e40..a52648183 100644 --- a/openapi/components/schemas/common/ReconciliationInstructions.yaml +++ b/openapi/components/schemas/common/ReconciliationInstructions.yaml @@ -1,5 +1,9 @@ type: object minProperties: 1 +description: >- + Instructions for reconciling a payment with this transaction. For the on-chain + transaction to or from an external crypto wallet that is the transaction's own source or + destination, use the `onChainTransaction` on the relevant source or destination instead. properties: reference: type: string @@ -10,6 +14,8 @@ properties: transactionHash: type: string description: >- - Transaction hash for the crypto transfer that delivered funds to the - transaction destination, when available. + Transaction hash of the internal settlement transfer used to deliver a UMA payment — + the inter-VASP settlement leg (e.g. USDC on Solana to the receiving partner), when + available. This is not a transfer to a customer's own wallet; for that, see the + `onChainTransaction` on the transaction's source or destination. example: "0x9f2c6b6f4b6c8f2a8d9e0b1c2d3e4f5061728394a5b6c7d8e9f00112233445566" diff --git a/openapi/components/schemas/crypto/CryptoNetwork.yaml b/openapi/components/schemas/crypto/CryptoNetwork.yaml new file mode 100644 index 000000000..5081abb51 --- /dev/null +++ b/openapi/components/schemas/crypto/CryptoNetwork.yaml @@ -0,0 +1,19 @@ +type: string +enum: + - ETHEREUM_MAINNET + - ETHEREUM_TESTNET + - SOLANA_MAINNET + - SOLANA_DEVNET + - BASE_MAINNET + - BASE_TESTNET + - POLYGON_MAINNET + - POLYGON_TESTNET + - TRON_MAINNET + - TRON_TESTNET + - SPARK_MAINNET + - SPARK_REGTEST +description: >- + A blockchain network, including the environment (mainnet vs devnet/testnet/regtest) so an + on-chain transaction can be looked up on the correct explorer. Sandbox transactions report + the devnet/testnet/regtest variant (e.g. SOLANA_DEVNET). +example: SOLANA_MAINNET diff --git a/openapi/components/schemas/transactions/BaseTransactionDestination.yaml b/openapi/components/schemas/transactions/BaseTransactionDestination.yaml index 2d8bc0f9b..999a3696e 100644 --- a/openapi/components/schemas/transactions/BaseTransactionDestination.yaml +++ b/openapi/components/schemas/transactions/BaseTransactionDestination.yaml @@ -8,3 +8,10 @@ properties: type: string description: Currency code for the destination example: EUR + onChainTransaction: + $ref: ./OnChainTransaction.yaml + description: >- + On-chain transaction that delivered funds to this destination, when the destination is + an external crypto wallet. Populated once the crypto transfer has settled; absent for + fiat/UMA destinations and for the internal settlement leg of a UMA payment (see + `reconciliationInstructions`). diff --git a/openapi/components/schemas/transactions/BaseTransactionSource.yaml b/openapi/components/schemas/transactions/BaseTransactionSource.yaml index f87267dfb..db1a16dcd 100644 --- a/openapi/components/schemas/transactions/BaseTransactionSource.yaml +++ b/openapi/components/schemas/transactions/BaseTransactionSource.yaml @@ -8,3 +8,10 @@ properties: type: string description: Currency code for the source example: USD + onChainTransaction: + $ref: ./OnChainTransaction.yaml + description: >- + On-chain transaction that delivered funds from this source, when the source is an + external crypto wallet. Populated once the crypto transfer has settled; absent for + fiat/UMA sources and for the internal settlement leg of a UMA payment (see + `reconciliationInstructions`). diff --git a/openapi/components/schemas/transactions/OnChainTransaction.yaml b/openapi/components/schemas/transactions/OnChainTransaction.yaml new file mode 100644 index 000000000..b988364dc --- /dev/null +++ b/openapi/components/schemas/transactions/OnChainTransaction.yaml @@ -0,0 +1,12 @@ +type: object +required: + - transactionHash + - network +properties: + transactionHash: + type: string + description: On-chain transaction hash of the crypto transfer for this leg of the transaction. + example: '4Nd1m6Qkq7RfKuE5vQ9qP9Tn6H94Ueqb4xXHzsAbd8WgpD9k6oRnJm2pQ7sT1uV3wX5yZ6aB8cD9eF0gH1i' + network: + $ref: ../crypto/CryptoNetwork.yaml + description: Blockchain network (incl. environment) the transaction settled on. From 2584f040bc53d4302c42d01c511b4c3fb7e66168 Mon Sep 17 00:00:00 2001 From: Jeremy Date: Sat, 11 Jul 2026 01:00:51 +0000 Subject: [PATCH 2/7] docs: scope OutgoingTransaction reconciliationInstructions to settlement leg Greptile P1: the field description still promised a crypto transaction hash, which contradicts the sharpened ReconciliationInstructions schema (transactionHash = inter-VASP settlement leg only). Point readers to destination.onChainTransaction for the crypto payout. --- mintlify/openapi.yaml | 2 +- openapi.yaml | 2 +- .../components/schemas/transactions/OutgoingTransaction.yaml | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index ea8af3f40..7debe9362 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -17467,7 +17467,7 @@ components: example: 10 reconciliationInstructions: $ref: '#/components/schemas/ReconciliationInstructions' - description: Reconciliation details for this transaction, including crypto transaction hash when available. + description: Reconciliation details for this transaction. For the on-chain hash of a crypto payout to an external wallet, see the destination's `onChainTransaction` instead. quoteId: type: string description: The ID of the quote that was used to trigger this payment diff --git a/openapi.yaml b/openapi.yaml index ea8af3f40..7debe9362 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -17467,7 +17467,7 @@ components: example: 10 reconciliationInstructions: $ref: '#/components/schemas/ReconciliationInstructions' - description: Reconciliation details for this transaction, including crypto transaction hash when available. + description: Reconciliation details for this transaction. For the on-chain hash of a crypto payout to an external wallet, see the destination's `onChainTransaction` instead. quoteId: type: string description: The ID of the quote that was used to trigger this payment diff --git a/openapi/components/schemas/transactions/OutgoingTransaction.yaml b/openapi/components/schemas/transactions/OutgoingTransaction.yaml index b6ff7eb16..4862163c5 100644 --- a/openapi/components/schemas/transactions/OutgoingTransaction.yaml +++ b/openapi/components/schemas/transactions/OutgoingTransaction.yaml @@ -37,8 +37,8 @@ allOf: reconciliationInstructions: $ref: ../common/ReconciliationInstructions.yaml description: >- - Reconciliation details for this transaction, including crypto - transaction hash when available. + Reconciliation details for this transaction. For the on-chain hash of a crypto + payout to an external wallet, see the destination's `onChainTransaction` instead. quoteId: type: string description: The ID of the quote that was used to trigger this payment From 6d2a457683ec87f837f0bc5447fa9bea9beced36 Mon Sep 17 00:00:00 2001 From: Jeremy Date: Mon, 13 Jul 2026 04:59:46 +0000 Subject: [PATCH 3/7] Declare onChainTransaction per-variant and add Bitcoin L1 networks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Stainless config strips the allOf ref to BaseTransactionSource/Destination from every concrete variant (the base is assumed empty after discriminator removal), so a base-declared onChainTransaction would be missing from generated SDK types — the same way base-declared currency is omitted today. Declare it inline on each variant instead, matching the per-variant discriminator pattern, and drop the base copies. Also add BITCOIN_MAINNET/BITCOIN_TESTNET to CryptoNetwork: grid supports BTC over L1 and a Bitcoin-sourced transaction needs a network value. --- mintlify/openapi.yaml | 45 ++++++++++++------- openapi.yaml | 45 ++++++++++++------- .../schemas/crypto/CryptoNetwork.yaml | 2 + .../AccountTransactionDestination.yaml | 5 +++ .../AccountTransactionSource.yaml | 5 +++ .../BaseTransactionDestination.yaml | 7 --- .../transactions/BaseTransactionSource.yaml | 7 --- .../RealtimeFundingTransactionSource.yaml | 5 +++ .../UmaAddressTransactionDestination.yaml | 5 +++ .../UmaAddressTransactionSource.yaml | 5 +++ 10 files changed, 83 insertions(+), 48 deletions(-) diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 7debe9362..c51e7ab31 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -16939,9 +16939,22 @@ components: - UMA_ADDRESS description: Type of transaction destination example: ACCOUNT + BaseTransactionDestination: + type: object + required: + - destinationType + properties: + destinationType: + $ref: '#/components/schemas/TransactionDestinationType' + currency: + type: string + description: Currency code for the destination + example: EUR CryptoNetwork: type: string enum: + - BITCOIN_MAINNET + - BITCOIN_TESTNET - ETHEREUM_MAINNET - ETHEREUM_TESTNET - SOLANA_MAINNET @@ -16969,20 +16982,6 @@ components: network: $ref: '#/components/schemas/CryptoNetwork' description: Blockchain network (incl. environment) the transaction settled on. - BaseTransactionDestination: - type: object - required: - - destinationType - properties: - destinationType: - $ref: '#/components/schemas/TransactionDestinationType' - currency: - type: string - description: Currency code for the destination - example: EUR - onChainTransaction: - $ref: '#/components/schemas/OnChainTransaction' - description: On-chain transaction that delivered funds to this destination, when the destination is an external crypto wallet. Populated once the crypto transfer has settled; absent for fiat/UMA destinations and for the internal settlement leg of a UMA payment (see `reconciliationInstructions`). AccountTransactionDestination: title: Account Destination allOf: @@ -17000,6 +16999,9 @@ components: type: string description: Destination account identifier example: ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123 + onChainTransaction: + $ref: '#/components/schemas/OnChainTransaction' + description: On-chain transaction that delivered funds to this destination, when the destination is an external crypto wallet. Populated once the crypto transfer has settled. description: Destination account details UmaAddressTransactionDestination: title: UMA Address Destination @@ -17018,6 +17020,9 @@ components: type: string description: UMA address of the recipient example: $receiver@uma.domain.com + onChainTransaction: + $ref: '#/components/schemas/OnChainTransaction' + description: On-chain transaction that delivered funds to this destination, when the destination is an external crypto wallet. Populated once the crypto transfer has settled. description: UMA address destination details TransactionDestinationOneOf: oneOf: @@ -17117,9 +17122,6 @@ components: type: string description: Currency code for the source example: USD - onChainTransaction: - $ref: '#/components/schemas/OnChainTransaction' - description: On-chain transaction that delivered funds from this source, when the source is an external crypto wallet. Populated once the crypto transfer has settled; absent for fiat/UMA sources and for the internal settlement leg of a UMA payment (see `reconciliationInstructions`). AccountTransactionSource: title: Account Source allOf: @@ -17137,6 +17139,9 @@ components: type: string description: Source account identifier example: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965 + onChainTransaction: + $ref: '#/components/schemas/OnChainTransaction' + description: On-chain transaction that delivered funds from this source, when the source is an external crypto wallet. Populated once the crypto transfer has settled. description: Source account details UmaAddressTransactionSource: title: UMA Address Source @@ -17155,6 +17160,9 @@ components: type: string description: UMA address of the sender example: $sender@uma.domain.com + onChainTransaction: + $ref: '#/components/schemas/OnChainTransaction' + description: On-chain transaction that delivered funds from this source, when the source is an external crypto wallet. Populated once the crypto transfer has settled. description: UMA address source details RealtimeFundingTransactionSource: title: External Funding Source @@ -17209,6 +17217,9 @@ components: type: string description: Rail-level tracking identifier for the payment, such as an ACH trace number or a wire IMAD/OMAD, useful for reconciliation. example: '021000020123456' + onChainTransaction: + $ref: '#/components/schemas/OnChainTransaction' + description: On-chain transaction that delivered the funding, when the funds arrived from an external crypto wallet. Populated once the crypto transfer has settled. description: Transaction was funded using an external funding source. All originator fields are optional and populated on a best-effort basis depending on what the funding source provides. TransactionSourceOneOf: oneOf: diff --git a/openapi.yaml b/openapi.yaml index 7debe9362..c51e7ab31 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -16939,9 +16939,22 @@ components: - UMA_ADDRESS description: Type of transaction destination example: ACCOUNT + BaseTransactionDestination: + type: object + required: + - destinationType + properties: + destinationType: + $ref: '#/components/schemas/TransactionDestinationType' + currency: + type: string + description: Currency code for the destination + example: EUR CryptoNetwork: type: string enum: + - BITCOIN_MAINNET + - BITCOIN_TESTNET - ETHEREUM_MAINNET - ETHEREUM_TESTNET - SOLANA_MAINNET @@ -16969,20 +16982,6 @@ components: network: $ref: '#/components/schemas/CryptoNetwork' description: Blockchain network (incl. environment) the transaction settled on. - BaseTransactionDestination: - type: object - required: - - destinationType - properties: - destinationType: - $ref: '#/components/schemas/TransactionDestinationType' - currency: - type: string - description: Currency code for the destination - example: EUR - onChainTransaction: - $ref: '#/components/schemas/OnChainTransaction' - description: On-chain transaction that delivered funds to this destination, when the destination is an external crypto wallet. Populated once the crypto transfer has settled; absent for fiat/UMA destinations and for the internal settlement leg of a UMA payment (see `reconciliationInstructions`). AccountTransactionDestination: title: Account Destination allOf: @@ -17000,6 +16999,9 @@ components: type: string description: Destination account identifier example: ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123 + onChainTransaction: + $ref: '#/components/schemas/OnChainTransaction' + description: On-chain transaction that delivered funds to this destination, when the destination is an external crypto wallet. Populated once the crypto transfer has settled. description: Destination account details UmaAddressTransactionDestination: title: UMA Address Destination @@ -17018,6 +17020,9 @@ components: type: string description: UMA address of the recipient example: $receiver@uma.domain.com + onChainTransaction: + $ref: '#/components/schemas/OnChainTransaction' + description: On-chain transaction that delivered funds to this destination, when the destination is an external crypto wallet. Populated once the crypto transfer has settled. description: UMA address destination details TransactionDestinationOneOf: oneOf: @@ -17117,9 +17122,6 @@ components: type: string description: Currency code for the source example: USD - onChainTransaction: - $ref: '#/components/schemas/OnChainTransaction' - description: On-chain transaction that delivered funds from this source, when the source is an external crypto wallet. Populated once the crypto transfer has settled; absent for fiat/UMA sources and for the internal settlement leg of a UMA payment (see `reconciliationInstructions`). AccountTransactionSource: title: Account Source allOf: @@ -17137,6 +17139,9 @@ components: type: string description: Source account identifier example: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965 + onChainTransaction: + $ref: '#/components/schemas/OnChainTransaction' + description: On-chain transaction that delivered funds from this source, when the source is an external crypto wallet. Populated once the crypto transfer has settled. description: Source account details UmaAddressTransactionSource: title: UMA Address Source @@ -17155,6 +17160,9 @@ components: type: string description: UMA address of the sender example: $sender@uma.domain.com + onChainTransaction: + $ref: '#/components/schemas/OnChainTransaction' + description: On-chain transaction that delivered funds from this source, when the source is an external crypto wallet. Populated once the crypto transfer has settled. description: UMA address source details RealtimeFundingTransactionSource: title: External Funding Source @@ -17209,6 +17217,9 @@ components: type: string description: Rail-level tracking identifier for the payment, such as an ACH trace number or a wire IMAD/OMAD, useful for reconciliation. example: '021000020123456' + onChainTransaction: + $ref: '#/components/schemas/OnChainTransaction' + description: On-chain transaction that delivered the funding, when the funds arrived from an external crypto wallet. Populated once the crypto transfer has settled. description: Transaction was funded using an external funding source. All originator fields are optional and populated on a best-effort basis depending on what the funding source provides. TransactionSourceOneOf: oneOf: diff --git a/openapi/components/schemas/crypto/CryptoNetwork.yaml b/openapi/components/schemas/crypto/CryptoNetwork.yaml index 5081abb51..9794aba47 100644 --- a/openapi/components/schemas/crypto/CryptoNetwork.yaml +++ b/openapi/components/schemas/crypto/CryptoNetwork.yaml @@ -1,5 +1,7 @@ type: string enum: + - BITCOIN_MAINNET + - BITCOIN_TESTNET - ETHEREUM_MAINNET - ETHEREUM_TESTNET - SOLANA_MAINNET diff --git a/openapi/components/schemas/transactions/AccountTransactionDestination.yaml b/openapi/components/schemas/transactions/AccountTransactionDestination.yaml index 1e85b52e9..12a9984e7 100644 --- a/openapi/components/schemas/transactions/AccountTransactionDestination.yaml +++ b/openapi/components/schemas/transactions/AccountTransactionDestination.yaml @@ -14,4 +14,9 @@ allOf: type: string description: Destination account identifier example: ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123 + onChainTransaction: + $ref: ./OnChainTransaction.yaml + description: >- + On-chain transaction that delivered funds to this destination, when the destination + is an external crypto wallet. Populated once the crypto transfer has settled. description: Destination account details diff --git a/openapi/components/schemas/transactions/AccountTransactionSource.yaml b/openapi/components/schemas/transactions/AccountTransactionSource.yaml index f3a05e2a9..98fde70a6 100644 --- a/openapi/components/schemas/transactions/AccountTransactionSource.yaml +++ b/openapi/components/schemas/transactions/AccountTransactionSource.yaml @@ -14,4 +14,9 @@ allOf: type: string description: Source account identifier example: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965 + onChainTransaction: + $ref: ./OnChainTransaction.yaml + description: >- + On-chain transaction that delivered funds from this source, when the source is an + external crypto wallet. Populated once the crypto transfer has settled. description: Source account details diff --git a/openapi/components/schemas/transactions/BaseTransactionDestination.yaml b/openapi/components/schemas/transactions/BaseTransactionDestination.yaml index 999a3696e..2d8bc0f9b 100644 --- a/openapi/components/schemas/transactions/BaseTransactionDestination.yaml +++ b/openapi/components/schemas/transactions/BaseTransactionDestination.yaml @@ -8,10 +8,3 @@ properties: type: string description: Currency code for the destination example: EUR - onChainTransaction: - $ref: ./OnChainTransaction.yaml - description: >- - On-chain transaction that delivered funds to this destination, when the destination is - an external crypto wallet. Populated once the crypto transfer has settled; absent for - fiat/UMA destinations and for the internal settlement leg of a UMA payment (see - `reconciliationInstructions`). diff --git a/openapi/components/schemas/transactions/BaseTransactionSource.yaml b/openapi/components/schemas/transactions/BaseTransactionSource.yaml index db1a16dcd..f87267dfb 100644 --- a/openapi/components/schemas/transactions/BaseTransactionSource.yaml +++ b/openapi/components/schemas/transactions/BaseTransactionSource.yaml @@ -8,10 +8,3 @@ properties: type: string description: Currency code for the source example: USD - onChainTransaction: - $ref: ./OnChainTransaction.yaml - description: >- - On-chain transaction that delivered funds from this source, when the source is an - external crypto wallet. Populated once the crypto transfer has settled; absent for - fiat/UMA sources and for the internal settlement leg of a UMA payment (see - `reconciliationInstructions`). diff --git a/openapi/components/schemas/transactions/RealtimeFundingTransactionSource.yaml b/openapi/components/schemas/transactions/RealtimeFundingTransactionSource.yaml index 8afbf9562..256f106a5 100644 --- a/openapi/components/schemas/transactions/RealtimeFundingTransactionSource.yaml +++ b/openapi/components/schemas/transactions/RealtimeFundingTransactionSource.yaml @@ -60,6 +60,11 @@ allOf: Rail-level tracking identifier for the payment, such as an ACH trace number or a wire IMAD/OMAD, useful for reconciliation. example: '021000020123456' + onChainTransaction: + $ref: ./OnChainTransaction.yaml + description: >- + On-chain transaction that delivered the funding, when the funds arrived from an + external crypto wallet. Populated once the crypto transfer has settled. description: >- Transaction was funded using an external funding source. All originator fields are optional and populated on a best-effort basis depending on what diff --git a/openapi/components/schemas/transactions/UmaAddressTransactionDestination.yaml b/openapi/components/schemas/transactions/UmaAddressTransactionDestination.yaml index eeba5ba99..e75ceff93 100644 --- a/openapi/components/schemas/transactions/UmaAddressTransactionDestination.yaml +++ b/openapi/components/schemas/transactions/UmaAddressTransactionDestination.yaml @@ -14,4 +14,9 @@ allOf: type: string description: UMA address of the recipient example: $receiver@uma.domain.com + onChainTransaction: + $ref: ./OnChainTransaction.yaml + description: >- + On-chain transaction that delivered funds to this destination, when the destination + is an external crypto wallet. Populated once the crypto transfer has settled. description: UMA address destination details diff --git a/openapi/components/schemas/transactions/UmaAddressTransactionSource.yaml b/openapi/components/schemas/transactions/UmaAddressTransactionSource.yaml index ebc7162e1..3309c4782 100644 --- a/openapi/components/schemas/transactions/UmaAddressTransactionSource.yaml +++ b/openapi/components/schemas/transactions/UmaAddressTransactionSource.yaml @@ -14,4 +14,9 @@ allOf: type: string description: UMA address of the sender example: $sender@uma.domain.com + onChainTransaction: + $ref: ./OnChainTransaction.yaml + description: >- + On-chain transaction that delivered funds from this source, when the source is an + external crypto wallet. Populated once the crypto transfer has settled. description: UMA address source details From 1f83f74258281a799f16dff99778cd9848f2ca6f Mon Sep 17 00:00:00 2001 From: Jeremy Date: Mon, 13 Jul 2026 05:38:34 +0000 Subject: [PATCH 4/7] docs: point receipts and reconciliation guides at per-leg onChainTransaction MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The receipts field-mapping table anticipated a dedicated hash field — point it at source/destination onChainTransaction with reconciliationInstructions.transactionHash scoped to the UMA settlement leg. Add a note to the reconciliation guide explaining when source/destination carry onChainTransaction. --- mintlify/snippets/receipts.mdx | 2 +- mintlify/snippets/reconciliation/reconciliation.mdx | 7 +++++++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/mintlify/snippets/receipts.mdx b/mintlify/snippets/receipts.mdx index 818199ede..3059d196e 100644 --- a/mintlify/snippets/receipts.mdx +++ b/mintlify/snippets/receipts.mdx @@ -197,7 +197,7 @@ Most receipt fields come directly from the [transaction object](/api-reference/t | Total to recipient | `receivedAmount.amount` + `receivedAmount.currency` | | Total transfer fees | `fees` (smallest unit of the sending currency) | | Exchange rate | `exchangeRate` | -| Transaction hash / VC address(es) | `reconciliationInstructions.transactionHash` (a dedicated transaction hash field may be exposed directly on the transaction) | +| Transaction hash / VC address(es) | `source.onChainTransaction` / `destination.onChainTransaction` (`transactionHash` + `network`) when that side is an external crypto wallet; `reconciliationInstructions.transactionHash` carries the internal UMA settlement-leg hash | ## Example: send a receipt on completion diff --git a/mintlify/snippets/reconciliation/reconciliation.mdx b/mintlify/snippets/reconciliation/reconciliation.mdx index 28be2192f..c76faf3ae 100644 --- a/mintlify/snippets/reconciliation/reconciliation.mdx +++ b/mintlify/snippets/reconciliation/reconciliation.mdx @@ -58,6 +58,13 @@ Sample webhook payload: } } ``` + + +When the transaction's source or destination is an external crypto wallet, that `source` / +`destination` object also includes an `onChainTransaction` (`transactionHash` + `network`, +e.g. `SOLANA_MAINNET`) once the crypto transfer settles — use it to match the transfer on a +block explorer. + From 0fba3a71257f1bad0577c7c3dcbcb8c646734722 Mon Sep 17 00:00:00 2001 From: Jeremy Date: Mon, 13 Jul 2026 05:53:14 +0000 Subject: [PATCH 5/7] docs: add crypto payout/deposit webhook examples showing onChainTransaction New OUTGOING_PAYMENT.COMPLETED and INCOMING_PAYMENT.COMPLETED example variants where the external-crypto-wallet leg carries onChainTransaction, so the API reference shows the field in a realistic payload. Existing fiat/UMA examples correctly omit it. --- mintlify/openapi.yaml | 73 ++++++++++++++++++++++++++ openapi.yaml | 73 ++++++++++++++++++++++++++ openapi/webhooks/incoming-payment.yaml | 32 +++++++++++ openapi/webhooks/outgoing-payment.yaml | 41 +++++++++++++++ 4 files changed, 219 insertions(+) diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index c51e7ab31..57fdf0af0 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -7830,6 +7830,38 @@ webhooks: description: Payment for services reconciliationInstructions: reference: REF-123456789 + incomingCompletedCryptoPayment: + summary: Completed payment funded from an external crypto wallet + value: + id: Webhook:019542f5-b3e7-1d02-0000-000000000009 + type: INCOMING_PAYMENT.COMPLETED + timestamp: '2025-08-15T14:32:00Z' + data: + id: Transaction:019542f5-b3e7-1d02-0000-000000000006 + status: COMPLETED + type: INCOMING + direction: CREDIT + source: + sourceType: REALTIME_FUNDING + currency: USDC + onChainTransaction: + transactionHash: 5Qe2n7Rlr8SgLvF6wR0rQ0Uo7I05Vfrc5yYIatBce9XhqE0l7pSoKn3qR8tU2vW4xY6zA7bC9dE0fG1hI2j + network: SOLANA_MAINNET + destination: + destinationType: ACCOUNT + accountId: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965 + customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 + platformCustomerId: 18d3e5f7b4a9c2 + receivedAmount: + amount: 100000 + currency: + code: USDC + name: USD Coin + symbol: '' + decimals: 6 + settledAt: '2025-08-15T14:30:00Z' + createdAt: '2025-08-15T14:25:18Z' + description: USDC deposit from self-custody wallet responses: '200': description: | @@ -7957,6 +7989,47 @@ webhooks: gridApiFixedFee: 10 gridApiVariableFeeRate: 0.003 gridApiVariableFeeAmount: 30 + outgoingCompletedCryptoPayment: + summary: Completed crypto payout to an external wallet + value: + id: Webhook:019542f5-b3e7-1d02-0000-000000000008 + type: OUTGOING_PAYMENT.COMPLETED + timestamp: '2025-08-15T14:32:00Z' + data: + id: Transaction:019542f5-b3e7-1d02-0000-000000000009 + status: COMPLETED + type: OUTGOING + direction: DEBIT + source: + sourceType: ACCOUNT + accountId: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965 + destination: + destinationType: ACCOUNT + accountId: ExternalAccount:c34dcbd6-dced-4ec4-b756-3c3a9ea3d789 + onChainTransaction: + transactionHash: 4Nd1m6Qkq7RfKuE5vQ9qP9Tn6H94Ueqb4xXHzsAbd8WgpD9k6oRnJm2pQ7sT1uV3wX5yZ6aB8cD9eF0gH1i + network: SOLANA_MAINNET + customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 + platformCustomerId: 18d3e5f7b4a9c2 + sentAmount: + amount: 100000 + currency: + code: USDC + name: USD Coin + symbol: '' + decimals: 6 + receivedAmount: + amount: 100000 + currency: + code: USDC + name: USD Coin + symbol: '' + decimals: 6 + quoteId: Quote:019542f5-b3e7-1d02-0000-000000000010 + settledAt: '2025-08-15T14:30:00Z' + createdAt: '2025-08-15T14:25:18Z' + description: USDC withdrawal to self-custody wallet + paymentInstructions: [] failedPayment: summary: Failed outgoing payment value: diff --git a/openapi.yaml b/openapi.yaml index c51e7ab31..57fdf0af0 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -7830,6 +7830,38 @@ webhooks: description: Payment for services reconciliationInstructions: reference: REF-123456789 + incomingCompletedCryptoPayment: + summary: Completed payment funded from an external crypto wallet + value: + id: Webhook:019542f5-b3e7-1d02-0000-000000000009 + type: INCOMING_PAYMENT.COMPLETED + timestamp: '2025-08-15T14:32:00Z' + data: + id: Transaction:019542f5-b3e7-1d02-0000-000000000006 + status: COMPLETED + type: INCOMING + direction: CREDIT + source: + sourceType: REALTIME_FUNDING + currency: USDC + onChainTransaction: + transactionHash: 5Qe2n7Rlr8SgLvF6wR0rQ0Uo7I05Vfrc5yYIatBce9XhqE0l7pSoKn3qR8tU2vW4xY6zA7bC9dE0fG1hI2j + network: SOLANA_MAINNET + destination: + destinationType: ACCOUNT + accountId: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965 + customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 + platformCustomerId: 18d3e5f7b4a9c2 + receivedAmount: + amount: 100000 + currency: + code: USDC + name: USD Coin + symbol: '' + decimals: 6 + settledAt: '2025-08-15T14:30:00Z' + createdAt: '2025-08-15T14:25:18Z' + description: USDC deposit from self-custody wallet responses: '200': description: | @@ -7957,6 +7989,47 @@ webhooks: gridApiFixedFee: 10 gridApiVariableFeeRate: 0.003 gridApiVariableFeeAmount: 30 + outgoingCompletedCryptoPayment: + summary: Completed crypto payout to an external wallet + value: + id: Webhook:019542f5-b3e7-1d02-0000-000000000008 + type: OUTGOING_PAYMENT.COMPLETED + timestamp: '2025-08-15T14:32:00Z' + data: + id: Transaction:019542f5-b3e7-1d02-0000-000000000009 + status: COMPLETED + type: OUTGOING + direction: DEBIT + source: + sourceType: ACCOUNT + accountId: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965 + destination: + destinationType: ACCOUNT + accountId: ExternalAccount:c34dcbd6-dced-4ec4-b756-3c3a9ea3d789 + onChainTransaction: + transactionHash: 4Nd1m6Qkq7RfKuE5vQ9qP9Tn6H94Ueqb4xXHzsAbd8WgpD9k6oRnJm2pQ7sT1uV3wX5yZ6aB8cD9eF0gH1i + network: SOLANA_MAINNET + customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 + platformCustomerId: 18d3e5f7b4a9c2 + sentAmount: + amount: 100000 + currency: + code: USDC + name: USD Coin + symbol: '' + decimals: 6 + receivedAmount: + amount: 100000 + currency: + code: USDC + name: USD Coin + symbol: '' + decimals: 6 + quoteId: Quote:019542f5-b3e7-1d02-0000-000000000010 + settledAt: '2025-08-15T14:30:00Z' + createdAt: '2025-08-15T14:25:18Z' + description: USDC withdrawal to self-custody wallet + paymentInstructions: [] failedPayment: summary: Failed outgoing payment value: diff --git a/openapi/webhooks/incoming-payment.yaml b/openapi/webhooks/incoming-payment.yaml index 2127d1ad3..894b0ecfc 100644 --- a/openapi/webhooks/incoming-payment.yaml +++ b/openapi/webhooks/incoming-payment.yaml @@ -133,6 +133,38 @@ post: description: Payment for services reconciliationInstructions: reference: REF-123456789 + incomingCompletedCryptoPayment: + summary: Completed payment funded from an external crypto wallet + value: + id: Webhook:019542f5-b3e7-1d02-0000-000000000009 + type: INCOMING_PAYMENT.COMPLETED + timestamp: '2025-08-15T14:32:00Z' + data: + id: Transaction:019542f5-b3e7-1d02-0000-000000000006 + status: COMPLETED + type: INCOMING + direction: CREDIT + source: + sourceType: REALTIME_FUNDING + currency: USDC + onChainTransaction: + transactionHash: 5Qe2n7Rlr8SgLvF6wR0rQ0Uo7I05Vfrc5yYIatBce9XhqE0l7pSoKn3qR8tU2vW4xY6zA7bC9dE0fG1hI2j + network: SOLANA_MAINNET + destination: + destinationType: ACCOUNT + accountId: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965 + customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 + platformCustomerId: 18d3e5f7b4a9c2 + receivedAmount: + amount: 100000 + currency: + code: USDC + name: USD Coin + symbol: '' + decimals: 6 + settledAt: '2025-08-15T14:30:00Z' + createdAt: '2025-08-15T14:25:18Z' + description: USDC deposit from self-custody wallet responses: '200': description: > diff --git a/openapi/webhooks/outgoing-payment.yaml b/openapi/webhooks/outgoing-payment.yaml index 2be94b05c..b9129cb75 100644 --- a/openapi/webhooks/outgoing-payment.yaml +++ b/openapi/webhooks/outgoing-payment.yaml @@ -88,6 +88,47 @@ post: gridApiFixedFee: 10 gridApiVariableFeeRate: 0.003 gridApiVariableFeeAmount: 30 + outgoingCompletedCryptoPayment: + summary: Completed crypto payout to an external wallet + value: + id: Webhook:019542f5-b3e7-1d02-0000-000000000008 + type: OUTGOING_PAYMENT.COMPLETED + timestamp: '2025-08-15T14:32:00Z' + data: + id: Transaction:019542f5-b3e7-1d02-0000-000000000009 + status: COMPLETED + type: OUTGOING + direction: DEBIT + source: + sourceType: ACCOUNT + accountId: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965 + destination: + destinationType: ACCOUNT + accountId: ExternalAccount:c34dcbd6-dced-4ec4-b756-3c3a9ea3d789 + onChainTransaction: + transactionHash: 4Nd1m6Qkq7RfKuE5vQ9qP9Tn6H94Ueqb4xXHzsAbd8WgpD9k6oRnJm2pQ7sT1uV3wX5yZ6aB8cD9eF0gH1i + network: SOLANA_MAINNET + customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 + platformCustomerId: 18d3e5f7b4a9c2 + sentAmount: + amount: 100000 + currency: + code: USDC + name: USD Coin + symbol: '' + decimals: 6 + receivedAmount: + amount: 100000 + currency: + code: USDC + name: USD Coin + symbol: '' + decimals: 6 + quoteId: Quote:019542f5-b3e7-1d02-0000-000000000010 + settledAt: '2025-08-15T14:30:00Z' + createdAt: '2025-08-15T14:25:18Z' + description: USDC withdrawal to self-custody wallet + paymentInstructions: [] failedPayment: summary: Failed outgoing payment value: From cba4acd787acaf259f593e77b79fe5664054a622 Mon Sep 17 00:00:00 2001 From: Jeremy Date: Mon, 13 Jul 2026 06:18:46 +0000 Subject: [PATCH 6/7] Scope onChainTransaction to account variants and fix docs review findings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove onChainTransaction from the UMA_ADDRESS source/destination variants: a UMA endpoint settles via the counterparty VASP, never a customer external wallet, so the field could not be truthfully populated there. - Hedge the reconciliation-guide note: the hash can land after the terminal status, so terminal webhook payloads may not include it — read it via GET /transactions. - Split the receipts mapping row: the wallet address comes from the external account's accountInfo, not onChainTransaction. - Use valid base58 strings for the Solana example signatures. --- mintlify/openapi.yaml | 12 +++--------- mintlify/snippets/receipts.mdx | 3 ++- mintlify/snippets/reconciliation/reconciliation.mdx | 4 +++- openapi.yaml | 12 +++--------- .../schemas/transactions/OnChainTransaction.yaml | 2 +- .../UmaAddressTransactionDestination.yaml | 5 ----- .../transactions/UmaAddressTransactionSource.yaml | 5 ----- openapi/webhooks/incoming-payment.yaml | 2 +- openapi/webhooks/outgoing-payment.yaml | 2 +- 9 files changed, 14 insertions(+), 33 deletions(-) diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 57fdf0af0..c60f39659 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -7845,7 +7845,7 @@ webhooks: sourceType: REALTIME_FUNDING currency: USDC onChainTransaction: - transactionHash: 5Qe2n7Rlr8SgLvF6wR0rQ0Uo7I05Vfrc5yYIatBce9XhqE0l7pSoKn3qR8tU2vW4xY6zA7bC9dE0fG1hI2j + transactionHash: 7RJWhvQBQPEjJmki5fhBboGBWRJhmcFkMvrr4Fu3tMSJ5EdynMEiYSyiWAH9GpcbHpeUzeSQF9ZY6q4x8AhBskUf network: SOLANA_MAINNET destination: destinationType: ACCOUNT @@ -8007,7 +8007,7 @@ webhooks: destinationType: ACCOUNT accountId: ExternalAccount:c34dcbd6-dced-4ec4-b756-3c3a9ea3d789 onChainTransaction: - transactionHash: 4Nd1m6Qkq7RfKuE5vQ9qP9Tn6H94Ueqb4xXHzsAbd8WgpD9k6oRnJm2pQ7sT1uV3wX5yZ6aB8cD9eF0gH1i + transactionHash: h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx network: SOLANA_MAINNET customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: 18d3e5f7b4a9c2 @@ -17051,7 +17051,7 @@ components: transactionHash: type: string description: On-chain transaction hash of the crypto transfer for this leg of the transaction. - example: 4Nd1m6Qkq7RfKuE5vQ9qP9Tn6H94Ueqb4xXHzsAbd8WgpD9k6oRnJm2pQ7sT1uV3wX5yZ6aB8cD9eF0gH1i + example: h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx network: $ref: '#/components/schemas/CryptoNetwork' description: Blockchain network (incl. environment) the transaction settled on. @@ -17093,9 +17093,6 @@ components: type: string description: UMA address of the recipient example: $receiver@uma.domain.com - onChainTransaction: - $ref: '#/components/schemas/OnChainTransaction' - description: On-chain transaction that delivered funds to this destination, when the destination is an external crypto wallet. Populated once the crypto transfer has settled. description: UMA address destination details TransactionDestinationOneOf: oneOf: @@ -17233,9 +17230,6 @@ components: type: string description: UMA address of the sender example: $sender@uma.domain.com - onChainTransaction: - $ref: '#/components/schemas/OnChainTransaction' - description: On-chain transaction that delivered funds from this source, when the source is an external crypto wallet. Populated once the crypto transfer has settled. description: UMA address source details RealtimeFundingTransactionSource: title: External Funding Source diff --git a/mintlify/snippets/receipts.mdx b/mintlify/snippets/receipts.mdx index 3059d196e..d0659eaeb 100644 --- a/mintlify/snippets/receipts.mdx +++ b/mintlify/snippets/receipts.mdx @@ -197,7 +197,8 @@ Most receipt fields come directly from the [transaction object](/api-reference/t | Total to recipient | `receivedAmount.amount` + `receivedAmount.currency` | | Total transfer fees | `fees` (smallest unit of the sending currency) | | Exchange rate | `exchangeRate` | -| Transaction hash / VC address(es) | `source.onChainTransaction` / `destination.onChainTransaction` (`transactionHash` + `network`) when that side is an external crypto wallet; `reconciliationInstructions.transactionHash` carries the internal UMA settlement-leg hash | +| Transaction hash | `source.onChainTransaction` / `destination.onChainTransaction` (`transactionHash` + `network`) when that side is an external crypto wallet; `reconciliationInstructions.transactionHash` carries the internal UMA settlement-leg hash | +| VC address(es) | Resolve `destination.accountId` to the external account and read the wallet address from its `accountInfo` | ## Example: send a receipt on completion diff --git a/mintlify/snippets/reconciliation/reconciliation.mdx b/mintlify/snippets/reconciliation/reconciliation.mdx index c76faf3ae..4942a90a2 100644 --- a/mintlify/snippets/reconciliation/reconciliation.mdx +++ b/mintlify/snippets/reconciliation/reconciliation.mdx @@ -63,7 +63,9 @@ Sample webhook payload: When the transaction's source or destination is an external crypto wallet, that `source` / `destination` object also includes an `onChainTransaction` (`transactionHash` + `network`, e.g. `SOLANA_MAINNET`) once the crypto transfer settles — use it to match the transfer on a -block explorer. +block explorer. The hash can land shortly after the terminal status, so a terminal webhook +payload may not include it yet; retrieve the transaction (`GET /transactions/{id}`) to read +it once settled. diff --git a/openapi.yaml b/openapi.yaml index 57fdf0af0..c60f39659 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -7845,7 +7845,7 @@ webhooks: sourceType: REALTIME_FUNDING currency: USDC onChainTransaction: - transactionHash: 5Qe2n7Rlr8SgLvF6wR0rQ0Uo7I05Vfrc5yYIatBce9XhqE0l7pSoKn3qR8tU2vW4xY6zA7bC9dE0fG1hI2j + transactionHash: 7RJWhvQBQPEjJmki5fhBboGBWRJhmcFkMvrr4Fu3tMSJ5EdynMEiYSyiWAH9GpcbHpeUzeSQF9ZY6q4x8AhBskUf network: SOLANA_MAINNET destination: destinationType: ACCOUNT @@ -8007,7 +8007,7 @@ webhooks: destinationType: ACCOUNT accountId: ExternalAccount:c34dcbd6-dced-4ec4-b756-3c3a9ea3d789 onChainTransaction: - transactionHash: 4Nd1m6Qkq7RfKuE5vQ9qP9Tn6H94Ueqb4xXHzsAbd8WgpD9k6oRnJm2pQ7sT1uV3wX5yZ6aB8cD9eF0gH1i + transactionHash: h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx network: SOLANA_MAINNET customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: 18d3e5f7b4a9c2 @@ -17051,7 +17051,7 @@ components: transactionHash: type: string description: On-chain transaction hash of the crypto transfer for this leg of the transaction. - example: 4Nd1m6Qkq7RfKuE5vQ9qP9Tn6H94Ueqb4xXHzsAbd8WgpD9k6oRnJm2pQ7sT1uV3wX5yZ6aB8cD9eF0gH1i + example: h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx network: $ref: '#/components/schemas/CryptoNetwork' description: Blockchain network (incl. environment) the transaction settled on. @@ -17093,9 +17093,6 @@ components: type: string description: UMA address of the recipient example: $receiver@uma.domain.com - onChainTransaction: - $ref: '#/components/schemas/OnChainTransaction' - description: On-chain transaction that delivered funds to this destination, when the destination is an external crypto wallet. Populated once the crypto transfer has settled. description: UMA address destination details TransactionDestinationOneOf: oneOf: @@ -17233,9 +17230,6 @@ components: type: string description: UMA address of the sender example: $sender@uma.domain.com - onChainTransaction: - $ref: '#/components/schemas/OnChainTransaction' - description: On-chain transaction that delivered funds from this source, when the source is an external crypto wallet. Populated once the crypto transfer has settled. description: UMA address source details RealtimeFundingTransactionSource: title: External Funding Source diff --git a/openapi/components/schemas/transactions/OnChainTransaction.yaml b/openapi/components/schemas/transactions/OnChainTransaction.yaml index b988364dc..e3baa4655 100644 --- a/openapi/components/schemas/transactions/OnChainTransaction.yaml +++ b/openapi/components/schemas/transactions/OnChainTransaction.yaml @@ -6,7 +6,7 @@ properties: transactionHash: type: string description: On-chain transaction hash of the crypto transfer for this leg of the transaction. - example: '4Nd1m6Qkq7RfKuE5vQ9qP9Tn6H94Ueqb4xXHzsAbd8WgpD9k6oRnJm2pQ7sT1uV3wX5yZ6aB8cD9eF0gH1i' + example: 'h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx' network: $ref: ../crypto/CryptoNetwork.yaml description: Blockchain network (incl. environment) the transaction settled on. diff --git a/openapi/components/schemas/transactions/UmaAddressTransactionDestination.yaml b/openapi/components/schemas/transactions/UmaAddressTransactionDestination.yaml index e75ceff93..eeba5ba99 100644 --- a/openapi/components/schemas/transactions/UmaAddressTransactionDestination.yaml +++ b/openapi/components/schemas/transactions/UmaAddressTransactionDestination.yaml @@ -14,9 +14,4 @@ allOf: type: string description: UMA address of the recipient example: $receiver@uma.domain.com - onChainTransaction: - $ref: ./OnChainTransaction.yaml - description: >- - On-chain transaction that delivered funds to this destination, when the destination - is an external crypto wallet. Populated once the crypto transfer has settled. description: UMA address destination details diff --git a/openapi/components/schemas/transactions/UmaAddressTransactionSource.yaml b/openapi/components/schemas/transactions/UmaAddressTransactionSource.yaml index 3309c4782..ebc7162e1 100644 --- a/openapi/components/schemas/transactions/UmaAddressTransactionSource.yaml +++ b/openapi/components/schemas/transactions/UmaAddressTransactionSource.yaml @@ -14,9 +14,4 @@ allOf: type: string description: UMA address of the sender example: $sender@uma.domain.com - onChainTransaction: - $ref: ./OnChainTransaction.yaml - description: >- - On-chain transaction that delivered funds from this source, when the source is an - external crypto wallet. Populated once the crypto transfer has settled. description: UMA address source details diff --git a/openapi/webhooks/incoming-payment.yaml b/openapi/webhooks/incoming-payment.yaml index 894b0ecfc..2570fe896 100644 --- a/openapi/webhooks/incoming-payment.yaml +++ b/openapi/webhooks/incoming-payment.yaml @@ -148,7 +148,7 @@ post: sourceType: REALTIME_FUNDING currency: USDC onChainTransaction: - transactionHash: 5Qe2n7Rlr8SgLvF6wR0rQ0Uo7I05Vfrc5yYIatBce9XhqE0l7pSoKn3qR8tU2vW4xY6zA7bC9dE0fG1hI2j + transactionHash: 7RJWhvQBQPEjJmki5fhBboGBWRJhmcFkMvrr4Fu3tMSJ5EdynMEiYSyiWAH9GpcbHpeUzeSQF9ZY6q4x8AhBskUf network: SOLANA_MAINNET destination: destinationType: ACCOUNT diff --git a/openapi/webhooks/outgoing-payment.yaml b/openapi/webhooks/outgoing-payment.yaml index b9129cb75..6cb3034b4 100644 --- a/openapi/webhooks/outgoing-payment.yaml +++ b/openapi/webhooks/outgoing-payment.yaml @@ -106,7 +106,7 @@ post: destinationType: ACCOUNT accountId: ExternalAccount:c34dcbd6-dced-4ec4-b756-3c3a9ea3d789 onChainTransaction: - transactionHash: 4Nd1m6Qkq7RfKuE5vQ9qP9Tn6H94Ueqb4xXHzsAbd8WgpD9k6oRnJm2pQ7sT1uV3wX5yZ6aB8cD9eF0gH1i + transactionHash: h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx network: SOLANA_MAINNET customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: 18d3e5f7b4a9c2 From 2e33d9a29a81d7cdafc889555b5888eb4ec1d23f Mon Sep 17 00:00:00 2001 From: Jeremy Date: Mon, 13 Jul 2026 19:56:24 +0000 Subject: [PATCH 7/7] Make onChainTransaction network environment-agnostic MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reviewer feedback: the rest of the API (e.g. cryptoNetwork on the withdrawal-fee request) uses bare chain names and infers mainnet vs test network from the platform environment. Drop the environment suffix from CryptoNetwork (SOLANA_MAINNET/DEVNET → SOLANA, etc.) and document that the environment follows the platform, for consistency. --- mintlify/openapi.yaml | 31 +++++++------------ .../reconciliation/reconciliation.mdx | 2 +- openapi.yaml | 31 +++++++------------ .../schemas/crypto/CryptoNetwork.yaml | 30 +++++++----------- .../transactions/OnChainTransaction.yaml | 2 +- openapi/webhooks/incoming-payment.yaml | 2 +- openapi/webhooks/outgoing-payment.yaml | 2 +- 7 files changed, 40 insertions(+), 60 deletions(-) diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index c60f39659..06658cda9 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -7846,7 +7846,7 @@ webhooks: currency: USDC onChainTransaction: transactionHash: 7RJWhvQBQPEjJmki5fhBboGBWRJhmcFkMvrr4Fu3tMSJ5EdynMEiYSyiWAH9GpcbHpeUzeSQF9ZY6q4x8AhBskUf - network: SOLANA_MAINNET + network: SOLANA destination: destinationType: ACCOUNT accountId: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965 @@ -8008,7 +8008,7 @@ webhooks: accountId: ExternalAccount:c34dcbd6-dced-4ec4-b756-3c3a9ea3d789 onChainTransaction: transactionHash: h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx - network: SOLANA_MAINNET + network: SOLANA customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: 18d3e5f7b4a9c2 sentAmount: @@ -17026,22 +17026,15 @@ components: CryptoNetwork: type: string enum: - - BITCOIN_MAINNET - - BITCOIN_TESTNET - - ETHEREUM_MAINNET - - ETHEREUM_TESTNET - - SOLANA_MAINNET - - SOLANA_DEVNET - - BASE_MAINNET - - BASE_TESTNET - - POLYGON_MAINNET - - POLYGON_TESTNET - - TRON_MAINNET - - TRON_TESTNET - - SPARK_MAINNET - - SPARK_REGTEST - description: A blockchain network, including the environment (mainnet vs devnet/testnet/regtest) so an on-chain transaction can be looked up on the correct explorer. Sandbox transactions report the devnet/testnet/regtest variant (e.g. SOLANA_DEVNET). - example: SOLANA_MAINNET + - BITCOIN + - ETHEREUM + - SOLANA + - BASE + - POLYGON + - TRON + - SPARK + description: The blockchain network an on-chain transaction settled on. Whether this is the mainnet or a test network (e.g. Solana devnet) is determined by your platform's environment — sandbox platforms operate on test networks, production platforms on mainnet — mirroring how `cryptoNetwork` is interpreted elsewhere in the API. + example: SOLANA OnChainTransaction: type: object required: @@ -17054,7 +17047,7 @@ components: example: h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx network: $ref: '#/components/schemas/CryptoNetwork' - description: Blockchain network (incl. environment) the transaction settled on. + description: Blockchain network the transaction settled on (mainnet vs test network is determined by your platform environment). AccountTransactionDestination: title: Account Destination allOf: diff --git a/mintlify/snippets/reconciliation/reconciliation.mdx b/mintlify/snippets/reconciliation/reconciliation.mdx index 4942a90a2..f918ed2da 100644 --- a/mintlify/snippets/reconciliation/reconciliation.mdx +++ b/mintlify/snippets/reconciliation/reconciliation.mdx @@ -62,7 +62,7 @@ Sample webhook payload: When the transaction's source or destination is an external crypto wallet, that `source` / `destination` object also includes an `onChainTransaction` (`transactionHash` + `network`, -e.g. `SOLANA_MAINNET`) once the crypto transfer settles — use it to match the transfer on a +e.g. `SOLANA`) once the crypto transfer settles — use it to match the transfer on a block explorer. The hash can land shortly after the terminal status, so a terminal webhook payload may not include it yet; retrieve the transaction (`GET /transactions/{id}`) to read it once settled. diff --git a/openapi.yaml b/openapi.yaml index c60f39659..06658cda9 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -7846,7 +7846,7 @@ webhooks: currency: USDC onChainTransaction: transactionHash: 7RJWhvQBQPEjJmki5fhBboGBWRJhmcFkMvrr4Fu3tMSJ5EdynMEiYSyiWAH9GpcbHpeUzeSQF9ZY6q4x8AhBskUf - network: SOLANA_MAINNET + network: SOLANA destination: destinationType: ACCOUNT accountId: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965 @@ -8008,7 +8008,7 @@ webhooks: accountId: ExternalAccount:c34dcbd6-dced-4ec4-b756-3c3a9ea3d789 onChainTransaction: transactionHash: h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx - network: SOLANA_MAINNET + network: SOLANA customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: 18d3e5f7b4a9c2 sentAmount: @@ -17026,22 +17026,15 @@ components: CryptoNetwork: type: string enum: - - BITCOIN_MAINNET - - BITCOIN_TESTNET - - ETHEREUM_MAINNET - - ETHEREUM_TESTNET - - SOLANA_MAINNET - - SOLANA_DEVNET - - BASE_MAINNET - - BASE_TESTNET - - POLYGON_MAINNET - - POLYGON_TESTNET - - TRON_MAINNET - - TRON_TESTNET - - SPARK_MAINNET - - SPARK_REGTEST - description: A blockchain network, including the environment (mainnet vs devnet/testnet/regtest) so an on-chain transaction can be looked up on the correct explorer. Sandbox transactions report the devnet/testnet/regtest variant (e.g. SOLANA_DEVNET). - example: SOLANA_MAINNET + - BITCOIN + - ETHEREUM + - SOLANA + - BASE + - POLYGON + - TRON + - SPARK + description: The blockchain network an on-chain transaction settled on. Whether this is the mainnet or a test network (e.g. Solana devnet) is determined by your platform's environment — sandbox platforms operate on test networks, production platforms on mainnet — mirroring how `cryptoNetwork` is interpreted elsewhere in the API. + example: SOLANA OnChainTransaction: type: object required: @@ -17054,7 +17047,7 @@ components: example: h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx network: $ref: '#/components/schemas/CryptoNetwork' - description: Blockchain network (incl. environment) the transaction settled on. + description: Blockchain network the transaction settled on (mainnet vs test network is determined by your platform environment). AccountTransactionDestination: title: Account Destination allOf: diff --git a/openapi/components/schemas/crypto/CryptoNetwork.yaml b/openapi/components/schemas/crypto/CryptoNetwork.yaml index 9794aba47..8ea3884d6 100644 --- a/openapi/components/schemas/crypto/CryptoNetwork.yaml +++ b/openapi/components/schemas/crypto/CryptoNetwork.yaml @@ -1,21 +1,15 @@ type: string enum: - - BITCOIN_MAINNET - - BITCOIN_TESTNET - - ETHEREUM_MAINNET - - ETHEREUM_TESTNET - - SOLANA_MAINNET - - SOLANA_DEVNET - - BASE_MAINNET - - BASE_TESTNET - - POLYGON_MAINNET - - POLYGON_TESTNET - - TRON_MAINNET - - TRON_TESTNET - - SPARK_MAINNET - - SPARK_REGTEST + - BITCOIN + - ETHEREUM + - SOLANA + - BASE + - POLYGON + - TRON + - SPARK description: >- - A blockchain network, including the environment (mainnet vs devnet/testnet/regtest) so an - on-chain transaction can be looked up on the correct explorer. Sandbox transactions report - the devnet/testnet/regtest variant (e.g. SOLANA_DEVNET). -example: SOLANA_MAINNET + The blockchain network an on-chain transaction settled on. Whether this is the + mainnet or a test network (e.g. Solana devnet) is determined by your platform's + environment — sandbox platforms operate on test networks, production platforms on + mainnet — mirroring how `cryptoNetwork` is interpreted elsewhere in the API. +example: SOLANA diff --git a/openapi/components/schemas/transactions/OnChainTransaction.yaml b/openapi/components/schemas/transactions/OnChainTransaction.yaml index e3baa4655..12eeb5ea7 100644 --- a/openapi/components/schemas/transactions/OnChainTransaction.yaml +++ b/openapi/components/schemas/transactions/OnChainTransaction.yaml @@ -9,4 +9,4 @@ properties: example: 'h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx' network: $ref: ../crypto/CryptoNetwork.yaml - description: Blockchain network (incl. environment) the transaction settled on. + description: Blockchain network the transaction settled on (mainnet vs test network is determined by your platform environment). diff --git a/openapi/webhooks/incoming-payment.yaml b/openapi/webhooks/incoming-payment.yaml index 2570fe896..8079a41f7 100644 --- a/openapi/webhooks/incoming-payment.yaml +++ b/openapi/webhooks/incoming-payment.yaml @@ -149,7 +149,7 @@ post: currency: USDC onChainTransaction: transactionHash: 7RJWhvQBQPEjJmki5fhBboGBWRJhmcFkMvrr4Fu3tMSJ5EdynMEiYSyiWAH9GpcbHpeUzeSQF9ZY6q4x8AhBskUf - network: SOLANA_MAINNET + network: SOLANA destination: destinationType: ACCOUNT accountId: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965 diff --git a/openapi/webhooks/outgoing-payment.yaml b/openapi/webhooks/outgoing-payment.yaml index 6cb3034b4..219a17db2 100644 --- a/openapi/webhooks/outgoing-payment.yaml +++ b/openapi/webhooks/outgoing-payment.yaml @@ -107,7 +107,7 @@ post: accountId: ExternalAccount:c34dcbd6-dced-4ec4-b756-3c3a9ea3d789 onChainTransaction: transactionHash: h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx - network: SOLANA_MAINNET + network: SOLANA customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: 18d3e5f7b4a9c2 sentAmount: