Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.bluumfinance.com/llms.txt

Use this file to discover all available pages before exploring further.

This guide covers all funding methods, status tracking, and edge cases for moving money in and out of investment wallets.

​
Deposit methods

​
ACH via Plaid

Pull funds from a linked bank account. Requires a linked bank account. 
curl -X POST "$BASE_URL/accounts/$ACCOUNT_ID/deposits" \
  -H "Authorization: Basic $AUTH" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: dep-$(uuidgen)" \
  -d '{
    "amount": "5000.00",
    "currency": "USD",
    "method": "ach",
    "description": "Initial funding",
    "plaid_options": {
      "item_id": "item_abc123",
      "account_id": "acc_1234567890"
    }
  }'

​
Manual bank transfer

The user sends a bank transfer using instructions provided in the response: 
curl -X POST "$BASE_URL/accounts/$ACCOUNT_ID/deposits" \
  -H "Authorization: Basic $AUTH" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: dep-$(uuidgen)" \
  -d '{
    "amount": "5000.00",
    "currency": "USD",
    "method": "manual_bank_transfer",
    "description": "Wire transfer funding"
  }'
The response includes bank details and a reference code: 
{
  "method_details": {
    "referenceCode": "BLUUM-ABC123XY",
    "bankDetails": {
      "bankName": "Choice Financial Group",
      "accountName": "Bluum Finance, Inc.",
      "routingNumber": "091311229",
      "accountNumber": "202534766488",
      "instructions": "Include reference code \"BLUUM-ABC123XY\" in your transfer memo."
    }
  },
  "expires_at": "2025-06-22T10:45:00.000Z"
}
Display the bank details and reference code to your user. The deposit expires at expires_at if funds are not received.

​
Tracking deposit status

curl -X GET "$BASE_URL/accounts/$ACCOUNT_ID/deposits/$DEPOSIT_ID" \
  -H "Authorization: Basic $AUTH"
StatusMeaningNext
pendingCreated, not yet initiatedWait or cancel
processingACH initiated with bankWait
receivedFunds received, settlingWait
completedFunds in wallet, ready to tradeTrade
failedTransfer failedCheck failure_reason, retry
Use webhooks (transfer.deposit.*) for real-time status updates instead of polling.

​
Withdrawals

Withdraw funds to a linked bank account: 
curl -X POST "$BASE_URL/accounts/$ACCOUNT_ID/withdrawals" \
  -H "Authorization: Basic $AUTH" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: wdr-$(uuidgen)" \
  -d '{
    "amount": "1000.00",
    "currency": "USD",
    "method": "ach",
    "description": "Withdrawal to checking",
    "plaid_options": {
      "item_id": "item_abc123",
      "account_id": "acc_1234567890"
    }
  }'

​
Withdrawal statuses

StatusMeaning
pendingCreated, can be canceled
processingACH initiated
submittedSubmitted to bank
completedFunds delivered
failedTransfer failed

​
Canceling a withdrawal

Only pending withdrawals can be canceled: 
curl -X POST "$BASE_URL/accounts/$ACCOUNT_ID/withdrawals/$WITHDRAWAL_ID/cancel" \
  -H "Authorization: Basic $AUTH"

​
Idempotency

Always include Idempotency-Key headers on deposit and withdrawal requests. This prevents duplicate transfers if a request is retried due to network issues or timeouts. 
-H "Idempotency-Key: dep-unique-operation-id"
See Idempotency for best practices.

​
Error handling

ErrorCauseResolution
BLUM-400-*Invalid amount or missing fieldsCheck request body
BLUM-422-*Insufficient funds (withdrawal)Check wallet balance
BLUM-409-*Duplicate idempotency key with different bodyUse a new key for different operations