Transfers & Settlement

Overview

Transfers move money between Wallgent wallets and external bank accounts or crypto addresses. There are three types:

Type	Description	Fees
Deposit	Fund a wallet from an external source	0.5% (min $0.25)
Withdrawal	Send funds from a wallet to an external destination	0.5% (min $0.25)
Internal	Move funds between wallets in the same organization	Free

Minimum deposit amount: $25.00.

Supported Rails

Rail	Direction	Speed	Currency
ACH	Deposit / Withdrawal	1-3 business days	USD
Wire	Deposit / Withdrawal	Same day	USD
FedNow	Deposit / Withdrawal	Instant	USD
USDC	Deposit / Withdrawal	Minutes	USDC

Deposits

Initiate a Deposit

POST /v1/transfers/deposit

Request Body

Field	Type	Required	Description
`walletId`	`string`	Yes	Destination wallet
`amount`	`string`	Yes	Amount to deposit
`currency`	`string`	Yes	`USD` or `USDC`
`source`	`object`	No	Source details (see below)
`bankAccountId`	`string`	No	Linked bank account ID

Provide either source or bankAccountId. If using bankAccountId, the bank account must be VERIFIED.

Fiat Source (ACH/Wire/FedNow)

Field	Type	Required	Description
`type`	`string`	Yes	`ACH`, `WIRE`, or `FEDNOW`
`bankAccountId`	`string`	No	Column counterparty ID
`routingNumber`	`string`	No	Bank routing number
`accountNumber`	`string`	No	Bank account number

USDC Source

Field	Type	Required	Description
`type`	`string`	Yes	`USDC`
`address`	`string`	Yes	Source wallet address
`chain`	`string`	No	Blockchain (default: Ethereum)

const deposit = await wg.transfers.deposit({
  walletId: 'wal_01J...',
  amount: '1000.00',
  currency: 'USD',
  bankAccountId: 'ba_01J...',
});

Response 202 (Accepted — settlement is asynchronous)

Withdrawals

Initiate a Withdrawal

POST /v1/transfers/withdraw

Request Body

Field	Type	Required	Description
`walletId`	`string`	Yes	Source wallet
`amount`	`string`	Yes	Amount to withdraw
`currency`	`string`	Yes	`USD` or `USDC`
`destination`	`object`	No	Destination details
`bankAccountId`	`string`	No	Linked bank account ID

Same structure as deposit source. Provide either destination or bankAccountId.

const withdrawal = await wg.transfers.withdraw({
  walletId: 'wal_01J...',
  amount: '500.00',
  currency: 'USD',
  bankAccountId: 'ba_01J...',
});

Internal Transfers

Move funds between wallets in the same organization with no fees.

POST /v1/transfers/internal

Request Body

Field	Type	Required	Description
`fromWalletId`	`string`	Yes	Source wallet
`toWalletId`	`string`	Yes	Destination wallet
`amount`	`string`	Yes	Amount to transfer
`description`	`string`	No	Transfer description

const transfer = await wg.transfers.internal({
  fromWalletId: 'wal_01J_ops',
  toWalletId: 'wal_01J_savings',
  amount: '250.00',
  description: 'Move to savings',
});

Both wallets must be ACTIVE and belong to the same organization.

List and Get Transfers

List Transfers

GET /v1/transfers?walletId=...&direction=DEPOSIT&status=...&limit=20&cursor=...

Parameter	Type	Description
`walletId`	`string`	Filter by wallet
`direction`	`string`	`DEPOSIT` or `WITHDRAWAL`
`status`	`string`	Filter by status
`limit`	`number`	Results per page (default: 20)
`cursor`	`string`	Pagination cursor

Get Transfer

GET /v1/transfers/:id

Cancel Transfer

POST /v1/transfers/:id/cancel

Cancel a pending transfer before it settles.

Settlement Flow

External transfers follow a 3-phase settlement process:

INITIATED → PENDING → COMPLETED
                    → FAILED

Initiated: Transfer request accepted, validation passed
Pending: Submitted to the settlement rail, awaiting confirmation
Completed: Funds settled, wallet balance updated
Failed: Settlement failed, funds returned (if applicable)

Settlement holds protect against ACH returns and chargebacks. Deposited funds may be held for a clearing period before becoming fully available.

Webhook Events

Event	Description
`deposit.initiated`	Deposit submitted to rail
`deposit.completed`	Deposit settled, funds available
`deposit.failed`	Deposit failed
`withdrawal.initiated`	Withdrawal submitted to rail
`withdrawal.completed`	Withdrawal settled
`withdrawal.failed`	Withdrawal failed
`wallet.funds_pending`	Funds deposited but held for clearing
`wallet.funds_available`	Held funds released and available

MCP Tools

Tool	Description
`wallgent_deposit_wallet`	Deposit funds via external rail
`wallgent_withdraw_wallet`	Withdraw funds to external destination
`wallgent_get_transfer`	Check transfer status

Permissions

Permission	Required For
`payments:write`	Initiate deposits, withdrawals, internal transfers
`payments:read`	List and get transfers

Errors

Code	HTTP Status	Description
`BANK_ACCOUNT_NOT_FOUND`	404	Bank account ID not found
`BANK_ACCOUNT_NOT_VERIFIED`	400	Bank account not verified
`INSUFFICIENT_FUNDS`	402	Not enough balance for withdrawal
`WALLET_FROZEN`	403	Source or destination wallet is frozen
`TRANSFER_NOT_FOUND`	404	Transfer ID not found
`SELF_PAYMENT`	400	Cannot transfer to same wallet

On this page