US Bank Accounts - Bloque SDK

Overview

The USClient provides methods for creating and managing US bank accounts for individuals and businesses. These accounts are FDIC-insured and provide full ACH capabilities for receiving and sending funds.

Accessing USClient

import { SDK } from '@bloque/sdk';

const bloque = new SDK({
  auth: {
    type: 'apiKey',
    apiKey: process.env.BLOQUE_API_KEY,
  },
});

const user = await bloque.connect('@username');
const usClient = user.accounts.us;

Creating US Bank Accounts

Creating a US bank account is a two-step process:

Get a Terms of Service (TOS) acceptance link
Create the account with the signed agreement ID

Step 1: Get TOS Link

const tosLink = await user.accounts.us.getTosLink({
  redirectUri: 'https://myapp.com/callback'
});

console.log(tosLink.url);
// Example: https://dashboard.bridge.xyz/accept-terms-of-service?session_token=...

// Redirect user to tosLink.url
// After acceptance, extract signed_agreement_id from callback URL

Step 2: Create Account

const account = await user.accounts.us.create({
  type: 'individual',
  firstName: 'Robert',
  middleName: 'James',
  lastName: 'Johnson',
  email: '[email protected]',
  phone: '+12125551234',
  address: {
    streetLine1: '456 Wall Street',
    streetLine2: 'Suite 789',
    city: 'New York',
    state: 'NY',
    postalCode: '10005',
    country: 'US'
  },
  birthDate: '1985-03-15',
  taxIdentificationNumber: '123-45-6789',
  govIdCountry: 'US',
  govIdImageFront: 'base64_encoded_image',
  signedAgreementId: '0d139f8e-14b0-4540-92ba-4e66c619b533'
});

console.log(account.urn);
console.log(account.status); // 'creation_in_progress'

Wait for Active Status

const account = await user.accounts.us.create(
  {
    type: 'individual',
    firstName: 'Robert',
    lastName: 'Johnson',
    email: '[email protected]',
    phone: '+12125551234',
    address: {
      streetLine1: '456 Wall Street',
      city: 'New York',
      state: 'NY',
      postalCode: '10005',
      country: 'US'
    },
    birthDate: '1985-03-15',
    taxIdentificationNumber: '123-45-6789',
    govIdCountry: 'US',
    govIdImageFront: 'base64_encoded_image',
    signedAgreementId: '0d139f8e-14b0-4540-92ba-4e66c619b533'
  },
  { waitLedger: true }
);

console.log(account.status);        // 'active'
console.log(account.accountNumber); // Bank account number
console.log(account.routingNumber); // Bank routing number

Complete Example

// Step 1: Get TOS link
const tosLink = await user.accounts.us.getTosLink({
  redirectUri: 'https://myapp.com/callback'
});

// Redirect user to accept TOS
window.location.href = tosLink.url;

// Step 2: After callback, create account
// (Extract signed_agreement_id from callback URL)
const urlParams = new URLSearchParams(window.location.search);
const signedAgreementId = urlParams.get('signed_agreement_id');

const account = await user.accounts.us.create(
  {
    type: 'individual',
    firstName: 'Robert',
    lastName: 'Johnson',
    email: '[email protected]',
    phone: '+12125551234',
    address: {
      streetLine1: '456 Wall Street',
      city: 'New York',
      state: 'NY',
      postalCode: '10005',
      country: 'US'
    },
    birthDate: '1985-03-15',
    taxIdentificationNumber: '123-45-6789',
    govIdCountry: 'US',
    govIdImageFront: await encodeImageToBase64('path/to/id.jpg'),
    signedAgreementId,
  },
  { waitLedger: true }
);

Account Types

US accounts support two types:

individual - Personal bank accounts for individuals
business - Business bank accounts for companies

Listing US Accounts

List All Accounts

const { accounts } = await user.accounts.us.list();

accounts.forEach(account => {
  console.log(account.urn);
  console.log(account.type);
  console.log(account.firstName, account.lastName);
  console.log(account.accountNumber);
  console.log(account.routingNumber);
  console.log(account.status);
  console.log(account.balance);
});

Get Specific Account

const { accounts } = await user.accounts.us.list({
  urn: 'did:bloque:account:us-account:usr-123:us-456'
});

const account = accounts[0];

US Account Details

The UsAccount type includes:

urn

string

required

Unique resource name for the US account

string

required

US account ID

type

'individual' | 'business'

required

Account type (individual or business)

firstName

string

required

Account holder’s first name

middleName

string

Account holder’s middle name (if provided)

lastName

string

required

Account holder’s last name

string

required

Email address

phone

string

required

Phone number with country code

address

UsAccountAddress

required

Account holder’s address

birthDate

string

required

Birth date in YYYY-MM-DD format

accountNumber

string

Bank account number (if available)

routingNumber

string

Bank routing number (if available)

status

AccountStatus

required

Current status: creation_in_progress, active, disabled, frozen, deleted, or creation_failed

ownerUrn

string

required

URN of the account owner

ledgerId

string

required

Ledger account ID associated with this account

webhookUrl

string | null

Webhook URL for account events (if configured)

metadata

Record<string, unknown>

Custom metadata attached to the account

balance

Record<string, TokenBalance>

Token balances by asset (only included in list responses)

Managing US Accounts

Update Metadata

const account = await user.accounts.us.updateMetadata({
  urn: 'did:bloque:mediums:us-account:account:123',
  metadata: {
    updated_by: 'admin',
    update_reason: 'customer_request',
  },
});

Activate Account

const account = await user.accounts.us.activate(
  'did:bloque:mediums:us-account:account:123'
);

console.log(account.status); // 'active'

Freeze Account

const account = await user.accounts.us.freeze(
  'did:bloque:mediums:us-account:account:123'
);

console.log(account.status); // 'frozen'

Disable Account

const account = await user.accounts.us.disable(
  'did:bloque:mediums:us-account:account:123'
);

console.log(account.status); // 'disabled'

Using US Accounts

Check Balance

Use the general accounts.balance() method:

const balance = await user.accounts.balance(
  'did:bloque:account:us-account:usr-123:us-456'
);

Object.entries(balance).forEach(([asset, b]) => {
  console.log(`${asset}:`);
  console.log(`  Current: ${b.current}`);
  console.log(`  Pending: ${b.pending}`);
  console.log(`  In: ${b.in}`);
  console.log(`  Out: ${b.out}`);
});

Transfer Funds

// Transfer from US account to virtual account
const transfer = await user.accounts.transfer({
  sourceUrn: 'did:bloque:account:us-account:usr-123:us-456',
  destinationUrn: 'did:bloque:account:virtual:acc-12345',
  amount: '100000000',
  asset: 'DUSD/6',
  metadata: {
    reference: 'internal-transfer',
  },
});

View Transaction History

const { data, hasMore, next } = await user.accounts.movements({
  urn: 'did:bloque:account:us-account:usr-123:us-456',
  asset: 'DUSD/6',
  limit: 50,
});

data.forEach(movement => {
  console.log(movement.type);      // 'deposit' | 'withdraw' | 'transfer'
  console.log(movement.amount);
  console.log(movement.direction); // 'in' | 'out'
  console.log(movement.status);
});

Common Use Cases

Business Payroll

Create a US account for handling payroll:

const payrollAccount = await user.accounts.us.create(
  {
    type: 'business',
    firstName: 'Acme',
    lastName: 'Corporation',
    email: '[email protected]',
    phone: '+12125551234',
    address: {
      streetLine1: '123 Business Ave',
      city: 'New York',
      state: 'NY',
      postalCode: '10001',
      country: 'US'
    },
    birthDate: '2020-01-01',
    taxIdentificationNumber: '12-3456789',
    govIdCountry: 'US',
    govIdImageFront: businessDocumentBase64,
    signedAgreementId,
    name: 'Payroll Account',
  },
  { waitLedger: true }
);

// Execute batch payroll transfers
const payroll = await user.accounts.batchTransfer({
  reference: 'payroll-2024-01-15',
  operations: employees.map(emp => ({
    fromUrn: payrollAccount.urn,
    toUrn: emp.accountUrn,
    reference: `payroll-${emp.id}`,
    amount: emp.salary,
    asset: 'DUSD/6',
  })),
});

Accepting ACH Payments

const account = await user.accounts.us.create(
  {
    type: 'individual',
    // ... account details ...
    webhookUrl: 'https://api.example.com/webhooks/ach-payments',
  },
  { waitLedger: true }
);

console.log('Account Number:', account.accountNumber);
console.log('Routing Number:', account.routingNumber);

// Provide these to payers for ACH deposits
// Your webhook will be notified when funds arrive

Multi-Currency Operations

Combine US accounts with other account types:

// Create US account
const usAccount = await user.accounts.us.create(
  { /* ... */ },
  { waitLedger: true }
);

// Create Polygon wallet linked to same ledger
const polygon = await user.accounts.polygon.create(
  {
    ledgerId: usAccount.ledgerId,
  },
  { waitLedger: true }
);

// Now you can:
// 1. Receive ACH in USD
// 2. Convert to crypto
// 3. Transfer to Polygon wallet

API Reference

getTosLink()

Get Terms of Service acceptance link.

params

GetTosLinkParams

required

redirectUri

string

required

Redirect URI after user accepts terms of service

create()

Create a new US bank account.

params

CreateUsAccountParams

required

type

'individual' | 'business'

required

Account type

firstName

string

required

First name

middleName

string

Middle name (optional)

lastName

string

required

Last name

string

required

Email address

phone

string

required

Phone number with country code (e.g., +12125551234)

address

UsAccountAddress

required

Address information

birthDate

string

required

Birth date in YYYY-MM-DD format

taxIdentificationNumber

string

required

SSN for individuals, EIN for businesses

govIdCountry

string

required

Government ID issuing country (2-letter code)

govIdImageFront

string

required

Base64-encoded image of government ID front

signedAgreementId

string

required

Signed agreement ID obtained from getTosLink

name

string

Display name for the account

webhookUrl

string

Webhook URL to receive account events

ledgerId

string

Ledger account ID to associate with this account

metadata

Record<string, unknown>

Custom metadata to associate with the account

options

CreateAccountOptions

waitLedger

boolean

default:false

If true, wait for the account to become active before returning

timeout

number

default:60000

Maximum time to wait in milliseconds (only applies when waitLedger is true)

list()

List US bank accounts.

params

ListUsAccountsParams

urn

string

URN of a specific US account to retrieve

updateMetadata()

Update US account metadata.

params

UpdateUsMetadataParams

required

urn

string

required

URN of the US account to update

metadata

Record<string, unknown>

required

Metadata to update

activate()

Activate a US account.

urn

string

required

US account URN

freeze()

Freeze a US account.

urn

string

required

US account URN

disable()

Disable a US account.

urn

string

required

US account URN

Get Started

Core Concepts

Accounts

Swap & Exchange

Identity & Compliance

Organizations

Guides

​Overview

​Accessing USClient

​Creating US Bank Accounts

​Step 1: Get TOS Link

​Step 2: Create Account

​Wait for Active Status

​Complete Example

​Account Types

​Listing US Accounts

​List All Accounts

​Get Specific Account

​US Account Details

​Managing US Accounts

​Update Metadata

​Activate Account

​Freeze Account

​Disable Account

​Using US Accounts

​Check Balance

​Transfer Funds

​View Transaction History

​Common Use Cases

​Business Payroll

​Accepting ACH Payments

​Multi-Currency Operations

​API Reference

​getTosLink()

​create()

​list()

​updateMetadata()

​activate()

​freeze()

​disable()

Build docs developers (and LLMs) love

Overview

Accessing USClient

Creating US Bank Accounts

Step 1: Get TOS Link

Step 2: Create Account

Wait for Active Status

Complete Example

Account Types

Listing US Accounts

List All Accounts

Get Specific Account

US Account Details

Managing US Accounts

Update Metadata

Activate Account

Freeze Account

Disable Account

Using US Accounts

Check Balance

Transfer Funds

View Transaction History

Common Use Cases

Business Payroll

Accepting ACH Payments

Multi-Currency Operations

API Reference

getTosLink()

create()

list()

updateMetadata()

activate()

freeze()

disable()