getMaxDepositAmountread-only

Query the maximum amount that can currently be deposited in the given currency.

Request:

The request body must be a GetMaxDepositAmountRequest object. When depositPaytoUri is omitted, wire-method eligibility, account restrictions and wire fees cannot be reflected in the response.

Response:

On success, the result is a GetMaxDepositAmountResponse object.

Details:

The result distinguishes the maximum that can be deposited immediately (material) from the maximum that also includes the expected outputs of pending refresh operations (available). exchangeDiagnostics gives, for every ready same-currency exchange, the per-exchange maximums and the reasons why the exchange cannot serve the deposit.

interface GetMaxDepositAmountRequest {
  // Currency to deposit.
  currency: string;

  // Target bank account to deposit into.  When omitted, wire-method
  // eligibility, account restrictions and wire fees cannot be
  // reflected in the response.
  depositPaytoUri?: string;

  // Restrict the deposit to a certain scope.
  restrictScope?: ScopeInfo;
}

interface GetMaxDepositAmountResponse {
  // Maximum that can be deposited immediately.
  material: DepositMaximum;

  // Maximum including expected outputs of pending refresh
  // operations.
  available: DepositMaximum;

  // Eligibility and maximum amounts for every ready same-currency
  // exchange.
  exchangeDiagnostics: Record<string, DepositExchangeDiagnostics>;
}

// Maximum amounts and fees for one coherent deposit coin selection.
interface DepositMaximum {
  // Gross target amount passed to checkDeposit or
  // createDepositGroup.
  instructedAmount: AmountString;

  // Total balance effect on the wallet: instructed amount plus fees
  // paid by the customer and the cost of refreshing any change.
  effectiveAmount: AmountString;

  // Amount expected to reach the destination account: instructed
  // amount minus fees covered by the counterparty.
  rawAmount: AmountString;

  // Total fees incurred by this deposit selection.
  fees: DepositGroupFees;
}

interface DepositExchangeDiagnostics {
  // Maximum that can be deposited immediately.
  material: DepositMaximum;

  // Maximum including expected outputs of pending refresh
  // operations.
  available: DepositMaximum;

  // Eligibility failures, in deterministic evaluation order.
  reasons: DepositEligibilityReason[];
}

// Reason why a ready, same-currency exchange cannot serve a deposit.
type DepositEligibilityReason =
  | { type: "direct-deposit-disabled" }
  | { type: "scope-restricted"; scopeInfo: ScopeInfo }
  | { type: "wire-method-unsupported"; wireMethod: string }
  | { type: "wire-fee-unavailable"; wireMethod: string }
  | {
      type: "deposit-account-restricted";
      wireMethod: string;
      accountRestrictions: Record<string, AccountRestriction[]>;
    };

type DepositEligibilityReasonType =
  "direct-deposit-disabled"
  | "scope-restricted"
  | "wire-method-unsupported"
  | "wire-fee-unavailable"
  | "deposit-account-restricted";

type AccountRestriction =
  | RegexAccountRestriction
  | DenyAllAccountRestriction;

// Accounts interacting with this type of account restriction must
// have a payto://-URI matching the given regex.
interface RegexAccountRestriction {
  type: "regex";

  // Regular expression that the payto://-URI of the partner account
  // must follow (posix-egrep, without support for character
  // classes, GNU extensions, back-references or intervals).
  payto_regex: string;

  // Hint for a human to understand the restriction.
  human_hint: string;

  // Map from IETF BCP 47 language tags to localized human hints.
  human_hint_i18n?: InternationalizedString;
}

interface DenyAllAccountRestriction {
  type: "deny";
}