Link Transfers

Initiate a transfer from a Link account

Changed on

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

post/api/link/v1/enterprises/{enterpriseId}/accounts/{accountId}/transfers

Request

  • Base URL
    https://developers.bitgo.com
  • URL
    https://developers.bitgo.com/api/link/v1/enterprises/{enterpriseId}/accounts/{accountId}/transfers
  • Auth
    none declared. Required headers: user-id

Path parameters

enterpriseIdstring required
Example:59cd72485007a239fb00282ed480da1f

Your enterprise id.

accountIdstring required
Example:aba3a693-4f28-4523-8e53-85a3df22a608

The source Link account id.

Headers

user-idstring required

User id of the user making the request.

Request body

externalIdstring 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.

amountstring required

Amount to withdraw in Big Units (always positive — direction is implied).

genericAssetstring 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.

accountSubTypestring

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.

venueOtpstring

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: "pending_otp" and reason.code: "OtpRequired". Call the retry endpoint with a fresh code to proceed.

notesstring

Response

Created

idstring required
accountIdstring required
status'pending_policy_evaluation' | 'processing' | 'pending_approval' | 'pending' | 'completed' | 'failed' | 'failed_retriable' | 'pending_otp' | 'canceled' | 'rejected' required
amountstring required
genericAssetstring
rawAssetstring required
displayAssetstring required
rawNetworkstring
fromAssetstring
fromNetworkstring
fromIdstring
fromType'address' | 'bitgo_wallet' | 'link_account' | 'venue_account'
toAssetstring
toNetworkstring
toIdstring
toType'address' | 'bitgo_wallet' | 'link_account' | 'venue_account'
toMemostring

Destination memo / destination tag for this transfer, stored verbatim at initiation: an explicit destination.memo, or the ?dt=-style suffix parsed off toAddress (toId keeps the raw address with the suffix). Absent for chains without memos and for transfers that predate memo capture.

initiatedBystring
fromNamestring
toNamestring
fromVenueIdstring
toVenueIdstring
accountSubTypestring

Normalized sub-account-type for the transfer's owning Link account. Absent when a sub-type could not be determined. For pass-through values (no matching venue configuration), this carries the raw venue label and rawAccountSubType / accountSubTypeLabel are absent.

rawAccountSubTypestring

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

accountSubTypeLabelstring

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

fromAccountSubTypestring

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

fromRawAccountSubTypestring
fromAccountSubTypeLabelstring
toAccountSubTypestring

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

toRawAccountSubTypestring
toAccountSubTypeLabelstring
notesstring
sortTimestampstring date-time
createdAtstring date-time required
updatedAtstring date-time required

Example response

{
  "toMemo": "1234567890",
  "cryptoDetail": {
    "toMemo": "1234567890"
  }
}

Changes

  • 296f3ff58f6fRevision changes
    • warning

      added the new pending_otp enum value to the response property for the response status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property to the response with the status

  • b3e9978eb1f7Revision changes
    • info

      added the non-success response with the status