Fund Deposits & Withdrawals

The Fund Management APIs allow you to deposit and withdraw funds from Trading Accounts using linked bank accounts. Signal Accounts do not support fund transfers as they only create signals without executing real trades.

Prerequisites

Before depositing or withdrawing funds, you must first link a bank account using the Bank Linking APIs.

Cash Transfer

Endpoint: POST /cash-transfer

Description: Deposit or withdraw funds from a Trading Account

Request Body

{
  "instructionType": "DEPOSIT" | "WITHDRAWAL",
  "amount": 1000,
  "bankId": "bank-uuid-123"
}

Parameters

Parameter	Type	Required	Description
`instructionType`	string	Yes	Transaction type: `DEPOSIT` or `WITHDRAWAL`
`amount`	number	Yes	Amount in USD (minimum: $10 for deposits)
`bankId`	string	Yes	ID of the linked bank account

cURL Examples

# Deposit funds
curl -X POST {{BASE_URL}}/cash-transfer \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instructionType": "DEPOSIT",
    "amount": 1000,
    "bankId": "bank-uuid-123"
  }'

# Withdraw funds
curl -X POST {{BASE_URL}}/cash-transfer \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instructionType": "WITHDRAWAL",
    "amount": 500,
    "bankId": "bank-uuid-123"
  }'

Node.js Example

const axios = require("axios");

async function transferFunds(token, transferData) {
  try {
    const response = await axios.post(
      "{{BASE_URL}}/cash-transfer",
      transferData,
      {
        headers: {
          Authorization: `Bearer ${token}`,
          "Content-Type": "application/json",
        },
      },
    );
    return response.data;
  } catch (error) {
    console.error("Error transferring funds:", error.response?.data);
    throw error;
  }
}

// Deposit $1,000
const deposit = await transferFunds(token, {
  instructionType: "DEPOSIT",
  amount: 1000,
  bankId: "bank-uuid-123",
});
console.log("Deposit initiated:", deposit);

// Withdraw $500
const withdrawal = await transferFunds(token, {
  instructionType: "WITHDRAWAL",
  amount: 500,
  bankId: "bank-uuid-123",
});
console.log("Withdrawal initiated:", withdrawal);

Response

Success Response (200 OK):

{
  "message": "Deposit request submitted successfully. It may take up to 4 business days for deposits to arrive."
}

Error Response (400 Bad Request):

{
  "message": "Minimum deposit amount is $10"
}

Transaction Processing

Deposit Processing

Processing Time: Up to 4 business days
Minimum Amount: $10
No Fees: Bank transfers are free

Withdrawal Processing

Processing Time: Up to 4 business days
Requirements: Bank account must be verified (PROCESSED status)
No Fees: Bank transfers are free

Get All Transactions

Endpoint: GET /transactions

Description: Retrieve all deposit and withdrawal transactions for the authenticated user

Query Parameters

Parameter	Type	Required	Description
`limit`	number	No	Maximum number of transactions to return (default: 50, max: 100)
`offset`	number	No	Number of transactions to skip for pagination (default: 0)
`transactionType`	string	No	Filter by type: `DEPOSIT` or `WITHDRAWAL`
`status`	string	No	Filter by status: `PENDING`, `SCHEDULED`, `SUCCESS`, `FAILED`

cURL Examples

# Get all transactions
curl -X GET {{BASE_URL}}/transactions \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Get deposits only with pagination
curl -X GET "{{BASE_URL}}/transactions?transactionType=DEPOSIT&limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Get pending transactions
curl -X GET "{{BASE_URL}}/transactions?status=PENDING" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Node.js Example

async function getAllTransactions(token, filters = {}) {
  try {
    const response = await axios.get(
      "{{BASE_URL}}/transactions",
      {
        params: filters,
        headers: {
          Authorization: `Bearer ${token}`,
        },
      },
    );
    return response.data;
  } catch (error) {
    console.error("Error fetching transactions:", error.response?.data);
    throw error;
  }
}

// Get all transactions
const allTransactions = await getAllTransactions(token);
console.log("All transactions:", allTransactions);

// Get deposits with pagination
const deposits = await getAllTransactions(token, {
  transactionType: "DEPOSIT",
  limit: 20,
  offset: 0,
});
console.log("Deposits:", deposits);

// Get pending transactions
const pending = await getAllTransactions(token, {
  status: "PENDING",
});
console.log("Pending transactions:", pending);

Response

Success Response (200 OK):

{
  "results": [
    {
      "orderId": "1707200000000_bank-uuid-123",
      "transactionType": "DEPOSIT",
      "amount": 1000,
      "status": "SUCCESS",
      "bankId": "bank-uuid-123",
      "bankName": "Chase Bank",
      "createdDate": "2025-01-15T10:30:00Z",
      "updatedDate": "2025-01-17T14:30:00Z"
    },
    {
      "orderId": "1707200000001_bank-uuid-456",
      "transactionType": "WITHDRAWAL",
      "amount": 500,
      "status": "PENDING",
      "bankId": "bank-uuid-456",
      "bankName": "Bank of America",
      "createdDate": "2025-01-18T09:15:00Z",
      "updatedDate": "2025-01-18T09:15:00Z"
    }
  ],
  "pagination": {
    "total": 25,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

Get Transaction by ID

Endpoint: GET /transactions/{orderId}

Description: Retrieve details of a specific transaction

Path Parameters

Parameter	Type	Required	Description
`orderId`	string	Yes	The transaction order ID

cURL Example

curl -X GET {{BASE_URL}}/transactions/1707200000000_bank-uuid-123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Node.js Example

async function getTransaction(token, orderId) {
  try {
    const response = await axios.get(
      `{{BASE_URL}}/transactions/${orderId}`,
      {
        headers: {
          Authorization: `Bearer ${token}`,
        },
      },
    );
    return response.data;
  } catch (error) {
    console.error("Error fetching transaction:", error.response?.data);
    throw error;
  }
}

// Get specific transaction
const transaction = await getTransaction(token, "1707200000000_bank-uuid-123");
console.log("Transaction details:", transaction);

Response

Success Response (200 OK):

{
  "orderId": "1707200000000_bank-uuid-123",
  "userId": "user-uuid-123",
  "transactionType": "DEPOSIT",
  "amount": 1000,
  "status": "SUCCESS",
  "bankId": "bank-uuid-123",
  "bankName": "Chase Bank",
  "bankInstructionName": "Chase Bank",
  "portfolioId": "default",
  "brokerInstructionId": "12345",
  "clientInstructionId": "67890",
  "createdDate": "2025-01-15T10:30:00Z",
  "updatedDate": "2025-01-17T14:30:00Z"
}

Error Response (404 Not Found):

{
  "message": "Transaction not found"
}

Transaction Status Values

Status	Description
`SCHEDULED`	Bank account not processed yet.
`PENDING`	Transaction is being processed
`SUCCESS`	Transaction completed successfully
`FAILED`	Transaction failed

Bank Account Verification Status

Before you can withdraw funds, the linked bank account must be fully verified:

Status	Description	Can Deposit	Can Withdraw
`PENDING`	Initial verification in progress	✓	✗
`PENDING_VERIFICATION`	Awaiting micro-deposit confirmation	✓	✗
`PROCESSED`	Fully verified and active	✓	✓
`PENDING_DELETE`	Being unlinked	✗	✗
`REJECTED`	Verification failed	✗	✗

Important Notes

Trading Accounts Only - Fund transfers are only available for Trading Accounts
Bank Account Required - Must have a linked bank account before transferring funds
Verification Required - Bank account must be verified before withdrawals
Processing Time - Allow up to 4 business days for transfers to complete
No Fees - All bank transfers are free

Transaction Query Examples

Get Recent Deposits

const recentDeposits = await getAllTransactions(token, {
  transactionType: "DEPOSIT",
  limit: 10,
  offset: 0,
});

Get Failed Transactions

const failedTransactions = await getAllTransactions(token, {
  status: "FAILED",
});

Paginate Through All Transactions

async function getAllTransactionsWithPagination(token) {
  let allTransactions = [];
  let offset = 0;
  const limit = 50;
  let hasMore = true;

  while (hasMore) {
    const response = await getAllTransactions(token, { limit, offset });
    allTransactions = allTransactions.concat(response.results);
    hasMore = response.pagination.hasMore;
    offset += limit;
  }

  return allTransactions;
}

Common Errors

Invalid Filter Parameters

{
  "message": "Invalid transaction type. Must be DEPOSIT or WITHDRAWAL"
}

Solution: Use valid filter values: DEPOSIT, WITHDRAWAL, PENDING, SUCCESS, FAILED.

Bank Account Not Found

{
  "message": "Bank account not found"
}

Solution: Verify the bank ID is correct and the account is linked to your profile.

Bank Account Not Verified

{
  "message": "We're verifying your bank account. This usually takes about 4 hours. Once verified, you'll be able to deposit and start trading."
}

Solution: Wait for bank verification to complete before attempting deposits.

Insufficient Funds for Withdrawal

{
  "message": "Insufficient funds available for withdrawal"
}

Solution: Ensure you have enough available balance in your account.

Minimum Deposit Amount

{
  "message": "Minimum deposit amount is $10"
}

Solution: Increase the deposit amount to at least $10.

Best Practices

Link Bank First - Always link and verify a bank account before attempting transfers
Check Status - Verify bank account status before initiating withdrawals
Plan Timing - Account for 4 business day processing time
Error Handling - Implement proper error handling for verification delays
User Communication - Inform users about processing times and requirements

Next Steps

Bank Linking - Link and manage bank accounts
Trading Endpoints - Place trades with funded accounts
Portfolio Access - Check account balance