Tulu Infra Logo

External Transfer

Moves balance from one of your customer wallets to a customer wallet of another builder, identified by customer ID. Both sides must share the same channel, currency, and environment.

If the source or destination customer has wallets at more than one provider for the given channel + currency, pass fromProviderName or toProviderName to disambiguate. Use GET /v2/wallet/resolve/customer/:customerId to look up available providers before calling this endpoint.

Same provider: funds never leave that provider's float — settles synchronously with no provider call.
Cross provider: both builders' treasury holdings are rebooked immediately. The underlying float movement between providers is handled by the operator out-of-band. crossProvider: true is returned so you know to rebalance.

Body

fromCustomerId

*String

Your customer to debit.

channel

*String

Wallet channel — WALLET, ACCOUNT, STABLECOIN, or CBDC.

currency

*String

3-letter currency code e.g. NGN.

toCustomerId

*String

The destination customer ID (any builder).

amount

*Number

Amount to move in major units.

fromProviderName

String

Required only when the source customer has wallets at multiple providers for the given channel + currency.

toProviderName

String

Required only when the destination customer has wallets at multiple providers for the same channel + currency.

narration

String

Optional description recorded on both sides.

requestReference

String

Idempotency key — re-submitting the same key returns 409 instead of moving money twice.

Response

reference

String

Unique transfer reference.

from

Object

customerId, walletId, and provider of the source.

to

Object

customerId, walletId, and provider of the destination.

channel

String

Channel used.

currency

String

Currency moved.

amount

Number

Amount moved.

crossProvider

Boolean

true when source and destination sit at different providers.

status

String

Always COMPLETED on 201.

environment

String

SANDBOX or LIVE.

POST
/ v2/wallet/transfer/external
Endpoint URL(TEXT)
Request Body
Response(JSON)
// Click 'Try now' to see the response