TransfersClient - Coinbase Developer Documentation

Defined in: _vendor/api/resources/transfers/client/Client.ts:16 Transfers represent both the request and execution of fund transfers from a source to a target. They provide upfront fee quotes and track the complete lifecycle from initiation through completion, failure, or reversal.

Fee Quotes

Every transfer provides a comprehensive fee quote in the fees array. This allows you to show users exactly what they’ll pay before any money moves. To review fees before execution:

Create a transfer with execute: false
Review the fees array in the response
Call POST /transfers/{transferId}/execute when ready to proceed

For automatic execution without fee review, create a transfer with execute: true. Fee Expiration: Fee quotes are valid for a limited time (typically 10-15 minutes from creation). The expiresAt field shows exactly when the fee quote will expire. If you don’t execute before this time, you’ll need to create a new transfer to get updated fees.

Fees

Transfer fees vary by source, target, amount and transfer type:

Bank fees - Traditional banking fees for depositing funds (e.g., $15.00 wire transfer fee)
Conversion fees - Fees for exchanging between different assets
Network fees - Onchain transaction costs to complete the transfer (e.g., ETH gas fees)

All fees are disclosed upfront in the fees array when you create a transfer.

Transfer Lifecycle

When you create a transfer, it will be in one of these statuses that determine what action you need to take:

quoted - Transfer is ready but requires manual execution via the /execute endpoint
processing - Transfer is being executed (no action needed - poll for completion)
completed - Transfer completed successfully
failed - Transfer failed (see failureReason for details)

Execution Control

execute: true: Transfer will automatically attempt to execute
execute: false: Transfer will be created in quoted status and you must call the /execute endpoint. Use this to obtain a fee quote or validate a transfer destination before deciding whether to execute the Transfer.

Sources and Targets

A source can be an Account or a Payment Method
A target can be an Account, Payment Method, Onchain Address, or Email Address

Transfer Execution

When a transfer reaches completed status, it contains the final execution details that delivered funds to the target and completion timestamps.

Failure Reasons

When a transfer fails, the failureReason field provides a human-readable description of what went wrong. Common failure reasons include:

“Insufficient balance to complete this transfer.”
“The recipient address is invalid for the selected network.”
“The recipient address failed security validation checks.”
“Unable to send to this recipient.”

Failure reason is only present when the transfer’s status is failed.

Methods

createTransfer()

createTransfer(request: TransferRequest, requestOptions?: RequestOptions): HttpResponsePromise<Transfer>;

Defined in: _vendor/api/resources/transfers/client/Client.ts:305 Create a new transfer to move funds from a source to a target. All transfers first transition to quoted. If execute: false, the transfer stays quoted until you call /v2/transfers/{transferId}/execute. If execute: true, quoted status emits momentarily before the transfer moves to processing, where execution proceeds. Subscribe to the transfers webhook to follow progress in real time instead of polling.

Parameters

request

TransferRequest

requestOptions?

RequestOptions Request-specific configuration.

Returns

HttpResponsePromise<Transfer>

Example

await client.transfers.createTransfer({
    idempotencyKey: "8e03978e-40d5-43e8-bc93-6894a57f9324",
    source: {
        accountId: "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
        asset: "usd"
    },
    target: {
        address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        network: "base",
        asset: "usdc"
    },
    amount: "100.00",
    asset: "usd",
    validateOnly: false,
    execute: false,
    metadata: {
        "invoiceId": "12345",
        "reference": "Payment for invoice #12345"
    },
    travelRule: {
        isSelf: false,
        isIntermediary: true,
        originator: {
            financialInstitution: "PayPal, Inc.",
            name: "John Doe",
            address: {
                line1: "123 Main St",
                line2: "Unit 201",
                city: "San Francisco",
                state: "California",
                postCode: "94105",
                countryCode: "US"
            },
            personalId: "123-45-6789",
            dateOfBirth: {
                day: "15",
                month: "08",
                year: "1990"
            }
        },
        beneficiary: {
            name: "Jane Smith",
            address: {
                line1: "456 Oak Ave",
                city: "Paris",
                postCode: "75001",
                countryCode: "FR"
            },
            walletType: "custodial"
        }
    }
})

executeFundTransfer()

executeFundTransfer(request: ExecuteFundTransferRequest, requestOptions?: RequestOptions): HttpResponsePromise<Transfer>;

Defined in: _vendor/api/resources/transfers/client/Client.ts:500 Executes a transfer which was created using the Create a transfer endpoint.

Parameters

request

ExecuteFundTransferRequest

requestOptions?

RequestOptions Request-specific configuration.

Returns

HttpResponsePromise<Transfer>

Example

await client.transfers.executeFundTransfer({
    idempotencyKey: "8e03978e-40d5-43e8-bc93-6894a57f9324",
    transferId: "transfer_af2937b0-9846-4fe7-bfe9-ccc22d935114"
})

getTransferById()

getTransferById(request: GetTransferByIdRequest, requestOptions?: RequestOptions): HttpResponsePromise<Transfer>;

Defined in: _vendor/api/resources/transfers/client/Client.ts:406 Get a transfer by its ID.

Parameters

request

GetTransferByIdRequest

requestOptions?

RequestOptions Request-specific configuration.

Returns

HttpResponsePromise<Transfer>

Example

await client.transfers.getTransferById({
    transferId: "transfer_af2937b0-9846-4fe7-bfe9-ccc22d935114"
})

listTransfers()

listTransfers(request?: ListTransfersRequest, requestOptions?: RequestOptions): HttpResponsePromise<ListTransfersResponse>;

Defined in: _vendor/api/resources/transfers/client/Client.ts:128 List transfers for your organization. Use this to view and monitor your transfer activity. Status Filtering: Filter by specific status to efficiently manage transfers:

?status=processing - Monitor active transfers.
?status=quoted - Find transfers awaiting execution.
?status=failed - Review failed transfers for troubleshooting.
?status=completed - Find completed transfers.

Account Filtering: Filter by account ID to find transfers involving a specific account:

?accountId=<ID> - All transfers where the account is either source or target (OR semantics).
?sourceAccountId=<ID> - Only transfers where the account is the source (outbound).
?targetAccountId=<ID> - Only transfers where the account is the target (inbound). Providing accountId together with sourceAccountId or targetAccountId is a validation error and returns HTTP 400.

Date Range Filtering: Filter by creation or last-updated time for reconciliation:

?createdAfter=2026-01-01T00:00:00Z&createdBefore=2026-01-31T23:59:59Z - Transfers created within a date range.
?updatedAfter=2026-01-01T00:00:00Z - Transfers updated since a given time. Useful for incremental sync.

Asset Filtering: Filter by source or target asset symbol:

?sourceAsset=usd - Transfers funded from a USD account.
?targetAsset=usdc - Transfers delivering USDC to the target.

Other Filters:

?sourceAddress=0x... - Transfers from a specific on-chain source address.
?targetAddress=0x... - Transfers to a specific on-chain destination address.
?targetEmail=user@example.com - Transfers to a specific email recipient.
?transferId=transfer_... - Look up a single transfer by ID; bypasses pagination.

Parameters

request?

ListTransfersRequest = {}

requestOptions?

RequestOptions Request-specific configuration.

Returns

HttpResponsePromise<ListTransfersResponse>

Example

await client.transfers.listTransfers({
    accountId: "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
    sourceAccountId: "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
    targetAccountId: "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
    createdAfter: "2026-01-01T00:00:00Z",
    createdBefore: "2026-01-31T23:59:59Z",
    updatedAfter: "2026-01-01T00:00:00Z",
    updatedBefore: "2026-01-31T23:59:59Z",
    sourceAsset: "usd",
    targetAsset: "usdc",
    sourceAddress: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    targetAddress: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    targetEmail: "user@example.com",
    transferId: "transfer_af2937b0-9846-4fe7-bfe9-ccc22d935114",
    pageToken: "eyJsYXN0X2lkIjogImFiYzEyMyIsICJ0aW1lc3RhbXAiOiAxNzA3ODIzNzAxfQ=="
})

submitDepositTravelRule()

submitDepositTravelRule(request: DepositTravelRuleRequest, requestOptions?: RequestOptions): HttpResponsePromise<DepositTravelRuleResponse>;

Defined in: _vendor/api/resources/transfers/client/Client.ts:653 Submit travel rule information for a deposit transfer held pending compliance review. Required fields vary by jurisdiction and may include originator name, address, date of birth, personal ID, and VASP information. If the submitted information satisfies all jurisdictional requirements, status will be completed and the transfer will proceed. Otherwise, status will be incomplete and missingFields will indicate which fields still need to be provided.

Parameters

request

DepositTravelRuleRequest

requestOptions?

RequestOptions Request-specific configuration.

Returns

HttpResponsePromise<DepositTravelRuleResponse>

Example

await client.transfers.submitDepositTravelRule({
    idempotencyKey: "8e03978e-40d5-43e8-bc93-6894a57f9324",
    transferId: "transfer_af2937b0-9846-4fe7-bfe9-ccc22d935114",
    originator: {
        name: "John Doe",
        address: {
            line1: "123 Main St",
            city: "San Francisco",
            state: "CA",
            postCode: "94105",
            countryCode: "US"
        }
    },
    beneficiary: {
        name: "Jane Smith"
    },
    isSelf: false
})

​Fee Quotes

​Fees

​Transfer Lifecycle

​Execution Control

​Sources and Targets

​Transfer Execution

​Failure Reasons

​Methods

​createTransfer()

​Parameters

request

requestOptions?

​Returns

​Example

​executeFundTransfer()

​Parameters

request

requestOptions?

​Returns

​Example

​getTransferById()

​Parameters

request

requestOptions?

​Returns

​Example

​listTransfers()

​Parameters

request?

requestOptions?

​Returns

​Example

​submitDepositTravelRule()

​Parameters

request

requestOptions?

​Returns

​Example

Fee Quotes

Fees

Transfer Lifecycle

Execution Control

Sources and Targets

Transfer Execution

Failure Reasons

Methods

createTransfer()

Parameters

Returns

Example

executeFundTransfer()

Parameters

Returns

Example

getTransferById()

Parameters

Returns

Example

listTransfers()

Parameters

Returns

Example

submitDepositTravelRule()

Parameters

Returns

Example