Managing Fees and Commissions

Overview

Bakkt applies a base fee to stablecoin transactions. You can configure merchant fees that are added to, or subtracted from, that base fee for matching transactions.

Use fee configuration when you need merchant-wide pricing, user-specific pricing, or corporate-specific pricing.

Fee Configuration

Merchant fees use decimal percentage values:

0.01 is a 1% fee.
0.005 is a 0.5% fee.

The fee value must be between 0 and 1. Fee configuration uses ONRAMP and OFFRAMP for direction.

Field	Description
`fee`	Percentage fee in decimal format. Required when you update a fee configuration.
`direction`	Transaction direction: `ONRAMP` or `OFFRAMP`. Required when you update a fee configuration.
`fee_op_type`	Fee operation: `add` or `subtract`. Required when you update a fee configuration.
`input_currency`	Currency entering the transaction. Send `null` only for an `OFFRAMP` rule with a specific `output_currency`.
`output_currency`	Currency leaving the transaction. Send `null` only for an `ONRAMP` rule with a specific `input_currency`.
`payment_method`	Optional payment rail, such as `SEPA`, `SEPA_INSTANT`, `FASTER_PAYMENTS`, `ACH`, `WIRE`, or `PIX`. Omit it or set it to `null` for a catch-all rule.
`fixed_fee`	Fixed amount added on top of the percentage fee.
`minimum_fee`	Fixed minimum merchant fee amount.
`minimum_fee_currency`	Currency for `minimum_fee`. Required when `minimum_fee` is provided.

For stablecoin configurations, fiat currency codes may represent the token family for a direction. For example, an OFFRAMP input currency of USD can apply to USD-backed stablecoins, and an ONRAMP output currency of USD can apply to USD-backed stablecoins.

Fee Operation Types

Use add to increase the merchant fee applied to matching transactions.

Use subtract to reduce the total fee applied to matching transactions, including the merchant fee and Bakkt base fee. Confirm your commercial setup with Bakkt before using subtract in production.

Wildcard Rules

Send null to create a wildcard rule for one currency side:

For ONRAMP, output_currency can be null only when input_currency is specific.
For OFFRAMP, input_currency can be null only when output_currency is specific.
input_currency and output_currency cannot both be null in the same fee rule.

Use payment_method for rail-specific pricing. If a transaction has a matching rule for its payment method, Bakkt applies that rule. If not, Bakkt falls back to the matching rule where payment_method is omitted or null. Unsupported payment method values return a validation error.

Configuration Levels

Merchant-wide fees apply by default for matching transaction parameters. User and corporate fee configurations let you set custom pricing for a specific user_uuid or company_uuid.

User and corporate updates accept an array of fee configuration objects. This lets you update multiple fee rules in one request.

Endpoints

Action	Endpoint	Description
Update merchant fees	`PATCH /stablecoin/merchant/fees`	Updates merchant-wide fee configuration.
Retrieve merchant fees	`GET /stablecoin/merchant/fees`	Returns merchant-wide fee configurations.
Retrieve transaction fees	`GET /stablecoin/merchant/fees/transactions`	Returns transaction fees for a required `startDate` and `endDate` range.
Update user fee overrides	`PATCH /stablecoin/user/fees`	Sets custom fee configurations for users.
Remove user fee overrides	`DELETE /stablecoin/user/fees`	Removes custom user fee configurations.
Update corporate fee overrides	`PATCH /stablecoin/corporate/fees`	Sets custom fee configurations for corporates.
Remove corporate fee overrides	`DELETE /stablecoin/corporate/fees`	Removes custom corporate fee configurations.

Update Merchant Fees

Use PATCH /stablecoin/merchant/fees to create or update a merchant-wide fee rule.

{
  "fee": 0.01,
  "input_currency": "EUR",
  "output_currency": "USD",
  "direction": "ONRAMP",
  "payment_method": "SEPA_INSTANT",
  "fee_op_type": "add",
  "fixed_fee": 0.5,
  "minimum_fee": 2,
  "minimum_fee_currency": "EUR"
}

This configuration adds a 1% merchant fee, a fixed 0.5 fee, and a minimum merchant fee of 2 EUR for matching on-ramp transactions.

Omit payment_method or set it to null to create a catch-all rule for the same currency pair and direction.

{
  "fee": 0.005,
  "input_currency": "EUR",
  "output_currency": "USD",
  "direction": "ONRAMP",
  "payment_method": null,
  "fee_op_type": "add"
}

Use a currency wildcard only when the other side of the transaction is specific.

{
  "fee": 0.005,
  "input_currency": "EUR",
  "output_currency": null,
  "direction": "ONRAMP",
  "fee_op_type": "add"
}

Update User Fee Overrides

Use PATCH /stablecoin/user/fees to set custom fee rules for one or more users.

[
  {
    "user_uuid": "ccb567b4-c483-4ba6-ab8c-9b7a471f11db",
    "fee": 0.005,
    "input_currency": "EUR",
    "output_currency": "USD",
    "direction": "ONRAMP",
    "payment_method": "SEPA",
    "fee_op_type": "add",
    "fixed_fee": 0.25,
    "minimum_fee": 1,
    "minimum_fee_currency": "EUR"
  }
]

Remove a user-specific fee configuration with DELETE /stablecoin/user/fees. Include the user_uuid and the same matching fields used by the fee rule you want to remove.

Update Corporate Fee Overrides

Use PATCH /stablecoin/corporate/fees to set custom fee rules for one or more corporates.

[
  {
    "company_uuid": "ccb567b4-c483-4ba6-ab8c-9b7a471f11db",
    "fee": 0.005,
    "input_currency": "USD",
    "output_currency": "EUR",
    "direction": "OFFRAMP",
    "payment_method": "WIRE",
    "fee_op_type": "add",
    "fixed_fee": 0.5,
    "minimum_fee": 1,
    "minimum_fee_currency": "USD"
  }
]

Remove a corporate-specific fee configuration with DELETE /stablecoin/corporate/fees. Include the company_uuid and the same matching fields used by the fee rule you want to remove.