From bd9d13bf18211452701b78ba8a4793fecd992c5b Mon Sep 17 00:00:00 2001 From: Jack Latourette Date: Mon, 3 Aug 2026 16:42:38 -0700 Subject: [PATCH 1/3] feat(quotes): allow a per-transaction platform fee override on POST /quotes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Optional platformFeeOverride on QuoteRequest: when present it replaces all platform fees that would otherwise apply — no standing fee config required and no cap relative to one. platformFixedFee and platformVariableFeeBps are both required within the object; negatives are rejected at schema level. USD source currency only today (including same-currency USD transfers); the fixed fee currency must equal the quote's source currency (AT-6193). Co-Authored-By: Claude Fable 5 --- mintlify/openapi.yaml | 36 ++++++++++++++++ openapi.yaml | 36 ++++++++++++++++ .../schemas/quotes/PlatformFeeOverride.yaml | 43 +++++++++++++++++++ .../schemas/quotes/QuoteRequest.yaml | 2 + 4 files changed, 117 insertions(+) create mode 100644 openapi/components/schemas/quotes/PlatformFeeOverride.yaml diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 2a1df65c4..b41153830 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -21804,6 +21804,40 @@ components: - SENDING - RECEIVING description: The side of the quote which should be locked and specified in the `lockedCurrencyAmount`. For example, if I want to send exactly $5 MXN from my wallet, I would set this to "sending", and the `lockedCurrencyAmount` to 500 (in cents). If I want the receiver to receive exactly $10 USD, I would set this to "receiving" and the `lockedCurrencyAmount` to 10000 (in cents). + PlatformFeeOverride: + type: object + description: Overrides the platform fee for this transaction. When present, it replaces all platform fees that would otherwise apply to the transaction — no standing fee config is required. Only supported when the quote's source currency is USD today; the fixed fee must be denominated in the source currency. + required: + - platformFixedFee + - platformVariableFeeBps + properties: + platformFixedFee: + type: object + description: Fixed fee charged for this transaction. + required: + - amount + - currency + properties: + amount: + type: integer + format: int64 + minimum: 0 + description: Fee amount in the smallest unit of the fixed fee's `currency` (e.g., cents for USD). + example: 50 + currency: + type: string + description: Three-letter currency code (ISO 4217) the fixed fee is denominated in. Must equal the quote's source currency (USD today). + example: USD + platformVariableFeeBps: + type: integer + minimum: 0 + description: Variable fee in basis points (1 bps = 0.01%) to apply to the transaction's source-currency amount. + example: 30 + example: + platformFixedFee: + amount: 50 + currency: USD + platformVariableFeeBps: 30 QuoteRequest: type: object required: @@ -21849,6 +21883,8 @@ components: example: '12345' purposeOfPayment: $ref: '#/components/schemas/PurposeOfPayment' + platformFeeOverride: + $ref: '#/components/schemas/PlatformFeeOverride' scaFactor: $ref: '#/components/schemas/ScaFactor' description: Optional preferred factor for a Strong Customer Authentication challenge issued at quote creation. Only relevant for a realtime-funding source in a region where SCA is required (e.g. EU); ignored otherwise. Valid values are `SMS_OTP` (default) and `PASSKEY` — `TOTP` cannot carry the required dynamic linking and is rejected. When the quote is returned in `PENDING_AUTHORIZATION`, authorize it via `POST /quotes/{quoteId}/authorize`. diff --git a/openapi.yaml b/openapi.yaml index 2a1df65c4..b41153830 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -21804,6 +21804,40 @@ components: - SENDING - RECEIVING description: The side of the quote which should be locked and specified in the `lockedCurrencyAmount`. For example, if I want to send exactly $5 MXN from my wallet, I would set this to "sending", and the `lockedCurrencyAmount` to 500 (in cents). If I want the receiver to receive exactly $10 USD, I would set this to "receiving" and the `lockedCurrencyAmount` to 10000 (in cents). + PlatformFeeOverride: + type: object + description: Overrides the platform fee for this transaction. When present, it replaces all platform fees that would otherwise apply to the transaction — no standing fee config is required. Only supported when the quote's source currency is USD today; the fixed fee must be denominated in the source currency. + required: + - platformFixedFee + - platformVariableFeeBps + properties: + platformFixedFee: + type: object + description: Fixed fee charged for this transaction. + required: + - amount + - currency + properties: + amount: + type: integer + format: int64 + minimum: 0 + description: Fee amount in the smallest unit of the fixed fee's `currency` (e.g., cents for USD). + example: 50 + currency: + type: string + description: Three-letter currency code (ISO 4217) the fixed fee is denominated in. Must equal the quote's source currency (USD today). + example: USD + platformVariableFeeBps: + type: integer + minimum: 0 + description: Variable fee in basis points (1 bps = 0.01%) to apply to the transaction's source-currency amount. + example: 30 + example: + platformFixedFee: + amount: 50 + currency: USD + platformVariableFeeBps: 30 QuoteRequest: type: object required: @@ -21849,6 +21883,8 @@ components: example: '12345' purposeOfPayment: $ref: '#/components/schemas/PurposeOfPayment' + platformFeeOverride: + $ref: '#/components/schemas/PlatformFeeOverride' scaFactor: $ref: '#/components/schemas/ScaFactor' description: Optional preferred factor for a Strong Customer Authentication challenge issued at quote creation. Only relevant for a realtime-funding source in a region where SCA is required (e.g. EU); ignored otherwise. Valid values are `SMS_OTP` (default) and `PASSKEY` — `TOTP` cannot carry the required dynamic linking and is rejected. When the quote is returned in `PENDING_AUTHORIZATION`, authorize it via `POST /quotes/{quoteId}/authorize`. diff --git a/openapi/components/schemas/quotes/PlatformFeeOverride.yaml b/openapi/components/schemas/quotes/PlatformFeeOverride.yaml new file mode 100644 index 000000000..30b859001 --- /dev/null +++ b/openapi/components/schemas/quotes/PlatformFeeOverride.yaml @@ -0,0 +1,43 @@ +type: object +description: >- + Overrides the platform fee for this transaction. When present, it replaces + all platform fees that would otherwise apply to the transaction — no standing + fee config is required. Only supported when the quote's source currency is + USD today; the fixed fee must be denominated in the source currency. +required: + - platformFixedFee + - platformVariableFeeBps +properties: + platformFixedFee: + type: object + description: Fixed fee charged for this transaction. + required: + - amount + - currency + properties: + amount: + type: integer + format: int64 + minimum: 0 + description: >- + Fee amount in the smallest unit of the fixed fee's `currency` + (e.g., cents for USD). + example: 50 + currency: + type: string + description: >- + Three-letter currency code (ISO 4217) the fixed fee is denominated + in. Must equal the quote's source currency (USD today). + example: USD + platformVariableFeeBps: + type: integer + minimum: 0 + description: >- + Variable fee in basis points (1 bps = 0.01%) to apply to the + transaction's source-currency amount. + example: 30 +example: + platformFixedFee: + amount: 50 + currency: USD + platformVariableFeeBps: 30 diff --git a/openapi/components/schemas/quotes/QuoteRequest.yaml b/openapi/components/schemas/quotes/QuoteRequest.yaml index 545d701d8..c4f658c11 100644 --- a/openapi/components/schemas/quotes/QuoteRequest.yaml +++ b/openapi/components/schemas/quotes/QuoteRequest.yaml @@ -67,6 +67,8 @@ properties: example: '12345' purposeOfPayment: $ref: ./PurposeOfPayment.yaml + platformFeeOverride: + $ref: ./PlatformFeeOverride.yaml scaFactor: $ref: ../sca/ScaFactor.yaml description: >- From 3313c2336fc4b8b7159037978c133d18f2ab098f Mon Sep 17 00:00:00 2001 From: Jack Latourette Date: Wed, 5 Aug 2026 15:28:39 -0700 Subject: [PATCH 2/3] Scope platformFeeOverride docs to platform-authenticated POST /quotes Agent tokens carry no fee-control permission, so note that the field must be omitted on agent-authenticated requests like POST /agents/me/quotes. Co-Authored-By: Claude Fable 5 --- mintlify/openapi.yaml | 4 +++- openapi.yaml | 4 +++- openapi/components/schemas/quotes/PlatformFeeOverride.yaml | 4 ++++ 3 files changed, 10 insertions(+), 2 deletions(-) diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index b41153830..517456603 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -21806,7 +21806,9 @@ components: description: The side of the quote which should be locked and specified in the `lockedCurrencyAmount`. For example, if I want to send exactly $5 MXN from my wallet, I would set this to "sending", and the `lockedCurrencyAmount` to 500 (in cents). If I want the receiver to receive exactly $10 USD, I would set this to "receiving" and the `lockedCurrencyAmount` to 10000 (in cents). PlatformFeeOverride: type: object - description: Overrides the platform fee for this transaction. When present, it replaces all platform fees that would otherwise apply to the transaction — no standing fee config is required. Only supported when the quote's source currency is USD today; the fixed fee must be denominated in the source currency. + description: |- + Overrides the platform fee for this transaction. When present, it replaces all platform fees that would otherwise apply to the transaction — no standing fee config is required. Only supported when the quote's source currency is USD today; the fixed fee must be denominated in the source currency. + Only honored on platform-authenticated requests to `POST /quotes`. Agent tokens carry no fee-control permission, so this field must be omitted on agent-authenticated requests such as `POST /agents/me/quotes`. required: - platformFixedFee - platformVariableFeeBps diff --git a/openapi.yaml b/openapi.yaml index b41153830..517456603 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -21806,7 +21806,9 @@ components: description: The side of the quote which should be locked and specified in the `lockedCurrencyAmount`. For example, if I want to send exactly $5 MXN from my wallet, I would set this to "sending", and the `lockedCurrencyAmount` to 500 (in cents). If I want the receiver to receive exactly $10 USD, I would set this to "receiving" and the `lockedCurrencyAmount` to 10000 (in cents). PlatformFeeOverride: type: object - description: Overrides the platform fee for this transaction. When present, it replaces all platform fees that would otherwise apply to the transaction — no standing fee config is required. Only supported when the quote's source currency is USD today; the fixed fee must be denominated in the source currency. + description: |- + Overrides the platform fee for this transaction. When present, it replaces all platform fees that would otherwise apply to the transaction — no standing fee config is required. Only supported when the quote's source currency is USD today; the fixed fee must be denominated in the source currency. + Only honored on platform-authenticated requests to `POST /quotes`. Agent tokens carry no fee-control permission, so this field must be omitted on agent-authenticated requests such as `POST /agents/me/quotes`. required: - platformFixedFee - platformVariableFeeBps diff --git a/openapi/components/schemas/quotes/PlatformFeeOverride.yaml b/openapi/components/schemas/quotes/PlatformFeeOverride.yaml index 30b859001..4b27ad6db 100644 --- a/openapi/components/schemas/quotes/PlatformFeeOverride.yaml +++ b/openapi/components/schemas/quotes/PlatformFeeOverride.yaml @@ -4,6 +4,10 @@ description: >- all platform fees that would otherwise apply to the transaction — no standing fee config is required. Only supported when the quote's source currency is USD today; the fixed fee must be denominated in the source currency. + + Only honored on platform-authenticated requests to `POST /quotes`. Agent + tokens carry no fee-control permission, so this field must be omitted on + agent-authenticated requests such as `POST /agents/me/quotes`. required: - platformFixedFee - platformVariableFeeBps From 7a9c7e095688988479b6bd77339a245e177669dd Mon Sep 17 00:00:00 2001 From: Jack Latourette Date: Wed, 5 Aug 2026 17:02:25 -0700 Subject: [PATCH 3/3] Extract shared FixedFee schema, reword the override description, cap platformVariableFeeBps at 10000 Co-Authored-By: Claude Fable 5 --- mintlify/openapi.yaml | 55 ++++++++----------- openapi.yaml | 55 ++++++++----------- .../components/schemas/config/FeeConfig.yaml | 22 +------- .../components/schemas/config/FixedFee.yaml | 21 +++++++ .../schemas/quotes/PlatformFeeOverride.yaml | 33 +++-------- 5 files changed, 75 insertions(+), 111 deletions(-) create mode 100644 openapi/components/schemas/config/FixedFee.yaml diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 517456603..ea62cdcf4 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -11529,6 +11529,23 @@ components: - `CROSS_CURRENCY_TRANSACTION` — fee charged on a cross-currency Grid transaction (source currency differs from destination currency). example: CROSS_CURRENCY_TRANSACTION + FixedFee: + type: object + description: Fixed fee charged per transaction. + required: + - amount + - currency + properties: + amount: + type: integer + format: int64 + minimum: 0 + description: Fee amount in the smallest unit of the fixed fee's `currency` (e.g., cents for USD). + example: 100 + currency: + type: string + description: Three-letter currency code (ISO 4217) the fixed fee is denominated in. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.) + example: USD FeeConfig: type: object description: A platform-configured fee collected by Grid and settled to the platform internal account. There can be at most one fee config for a given fee type and source currency pair. The fee will apply to all transactions of the fee type that originate in the source currency. @@ -11546,22 +11563,7 @@ components: description: Variable fee in basis points (1 bps = 0.01%) to apply to a transaction's source-currency amount. example: 30 fixedFee: - type: object - description: Fixed fee charged per transaction. - properties: - amount: - type: integer - format: int64 - minimum: 0 - description: Fee amount in the smallest unit of the fixed fee's `currency` (e.g., cents for USD). - example: 100 - currency: - type: string - description: Three-letter currency code (ISO 4217) the fixed fee is denominated in. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.) - example: USD - required: - - amount - - currency + $ref: '#/components/schemas/FixedFee' required: - feeType - sourceCurrency @@ -21807,32 +21809,19 @@ components: PlatformFeeOverride: type: object description: |- - Overrides the platform fee for this transaction. When present, it replaces all platform fees that would otherwise apply to the transaction — no standing fee config is required. Only supported when the quote's source currency is USD today; the fixed fee must be denominated in the source currency. + Overrides the platform-collected fee for this transaction. When present, it replaces any configured platform-collected fees that would otherwise apply to the transaction. Currently only supported when the quote's source currency is USD; the fixed fee must be denominated in the source currency. Only honored on platform-authenticated requests to `POST /quotes`. Agent tokens carry no fee-control permission, so this field must be omitted on agent-authenticated requests such as `POST /agents/me/quotes`. required: - platformFixedFee - platformVariableFeeBps properties: platformFixedFee: - type: object - description: Fixed fee charged for this transaction. - required: - - amount - - currency - properties: - amount: - type: integer - format: int64 - minimum: 0 - description: Fee amount in the smallest unit of the fixed fee's `currency` (e.g., cents for USD). - example: 50 - currency: - type: string - description: Three-letter currency code (ISO 4217) the fixed fee is denominated in. Must equal the quote's source currency (USD today). - example: USD + $ref: '#/components/schemas/FixedFee' + description: Fixed fee charged for this transaction. Must be denominated in the quote's source currency (USD today). platformVariableFeeBps: type: integer minimum: 0 + maximum: 10000 description: Variable fee in basis points (1 bps = 0.01%) to apply to the transaction's source-currency amount. example: 30 example: diff --git a/openapi.yaml b/openapi.yaml index 517456603..ea62cdcf4 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -11529,6 +11529,23 @@ components: - `CROSS_CURRENCY_TRANSACTION` — fee charged on a cross-currency Grid transaction (source currency differs from destination currency). example: CROSS_CURRENCY_TRANSACTION + FixedFee: + type: object + description: Fixed fee charged per transaction. + required: + - amount + - currency + properties: + amount: + type: integer + format: int64 + minimum: 0 + description: Fee amount in the smallest unit of the fixed fee's `currency` (e.g., cents for USD). + example: 100 + currency: + type: string + description: Three-letter currency code (ISO 4217) the fixed fee is denominated in. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.) + example: USD FeeConfig: type: object description: A platform-configured fee collected by Grid and settled to the platform internal account. There can be at most one fee config for a given fee type and source currency pair. The fee will apply to all transactions of the fee type that originate in the source currency. @@ -11546,22 +11563,7 @@ components: description: Variable fee in basis points (1 bps = 0.01%) to apply to a transaction's source-currency amount. example: 30 fixedFee: - type: object - description: Fixed fee charged per transaction. - properties: - amount: - type: integer - format: int64 - minimum: 0 - description: Fee amount in the smallest unit of the fixed fee's `currency` (e.g., cents for USD). - example: 100 - currency: - type: string - description: Three-letter currency code (ISO 4217) the fixed fee is denominated in. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.) - example: USD - required: - - amount - - currency + $ref: '#/components/schemas/FixedFee' required: - feeType - sourceCurrency @@ -21807,32 +21809,19 @@ components: PlatformFeeOverride: type: object description: |- - Overrides the platform fee for this transaction. When present, it replaces all platform fees that would otherwise apply to the transaction — no standing fee config is required. Only supported when the quote's source currency is USD today; the fixed fee must be denominated in the source currency. + Overrides the platform-collected fee for this transaction. When present, it replaces any configured platform-collected fees that would otherwise apply to the transaction. Currently only supported when the quote's source currency is USD; the fixed fee must be denominated in the source currency. Only honored on platform-authenticated requests to `POST /quotes`. Agent tokens carry no fee-control permission, so this field must be omitted on agent-authenticated requests such as `POST /agents/me/quotes`. required: - platformFixedFee - platformVariableFeeBps properties: platformFixedFee: - type: object - description: Fixed fee charged for this transaction. - required: - - amount - - currency - properties: - amount: - type: integer - format: int64 - minimum: 0 - description: Fee amount in the smallest unit of the fixed fee's `currency` (e.g., cents for USD). - example: 50 - currency: - type: string - description: Three-letter currency code (ISO 4217) the fixed fee is denominated in. Must equal the quote's source currency (USD today). - example: USD + $ref: '#/components/schemas/FixedFee' + description: Fixed fee charged for this transaction. Must be denominated in the quote's source currency (USD today). platformVariableFeeBps: type: integer minimum: 0 + maximum: 10000 description: Variable fee in basis points (1 bps = 0.01%) to apply to the transaction's source-currency amount. example: 30 example: diff --git a/openapi/components/schemas/config/FeeConfig.yaml b/openapi/components/schemas/config/FeeConfig.yaml index 833923b9d..5a9064345 100644 --- a/openapi/components/schemas/config/FeeConfig.yaml +++ b/openapi/components/schemas/config/FeeConfig.yaml @@ -18,27 +18,7 @@ properties: Variable fee in basis points (1 bps = 0.01%) to apply to a transaction's source-currency amount. example: 30 fixedFee: - type: object - description: Fixed fee charged per transaction. - properties: - amount: - type: integer - format: int64 - minimum: 0 - description: >- - Fee amount in the smallest unit of the fixed fee's `currency` - (e.g., cents for USD). - example: 100 - currency: - type: string - description: >- - Three-letter currency code (ISO 4217) the fixed fee is denominated - in. Some cryptocurrencies may use their own ticker symbols (e.g. - "BTC" for Bitcoin, "USDC" for USDC, etc.) - example: USD - required: - - amount - - currency + $ref: ./FixedFee.yaml required: - feeType - sourceCurrency diff --git a/openapi/components/schemas/config/FixedFee.yaml b/openapi/components/schemas/config/FixedFee.yaml new file mode 100644 index 000000000..cc3f9f86c --- /dev/null +++ b/openapi/components/schemas/config/FixedFee.yaml @@ -0,0 +1,21 @@ +type: object +description: Fixed fee charged per transaction. +required: + - amount + - currency +properties: + amount: + type: integer + format: int64 + minimum: 0 + description: >- + Fee amount in the smallest unit of the fixed fee's `currency` + (e.g., cents for USD). + example: 100 + currency: + type: string + description: >- + Three-letter currency code (ISO 4217) the fixed fee is denominated + in. Some cryptocurrencies may use their own ticker symbols (e.g. + "BTC" for Bitcoin, "USDC" for USDC, etc.) + example: USD diff --git a/openapi/components/schemas/quotes/PlatformFeeOverride.yaml b/openapi/components/schemas/quotes/PlatformFeeOverride.yaml index 4b27ad6db..58f43c5d2 100644 --- a/openapi/components/schemas/quotes/PlatformFeeOverride.yaml +++ b/openapi/components/schemas/quotes/PlatformFeeOverride.yaml @@ -1,9 +1,9 @@ type: object description: >- - Overrides the platform fee for this transaction. When present, it replaces - all platform fees that would otherwise apply to the transaction — no standing - fee config is required. Only supported when the quote's source currency is - USD today; the fixed fee must be denominated in the source currency. + Overrides the platform-collected fee for this transaction. When present, + it replaces any configured platform-collected fees that would otherwise + apply to the transaction. Currently only supported when the quote's source + currency is USD; the fixed fee must be denominated in the source currency. Only honored on platform-authenticated requests to `POST /quotes`. Agent tokens carry no fee-control permission, so this field must be omitted on @@ -13,29 +13,14 @@ required: - platformVariableFeeBps properties: platformFixedFee: - type: object - description: Fixed fee charged for this transaction. - required: - - amount - - currency - properties: - amount: - type: integer - format: int64 - minimum: 0 - description: >- - Fee amount in the smallest unit of the fixed fee's `currency` - (e.g., cents for USD). - example: 50 - currency: - type: string - description: >- - Three-letter currency code (ISO 4217) the fixed fee is denominated - in. Must equal the quote's source currency (USD today). - example: USD + $ref: ../config/FixedFee.yaml + description: >- + Fixed fee charged for this transaction. Must be denominated in the + quote's source currency (USD today). platformVariableFeeBps: type: integer minimum: 0 + maximum: 10000 description: >- Variable fee in basis points (1 bps = 0.01%) to apply to the transaction's source-currency amount.