Skip to main content

Create a transfer

POST 
/transfers

Moves money in one of three shapes, inferred from the endpoints:

  • Fund a wallet — source = bank-account payment method, destination = wallet account (pull; settles asynchronously).
  • Pay an account — source = your wallet account, destination = another wallet account (internal; instant & final for a fiat currency). When the currency is a crypto code (e.g. BASE-USDC) this same shape moves a crypto wallet balance between accounts instead — e.g. player ↔ casino USDC transfers — and settles asynchronously over the crypto rail rather than posting instantly.
  • Cash out — source = wallet account, destination = bank-account payment method (push; settles asynchronously). A crypto-currency source cashes out to a bank (USDC → USD).

You must control the source account. Sending to a bank (cash-out/payout) requires the source account to be KYX-verified. bank→bank is rejected.

Request​

Header Parameters

    Idempotency-Key stringrequired

    Unique key per logical transfer. Replaying the same key (for the same account) returns the original transfer instead of creating a new one.

Body

required

    oneOf

    source_account uuidrequired

    Source account id — its wallet for the transfer currency is debited. The actor is this account.

    destination_account uuidrequired

    Destination account id — its wallet for the transfer currency is credited. May be a different account than the source.

    amount integerrequired

    Possible values: >= 1

    Amount in the smallest currency unit (e.g. cents).

    currency stringrequired

    ISO 4217 currency code (e.g. USD) for a fiat wallet-to-wallet move, or a crypto currency code in CHAIN-TOKEN format (e.g. BASE-USDC) to move a crypto wallet balance between accounts. Addresses the (account, currency) wallet on each side.

    reference stringnullable

    Optional merchant-facing description.

    metadata

    object

    Optional arbitrary key/value pairs.

    property name* any

    Optional arbitrary key/value pairs.

Responses​

Transfer created and final. Returned for an internal fiat wallet-to-wallet transfer, which posts synchronously. No response body — read the created transfer from the Location header (GET /transfers/{id}) or transfer.* webhooks.

Response Headers

  • Location

    string

    Path of the created transfer, e.g. /transfers/{transfer_id}.

Loading...