Bank Linking

The Bank Linking APIs allow you to link, retrieve, and manage bank accounts for fund deposits and withdrawals. Bank accounts must be linked and verified before you can transfer funds.

Link Bank Account

Endpoint: POST /bank

Description: Link a new bank account to a Trading Account

Request Body

{
  "bankName": "Goldman Sachs",
  "bankRoutingNumber": "123456789",
  "bankAccountNumber": "123456789012",
  "bankAccountTypeCode": "CHECKING" | "SAVINGS"
}

Parameters

Parameter	Type	Required	Description
`bankName`	string	Yes	Name of the bank (e.g., "Goldman Sachs", "Bank of America")
`bankRoutingNumber`	string	Yes	9-digit ABA routing number
`bankAccountNumber`	string	Yes	Bank account number
`bankAccountTypeCode`	string	Yes	Account type: `CHECKING` or `SAVINGS`

cURL Examples

# Link a checking account
curl -X POST {{BASE_URL}}/bank \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bankName": "Goldman Sachs",
    "bankRoutingNumber": "123456789",
    "bankAccountNumber": "123456789012",
    "bankAccountTypeCode": "CHECKING"
  }'

# Link a savings account
curl -X POST {{BASE_URL}}/bank \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bankName": "Bank of America",
    "bankRoutingNumber": "123456789",
    "bankAccountNumber": "123456789012",
    "bankAccountTypeCode": "SAVINGS"
  }'

Node.js Example

const axios = require("axios");

async function linkBankAccount(token, bankData) {
  try {
    const response = await axios.post(
      "{{BASE_URL}}/bank",
      bankData,
      {
        headers: {
          Authorization: `Bearer ${token}`,
          "Content-Type": "application/json",
        },
      },
    );
    return response.data;
  } catch (error) {
    console.error("Error linking bank:", error.response?.data);
    throw error;
  }
}

// Link checking account
const checkingAccount = await linkBankAccount(token, {
  bankName: "Goldman Sachs",
  bankRoutingNumber: "123456789",
  bankAccountNumber: "123456789012",
  bankAccountTypeCode: "CHECKING",
});
console.log("Bank linked:", checkingAccount);

Response

Success Response (200 OK):

{
  "message": "Bank account linked successfully",
  "bankId": "1707200000000"
}

Error Response (400 Bad Request):

{
  "message": "This bank account is already linked."
}

Get Linked Banks

Endpoint: GET /banks

Description: Retrieve all linked bank accounts for the authenticated user

Query Parameters

Parameter	Type	Required	Description
`queryBankDetails`	boolean	No	Set to `true` to include encrypted account numbers and routing details

cURL Examples

# Get basic bank information
curl -X GET {{BASE_URL}}/banks \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Get detailed bank information with account numbers
curl -X GET "{{BASE_URL}}/banks?queryBankDetails=true" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Node.js Example

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

// Get basic bank list
const banks = await getLinkedBanks(token);
console.log("Linked banks:", banks);

// Get detailed bank information
const detailedBanks = await getLinkedBanks(token, true);
console.log("Detailed banks:", detailedBanks);

Response

Basic Response (without details):

{
  "results": [
    {
      "bankId": "1707200000000",
      "bankName": "Goldman Sachs",
      "bankInstructionName": "Goldman Sachs",
      "status": "PROCESSED",
      "rfp": true,
      "limit": 50000
    },
    {
      "bankId": "1707200000001",
      "bankName": "Bank of America",
      "bankInstructionName": "Bank of America (5432)",
      "status": "PENDING",
      "rfp": false
    }
  ]
}

Detailed Response (with queryBankDetails=true):

{
  "results": [
    {
      "bankId": "1707200000000",
      "instructionId": "12345",
      "bankName": "Goldman Sachs",
      "bankInstructionName": "Goldman Sachs",
      "bankRoutingNumber": "123456789",
      "bankAccountNumber": "****6789",
      "bankAccountTypeCode": "CHECKING",
      "status": "PROCESSED",
      "rfp": true,
      "limit": 50000,
      "updatedDate": "2025-01-15T10:30:00Z"
    }
  ]
}

Delete Linked Bank

Endpoint: DELETE /bank/{bankId}

Description: Unlink a bank account from the Trading Account

Path Parameters

Parameter	Type	Required	Description
`bankId`	string	Yes	The ID of the bank account to unlink

cURL Example

curl -X DELETE {{BASE_URL}}/bank/1707200000000 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Node.js Example

async function deleteBankAccount(token, bankId) {
  try {
    const response = await axios.delete(
      `{{BASE_URL}}/bank/${bankId}`,
      {
        headers: {
          Authorization: `Bearer ${token}`,
        },
      },
    );
    return response.data;
  } catch (error) {
    console.error("Error deleting bank:", error.response?.data);
    throw error;
  }
}

// Unlink a bank account
const result = await deleteBankAccount(token, "1707200000000");
console.log("Bank unlinked:", result);

Response

Success Response (200 OK):

{
  "message": "Bank unlink request sent successfully"
}

Bank Account Status

Bank accounts go through several verification states:

Status	Description	Can Use
`SCHEDULED`	Trading account not processed yet.	✗
`PENDING`	Verification in progress (4 hours)	✗
`PENDING_VERIFICATION`	Awaiting micro-deposit confirmation	✗
`PROCESSED`	Fully verified and active	✓
`PENDING_DELETE`	Being unlinked	✗
`REJECTED`	Verification failed	✗

Common Errors

Invalid Routing Number

{
  "message": "Valid 9-digit routing number is required"
}

Solution: Verify the routing number is exactly 9 digits.

Bank Already Linked

{
  "message": "This bank account is already linked."
}

Solution: Use a different bank account or delete the existing one first.

Bank Not Found

{
  "message": "Bank not found"
}

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

Invalid Account Type

{
  "message": "Bank account type must be SAVINGS or CHECKING"
}

Solution: Use either CHECKING or SAVINGS for the account type.

Best Practices

Verify Details - Double-check routing number and account number before linking
Use Correct Type - Select the correct account type (CHECKING or SAVINGS)
Wait for Verification - Allow time for micro-deposits to appear
Monitor Status - Check bank status before attempting transfers

Next Steps

Fund Deposits & Withdrawals - Transfer funds using linked banks
Account Management - Manage user accounts
Trading Endpoints - Place trades with funded accounts