What's changing?

The Kraken API is being overhauled to add a more structured representation of monetary amounts in all input and output types.

New fields will be added for monetary amounts to allow API consumers to use a more structured format. Adding the new fields is a purely additive, backwards compatible change.

Existing input and output fields which represent monetary amounts are being deprecated, and will eventually be removed.

This an interface-only change to how Kraken represents monetary amounts over the API, and does not affect how Kraken operates on the monetary values.

During the deprecation window, existing queries will continue to work, and a migration path will be provided for every field.

When is this change being made?

The new types and fields are being introduced by the end of 2026.

Deprecation windows for existing fields are a year from the introduction of the new field by default.

Why is this change being made?

Today, a monetary amount in Kraken’s API is a bare integer in the smallest currency denomination (e.g. 314 for £3.14), with the currency itself being implicit based on the Kraken instance.

This representation can be ambiguous: ISO 4217 doesn't use the same number of decimal places everywhere (there are 0 for JPY, and 4 for CLF), so "smallest denomination" means something different depending on currency.

The new types makes both the currency and the scale explicit in every response, and give us the space to add further representations of the same amount in the future.

Scope

We will be migrating ~300 monetary fields being across our schema. For each field, we will add a replacement version that uses a more structured representation and deprecate the existing field (which is a backwards-compatible change).

Removal will happen later after clients have migrated to the new fields.

We will post a follow-up announcement listing all fields for reference when the replacement fields have been added.

New Fields

For every monetary field xAmount in the API, we're adding a sibling field xAmountDetails with a structured money object. The existing xAmount field is being deprecated, and will eventually be removed.

In all cases, there will be a direct replacement for queries which currently use xAmount.

New Types

To attach to the xAmountDetails fields, we are adding 3 new types (2 output and 1 input).

The Money type

The Money type is an output type for representing monetary amounts which are whole amounts of the currencies’ minor unit (e.g. £3.14 or 211¥).

Details of the type are as follows:

scalar BigInt   # Unbounded integer; serialised as a JSON number.
scalar Decimal  # Arbitrary-precision decimal; serialised as a JSON string.

type Money {
  """
  Full amount in the currency's smallest denomination (e.g. pence for GBP,
  cents for USD). Example: £3.14 is represented as 314.
  """
  amountAsMinorUnits: BigInt!

  """
  The amount represented as an ISO 20022 structured value.
  Example: £3.14 is represented as { amount: "3.14", currency: "GBP" }.
  """
  amountAsISO20022: ISO20022MoneyAmount!

  """
  Details about the currency of this amount.
  """
  currencyDetails: CurrencyDetails!
}

type ISO20022MoneyAmount {
  amount: Decimal!    # e.g. "3.14"
  currency: String!   # e.g. "GBP"
}

type CurrencyDetails {
  iso4217CurrencyCode: String!  # e.g. "GBP"
}

TheFractionalMoney type

The FractionalMoney type is an output type for representing monetary amounts which are able to be fractional amounts of the currencies’ minor unit (e.g. 45.6p or 211.5¥).

Details of the type are as follows:

scalar Decimal  # Arbitrary-precision decimal; serialised as a JSON string.

type FractionalMoney {
  """
  Full amount in the currency's smallest denomination (e.g. pence for GBP,
  cents for USD). Example: £3.145 is represented as 314.5.
  """
  amountAsMinorUnits: Decimal!

  """
  Details about the currency of this amount.
  """
  currencyDetails: CurrencyDetails!
}

type CurrencyDetails {
  iso4217CurrencyCode: String!  # e.g. "GBP"
}

The MoneyInput type

The MoneyInput type is an input type for submitting monetary amounts which are whole amounts of the currencies’ minor unit (e.g. £1.23 or 64¥).

Details of the type are as follows:

scalar BigInt   # Unbounded integer; serialised as a JSON number.
scalar Decimal  # Arbitrary-precision decimal; serialised as a JSON string.

input MinorUnitAmountInput {
  """
  The amount of money being provided as an integer amount of minor units, e.g 314.
  """
  amount: BigInt!
   
  """
  The ISO4217 currency code to use for this amount of money.
  
  If this is omitted, then the default currency code for the instance will be used.
  """
  iso4217CurrencyCode: String
}

input ISO20022AmountInput {
  """
  The amount of money being provided as an ISO20022 formatted decimal, e.g "3.14".
  """
  amount: Decimal!
   
  """
  The ISO4217 currency code to use for this amount of money.
  
  If this is omitted, then the default currency code for the instance will be used.
  """
  currency: String
}

input MoneyInput @oneOf {
  """
  Full amount in the currency's smallest denomination (e.g. pence, cents, yen).
  
  Example: £3.14 will be represented as {"amount": 314, "iso4217CurrencyCode": "GBP"}.
  .
  """
  amountAsMinorUnits: MinorUnitAmountInput
    
  """
  Full amount in the ISO 20022 amount/currency form.

  Example: £3.14 will be represented as {"amount": "3.14", "currency": "GBP"}.
  """
  amountAsISO20022: ISO20022AmountInput
}

Note that Kraken does not need an equivalent input type for FractionalMoney for now, as no mutations accept sub-minor unit input, but if this changes in the future one will be added.

Migration advice

For existing queries that access an xAmount field, xAmountDetails.amountAsMinorUnits is a drop-in replacement.

Example: AccountChargeType

Before:

query {
  accountCharge(id: "AC-123") {
    netAmount
    grossAmount
  }
}

{
  "data": {
    "accountCharge": {
      "netAmount": 1234,
      "grossAmount": 1500
    }
  }
}

After:

query {
  accountCharge(id: "AC-123") {
    netAmountDetails { amountAsMinorUnits }
    grossAmountDetails { amountAsMinorUnits }
  }
}

{
  "data": {
    "accountCharge": {
      "netAmountDetails": { "amountAsMinorUnits": 1234 },
      "grossAmountDetails": { "amountAsMinorUnits": 1500 }
    }
  }
}

Extra technical details

Query complexity

Each xAmountDetails { amountAsMinorUnits } costs 2 complexity points against your query, versus 1 for the old xAmount field.

Reading the full amountAsISO20022 representation costs up to 4, and reading all three representations at once costs up to 7.

Our complexity ceiling per request is 200, so this is not expected to be an issue for typical queries.

If you query a large number of amount fields per request and have a query near that ceiling today, please get in touch.