sendManyRoute.ts

import { httpRequest, HttpResponse, httpRoute, optional } from '@api-ts/io-ts-http';
import * as t from 'io-ts';
import { ErrorResponses } from '../../shared/errors';

export const SendManyRequest = {
  /**
   * The key to use for signing the transaction
   */
  source: t.union([t.literal('user'), t.literal('backup')]),
  /**
   * Required for transactions from MPC wallets. Defaults to 'transfer' for TSS wallets if not provided.
   */
  type: t.union([
    t.undefined,
    t.literal('transfer'),
    t.literal('fillNonce'),
    t.literal('acceleration'),
    t.literal('accountSet'),
    t.literal('enabletoken'),
    t.literal('transfertoken'),
    t.literal('trustline'),
  ]),
  /**
   * List of recipient addresses and amounts to send
   */
  recipients: optional(
    t.array(
      t.type({
        /**
         * Destination address
         * @maxLength 250
         * @example "2MvrwRYBAuRtPTiZ5MyKg42Ke55W3fZJfZS"
         */
        address: t.string,
        /**
         * The amount in base units (e.g. satoshis) to send. For doge, only string is allowed.
         * @example "2000000"
         * @pattern ^-?\d+$
         */
        amount: t.union([t.string, t.number]),
      }),
    ),
  ),
  /**
   * Public key of the key used for signing multisig transactions
   * i.e if source is user, this is the user's public key
   * if source is backup, this is the backup key's public key
   */
  pubkey: optional(t.string),

  /**
   * For TSS wallets, this is the common keychain of the wallet,
   * it remains the same whether source is user or backup
   */
  commonKeychain: optional(t.string),

  /**
   * (BTC only) The number of blocks required to confirm a transaction. You can use `numBlocks` to estimate the fee rate by targeting confirmation within a given number of blocks. If both `feeRate` and `numBlocks` are absent, the transaction defaults to 2 blocks for confirmation.
   * Note: The `maxFeeRate` limits the fee rate generated by `numBlocks`.
   * @minimum 2
   * @maximum 1000
   */
  numBlocks: optional(t.number),

  /**
   * Custom fee rate (in base units) per kilobyte (or virtual kilobyte). For example, satoshis per kvByte.
   * If the `feeRate` is less than the minimum required network fee, then the minimum fee applies. For example, 1000 sat/kvByte, a flat 1000 microAlgos, or a flat 10 drops of xrp. For XRP, the actual fee is usually 4.5 times the open ledger fee.
   * Note: The `feeRate` overrides the `maxFeeRate` and `minFeeRate`.
   */
  feeRate: optional(t.number),

  /**
   * (UTXO only) Custom multiplier to the `feeRate`. The resulting fee rate is limited by the `maxFeeRate`. For replace-by-fee (RBF) transactions (that include `rbfTxIds`), the `feeMultiplier` must be greater than 1, since it's an absolute fee multiplier to the transaction being replaced.
   * Note: The `maxFeeRate` limits the fee rate generated by `feeMultiplier`.
   */
  feeMultiplier: optional(t.number),

  /**
   * (BTC only) The maximum fee rate (in base units) per kilobyte (or virtual kilobyte). For example, satoshis per kvByte. The `maxFeeRate` limits the fee rate generated by both `feeMultiplier` and `numBlocks`.
   * Note: The `feeRate` overrides the `maxFeeRate`.
   */
  maxFeeRate: optional(t.number),

  /**
   * The unspent selection for the transaction will only consider unspents with at least this many confirmations to be used as inputs. Does not apply to change outputs unless used in combination with `enforceMinConfirmsForChange`.
   */
  minConfirms: optional(t.number),

  /**
   * When set to true, will enforce minConfirms for change outputs. Defaults to false.
   * @default false
   */
  enforceMinConfirmsForChange: optional(t.boolean),

  /**
   * Specifies the minimum count of good-sized unspents to maintain in the wallet. Change splitting ceases when the wallet has `targetWalletUnspents` good-sized unspents.
   * Note: Wallets that continuously send a high count of transactions will automatically split large change amounts into multiple good-sized change outputs while they have fewer than `targetWalletUnspents` good-sized unspents in their unspent pool. Breaking up large unspents helps to reduce the amount of unconfirmed funds in flight in future transactions, and helps to avoid long chains of unconfirmed transactions. This is especially useful for newly funded wallets or recently refilled send-only wallets.
   * @default 1000
   */
  targetWalletUnspents: optional(t.number),

  /**
   * Optional metadata (only persisted in BitGo) to be applied to the transaction. Use this to add transaction-specific information such as the transaction's purpose or another identifier that you want to reference later. The value is shown in the UI in the transfer listing page.
   * @maxLength 256
   */
  message: optional(t.string),

  /**
   * Ignore unspents smaller than this amount of base units (e.g. satoshis). For doge, only string is allowed.
   */
  minValue: optional(t.union([t.number, t.string])),

  /**
   * Ignore unspents larger than this amount of base units (e.g. satoshis). For doge, only string is allowed.
   */
  maxValue: optional(t.union([t.number, t.string])),

  /**
   * A `sequenceId` is a unique and arbitrary wallet identifier applied to transfers and transactions at creation. It is optional but highly recommended. With a `sequenceId` you can easily reference transfers and transactions—for example, to safely retry sending. Because the system only confirms one send request per `sequenceId` (and fails all subsequent attempts), you can retry sending without the risk of double spending. The `sequenceId` is only visible to users on the wallet and is not shared publicly.
   */
  sequenceId: optional(t.string),

  /**
   * (XRP only) Absolute max ledger the transaction should be accepted in, whereafter it will be rejected
   */
  lastLedgerSequence: optional(t.number),

  /**
   * (XRP only) Relative ledger height (in relation to the current ledger) that the transaction should be accepted in, whereafter it will be rejected
   */
  ledgerSequenceDelta: optional(t.number),

  /**
   * Set `true` to disable automatic change splitting.
   * Also see: `targetWalletUnspents`
   * @default false
   */
  noSplitChange: optional(t.boolean),

  /**
   * Used to explicitly specify the unspents to be used in the input set in the transaction. Each unspent should be in the form `prevTxId:nOutput`.
   */
  unspents: optional(t.array(t.string)),

  /**
   * Optional metadata (only persisted in BitGo) to be applied to the transaction. Use this to add transaction-specific information such as the transaction's purpose or another identifier that you want to reference later. The value is shown in the UI in the transfer listing page.
   * @maxLength 256
   */
  comment: optional(t.string),

  /**
   * Two factor auth code to enable sending the transaction. Not necessary if using a long lived access token within the spending limit.
   */
  otp: optional(t.string),

  /**
   * Specifies a custom destination address for the transaction's change output(s)
   * @maxLength 250
   */
  changeAddress: optional(t.string),

  /**
   * Flag for allowing external change addresses
   */
  allowExternalChangeAddress: optional(t.boolean),

  /**
   * (DASH only) Specifies whether or not to use Dash's "InstantSend" feature when sending a transaction.
   */
  instant: optional(t.boolean),

  /**
   * Extra transaction information for CSPR, EOS, HBAR, RUNE, STX, TON, XLM, and XRP. Required for XLM transactions.
   * Note: For XRP this is the destination tag (DT). For CSPR this is the transfer ID.
   */
  memo: optional(t.string),

  /**
   * Transfer ID for the transaction
   */
  transferId: optional(t.number),

  /**
   * EIP-1559 gas parameters for modern Ethereum transactions
   */
  eip1559: optional(t.any),

  /**
   * Custom gas limit to be used for sending the transaction. Only for ETH and ERC20 tokens.
   */
  gasLimit: optional(t.number),

  /**
   * Custodian transaction ID
   */
  custodianTransactionId: optional(t.string),

  /**
   * (DOT only) A nonce ID is a number used to protect private communications by preventing replay attacks.
   * This is an advanced option where users can manually input a new nonce value in order to correct or fill in a missing nonce ID value.
   */
  nonce: optional(t.string),
};

export const SendManyResponse: HttpResponse = {
  200: t.any,
  ...ErrorResponses,
};

/**
 * Advanced Wallets - Send to Many
 *
 * Send coins or tokens to one or more recipients. You can use this endpoint to schedule outgoing transactions in bulk, lowering your aggregate amount of blockchain fees.
 *
 * Retrieves the private key from KMS using the provided public key, then signs and broadcasts the transaction.
 *
 * Works with both multisignature and MPC wallets.
 *
 * Works with most BitGo-supported assets, but currently unavailable for: ALGO, ARBETH, AVAXC, CELO, CELO:CUSD, CSPR, DOT, EOS, HTETH:BGERCH, NEAR, OPETH, STX, TON, TRX, TRX:USDC, XLM, XRP, XTZ
 *
 * Use this endpoint only with advanced wallets. For other wallet types, use [Send to many](https://developers.bitgo.com/reference/expresswalletsendmany).
 *
 * @tag Advanced Wallets
 * @operationId advancedwallet.sendmany
 */
export const SendManyRoute = httpRoute({
  method: 'POST',
  path: '/api/v1/{coin}/advancedwallet/{walletId}/sendMany',
  request: httpRequest({
    params: {
      walletId: t.string,
      coin: t.string,
    },
    body: SendManyRequest,
  }),
  response: SendManyResponse,
  description: 'Send many transactions',
});