Sign in
latestOpenAPI 3.0.32026-08-224982,0272.8 MB

e445c15e5bee

Link Transfers

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').

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

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: "failed_retriable" 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' | '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'
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