REST API›Link›Link Transfers

POST

Initiate a transfer from a Link account

The destination kind is selected by destination.kind and dispatched server-side. Supported kinds today: on-chain address ('address') and BitGo wallet ('wallet').

Path Params

  • enterpriseId string required
    Your enterprise id.

    at least 1 characters · matches ^[0-9a-f]{32}$

  • accountId string required
    The source Link account id.

Header Params

  • user-id string required
    User id of the user making the request.

    at least 1 characters

Body Params

object

Transfer initiation request body. Carries the amount, the asset to move (as a (genericAsset, network) pair), the optional venue sub-account bucket, and the discriminated destination describing where the funds should land.
  • externalId string required

    Client-supplied idempotency key, scoped to the source accountId.

    Two requests with the same externalId and identical hard fields (amount, asset, network, destination, …) resolve to the same LinkTransfer — the second call is reconciled against the first and the venue is not charged twice. A retry that disagrees on any hard field returns 409 TransferIdempotencyConflict.

    Required. Callers should generate a stable identifier (e.g. UUIDv4) per logical transfer and reuse it across retries.

    at least 1 characters

  • amount string required
    Amount to withdraw in Big Units (always positive — direction is implied).
  • genericAsset string required
    Generic asset symbol (chain-agnostic, e.g. usdc). Paired with network the service resolves a venue-specific raw asset. Using a generic-asset + network pair (rather than a BitGo concrete symbol) lets the endpoint support assets BitGo doesn't yet carry a concrete symbol for.

    at least 1 characters

  • accountSubType string
    Optional venue sub-account / bucket (e.g. SPOT vs MARGIN). Required for venues that hold balances across multiple sub-types where the caller needs to disambiguate which bucket to debit. When omitted, the venue's default sub-account is used.

    at least 1 characters

  • destination object required
    Destination — discriminated by kind. See TransferDestination.

    ONE OF

    • kind string enum required
      address
    • toAddress string required

      at least 1 characters

    • network string required
      Network identifier (e.g. ethereum, bitcoin).

      at least 1 characters

    • memo string

      at least 1 characters

  • venueOtp string
    Venue-specific one-time password (TOTP code). Required only when the venue has OTP withdrawal protection enabled. When omitted and the venue requires OTP, the transfer is created with status: "failed_retriable" and reason.code: "OtpRequired". Call the retry endpoint with a fresh code to proceed.

    at least 1 characters

Responses

201
Created

Response Body

object

Single transfer response object
  • id string required
  • accountId string required
  • status string enum required
    pending_policy_evaluationprocessingpending_approvalpendingcompletedfailedfailed_retriablecanceledrejected
  • amount string required

    at least 1 characters

  • genericAsset string

    at least 1 characters

  • rawAsset string required

    at least 1 characters

  • displayAsset string required

    at least 1 characters

  • rawNetwork string

    at least 1 characters

  • fromAsset string

    at least 1 characters

  • fromNetwork string

    at least 1 characters

  • fromId string

    at least 1 characters

  • fromType string enum
    addressbitgo_walletlink_accountvenue_account
  • toAsset string

    at least 1 characters

  • toNetwork string

    at least 1 characters

  • toId string

    at least 1 characters

  • toType string enum
    addressbitgo_walletlink_accountvenue_account
  • initiatedBy string

    at least 1 characters

  • fromName string

    at least 1 characters

  • toName string

    at least 1 characters

  • fromVenueId string

    at least 1 characters

  • toVenueId string

    at least 1 characters

  • accountSubType string
    Normalized sub-account-type for the transfer's owning Link account. Read from the Link DB column populated by the normalized-transfers Kafka consumer. Absent when the upstream message omitted a sub-type. For pass-through values (no matching venue-config entry), this carries the raw venue label and rawAccountSubType / accountSubTypeLabel are absent.

    at least 1 characters

  • rawAccountSubType string
    Venue-raw sub-type label, projected from venue config. Absent for pass-through values.

    at least 1 characters

  • accountSubTypeLabel string
    Human-readable sub-type display label, projected from venue config. Absent for single-sub-type venues or pass-through values.

    at least 1 characters

  • fromAccountSubType string
    Source-leg normalized sub-account-type. Only set for link_account legs that ingested with a sub-type.

    at least 1 characters

  • fromRawAccountSubType string

    at least 1 characters

  • fromAccountSubTypeLabel string

    at least 1 characters

  • toAccountSubType string
    Destination-leg normalized sub-account-type. Only set for link_account legs that ingested with a sub-type.

    at least 1 characters

  • toRawAccountSubType string

    at least 1 characters

  • toAccountSubTypeLabel string

    at least 1 characters

  • cryptoDetail object
    Crypto detail response for a transfer
    cryptoDetail object
    • confirmations number
    • createdAt string date-time required
    • feeAmount string

      at least 1 characters

    • feeAsset string

      at least 1 characters

    • feeNetwork string

      at least 1 characters

    • feeRawAsset string

      at least 1 characters

    • feeRawNetwork string

      at least 1 characters

    • fromAddress string

      at least 1 characters

    • hash string required

      at least 1 characters

    • id string required
    • linkTransferId string required
    • status string enum required
      unconfirmedconfirmedfailedcanceledunknown
    • toAddress string

      at least 1 characters

    • updatedAt string date-time required
  • bitgoDetail object
    BitGo detail response for a transfer
    bitgoDetail object
    • bitgoWalletAddress string

      at least 1 characters

    • createdAt string date-time required
    • evaluationId string

      at least 1 characters

    • id string required
    • linkTransferId string required
    • pendingApprovalId string

      at least 1 characters

    • transactionRequestId string

      at least 1 characters

    • transferId string

      at least 1 characters

    • updatedAt string date-time required
    • walletId string

      at least 1 characters

  • venueDetail object
    Venue detail response for a transfer
    venueDetail object
    • createdAt string date-time required
    • id string required
    • linkTransferId string required
    • updatedAt string date-time required
    • venueCreatedDate string date-time required
    • venueModifiedDate string date-time required
    • venueTransactionId string

      at least 1 characters

    • venueTransferId string

      at least 1 characters

  • reason object
    Normalized failure context. Set when status is failed (terminal) or failed_retriable (the venue rejected this attempt but the same transfer can be retried under the same externalId once external state changes). code is a stable string the caller can branch on; message is a human-readable description from the venue.
    reason object
    • code string required

      at least 1 characters

    • message string required

      at least 1 characters

  • sortTimestamp string date-time
  • createdAt string date-time required
  • updatedAt string date-time required
400
Bad Request
No response body
401
Unauthorized

Response Body

object

  • errorName string required
  • error string required
403
Forbidden

Response Body

object

  • errorName string required
  • error string required
404
Not Found

Response Body

object

  • errorName string required
  • error string required
409
Conflict

Response Body

object

  • errorName string required
  • error string required
422
Unprocessable Entity

Response Body

object

  • errorName string required
  • error string required
500
Internal Server Error

Response Body

object

  • errorName string required
  • error string required