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.

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

Update Merchant Fees

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

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

This configuration adds a 1% merchant fee, a fixed 0.5 fee, and a minimum merchant fee of 2 USD 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": "USD",
  "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": "USD",
    "output_currency": "USD",
    "direction": "ONRAMP",
    "payment_method": "ACH",
    "fee_op_type": "add",
    "fixed_fee": 0.25,
    "minimum_fee": 1,
    "minimum_fee_currency": "USD"
  }
]

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.

Because fee rules are stored per payment rail, include payment_method to remove a single rail-scoped rule. Omit it and every rail variant matching the other fields is removed.

{
  "user_uuid": "ccb567b4-c483-4ba6-ab8c-9b7a471f11db",
  "input_currency": "USD",
  "output_currency": "USD",
  "direction": "ONRAMP",
  "payment_method": "ACH"
}

Retrieve User Fee Overrides

Use GET /stablecoin/user/fees to read back the custom fee rules currently configured for a user. Pass the user_uuid as a query parameter, and optionally narrow the result with input_currency, output_currency, and direction.

GET /stablecoin/user/fees?user_uuid=ccb567b4-c483-4ba6-ab8c-9b7a471f11db&direction=ONRAMP

[
  {
    "uuid": "0f1c6c4e-8b4a-4f0e-9a1e-4d2f7b3c9a11",
    "client_uuid": "ccb567b4-c483-4ba6-ab8c-9b7a471f11db",
    "client_type": "INDIVIDUAL",
    "input_currency": "USD",
    "output_currency": "USD",
    "direction": "ONRAMP",
    "percentage_fee": "0.005",
    "fee_op_type": "add",
    "minimum_fee": 1,
    "minimum_fee_currency": "USD",
    "fixed_fee": "0.25",
    "payment_method": "ACH"
  }
]

Results are ordered from most specific to least specific, matching the precedence the pricing engine applies when it resolves a fee. A user with no overrides returns an empty array.

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": "USD",
    "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.

As with user overrides, include payment_method to remove a single rail-scoped rule, or omit it to remove every rail variant matching the other fields.

Retrieve Corporate Fee Overrides

Use GET /stablecoin/corporate/fees to read back the custom fee rules currently configured for a corporate. Pass the company_uuid as a query parameter, and optionally narrow the result with input_currency, output_currency, and direction.

GET /stablecoin/corporate/fees?company_uuid=ccb567b4-c483-4ba6-ab8c-9b7a471f11db&direction=OFFRAMP

The response uses the same shape as the user fee overrides, with client_type set to COMPANY. A corporate with no overrides returns an empty array.