Wallets

Methods for creating and managing wallets.

Quick Reference

Method	Description
createWallet	Create a Wallet entity which can then transfer amounts of Tokens.
findBalances	Search for Balances using either a simple filter or queryBuilder
findWallets	Search for Wallets using either a simple filter or queryBuilder
getBalance	Get a specific token/wallet balance
getBalanceHistory	Get a list of changes to token/wallet balance
getWallet	Get information about a specific Wallet
updateWallet	Update a Wallet

createWallet

Create a Wallet entity which can then transfer amounts of Tokens.

exampleexample result

await client.createWallet(
  {
    foreign: 'test-wallet-2',
    name: 'Irrelevant',
    metadata: {
      awesome: true,
      invalid: false,
    },
  },
  {
    // GENERALOPTIONS
  },
);

{
  wallet: {
    id: 4,
    foreign: '2026-01-01T10:00:00.000Z',
    name: 'Irrelevant',
    metadata: {
      awesome: true,
      invalid: false
    },
    type: 'regular',
    default_allow_negative: false,
    default_allow_positive: true,
    created_at: '2026-01-01T10:00:00.000Z',
    updated_at: '2026-01-01T10:00:00.000Z',
    status: 'active',
    default_dtw_to: '110',
    default_dtw_from: '011'
  }
};

createWalletFnInput

Input for createWallet

Attribute	Type	Required	Description
`foreign`	`string`	✓	User provided key for wallet. Must be unique
`name`	`string`		User provided key for wallet. Must be unique
`metadata`	`Metadata ▶`		Key/value object describing this wallet
`status`	`WalletStatus ▶`		Current status for the wallet
`default_allow_negative`	`boolean`		Boolean indicating if wallet (pending_amount + finished_amount) can be negative
`default_allow_positive`	`boolean`		Boolean indicating if wallet (pending_amount + finished_amount) can be positive. Used for token balance to deny positive balance.
▶`options`	`{}`		Optional flags for input

createWalletFnOutput

Output of createWallet

Attribute	Type	Always	Description
▶`wallet`	`{}`	✓	Wallet\|Entities who can make transfers in this system

findBalances

Search for Balances using either a simple filter or queryBuilder

exampleexample result

await client
  .findBalances()
  .where({
    wallet: TEST.INFO.WALLETS.validId0,
  })
  .orWhere('amount', '>', 100)
  .orWhere({
    wallet: TEST.INFO.WALLETS.validId1,
    token: 'USD',
  })
  .orWhere((builder) => {
    builder
      .where('updated_at', '<', '2020-01-01')
      .where('amount', '<', -1000000);
  })
  .limit(5)
  .offset(0)
  .orderBy('wallet_foreign', 'desc')
  .options({
    tracking_id: 'hello',
    return_metadata_total: true,
  });

{
  balances: [
    {
      updated_at: '2026-01-01T10:00:00.000Z',
      transfer_id: 2,
      token_id: 1,
      wallet_id: 16,
      pending_amount: 0,
      pending_amount_from: 0,
      pending_amount_to: 0,
      available_balance: 100000,
      finished_amount: 100000,
      latest_control_hash: null,
      amount: 100000,
      token_foreign: 'USD',
      token_metadata: null,
      wallet_foreign: '2026-01-01T10:00:00.000Z',
      wallet_metadata: null
    },
    {
      updated_at: '2026-01-01T10:00:00.000Z',
      transfer_id: 3,
      token_id: 3,
      wallet_id: 17,
      pending_amount: 0,
      pending_amount_from: 0,
      pending_amount_to: 0,
      available_balance: 100000,
      finished_amount: 100000,
      latest_control_hash: null,
      amount: 100000,
      token_foreign: 'GBP',
      token_metadata: null,
      wallet_foreign: '2026-01-01T10:00:00.000Z',
      wallet_metadata: null
    },
    {
      updated_at: '2026-01-01T10:00:00.000Z',
      transfer_id: 1,
      token_id: 2,
      wallet_id: 15,
      pending_amount: 0,
      pending_amount_from: 0,
      pending_amount_to: 0,
      available_balance: 100000,
      finished_amount: 100000,
      latest_control_hash: null,
      amount: 100000,
      token_foreign: 'EUR',
      token_metadata: null,
      wallet_foreign: '2026-01-01T10:00:00.000Z',
      wallet_metadata: null
    },
    {
      updated_at: '2026-01-01T10:00:00.000Z',
      transfer_id: 23,
      token_id: 2,
      wallet_id: 13,
      pending_amount: 0,
      pending_amount_from: 0,
      pending_amount_to: 0,
      available_balance: 123,
      finished_amount: 123,
      latest_control_hash: null,
      amount: 123,
      token_foreign: 'EUR',
      token_metadata: null,
      wallet_foreign: 'VALID9',
      wallet_metadata: null
    },
    {
      updated_at: '2026-01-01T10:00:00.000Z',
      transfer_id: 22,
      token_id: 2,
      wallet_id: 12,
      pending_amount: 0,
      pending_amount_from: 0,
      pending_amount_to: 0,
      available_balance: 121,
      finished_amount: 121,
      latest_control_hash: null,
      amount: 121,
      token_foreign: 'EUR',
      token_metadata: null,
      wallet_foreign: 'VALID8',
      wallet_metadata: null
    }
  ],
  metadata: {
    limit: 5,
    offset: 0,
    total: 7,
    more_rows: true,
    order: [
      {
        field: 'wallet_foreign',
        direction: 'desc'
      }
    ]
  }
};

findBalancesFnInput

Input for findBalances

Attribute	Type	Description
`token`	`string \| number`	Token to get balance for
`wallet`	`string \| number`	Wallet to get balance for
`amount`	`string \| number`	Balance amount
`available_balance`	`string \| number`	Balance amount available
`pending_amount`	`string \| number`	Balance pending_amount
`finished_amount`	`string \| number`	Balance finished_amount
`metadata`	`MetadataSearch ▶`	Metadata filter for custom properties
▶`options`	`{}`	Optional flags for input

findBalancesFnOutput

Output of findBalances

Attribute	Type	Always	Description
▶`balances`	`({})[]`	✓	Found balances
▶`metadata`	`{}`	✓	Metadata about the search

findWallets

Search for Wallets using either a simple filter or queryBuilder

exampleexample result

await client
  .findWallets()
  .where({
    metadata: {
      general: true,
    },
  })
  .where('id', '>', 1)
  .where((builder) => {
    builder.whereMetadata('tost', 10).orWhereMetadata('test', 1);
  })
  .limit(5)
  .offset(0)
  .orderBy(['status', { column: 'id', order: 'desc' }])
  .select('id')
  .options({
    tracking_id: 'hello',
  });

{
  wallets: [
    {
      id: 123
    },
    {
      id: 122
    },
    {
      id: 121
    }
  ],
  metadata: {
    limit: 5,
    offset: 0,
    more_rows: false,
    order: [
      {
        field: 'status',
        direction: 'asc'
      },
      {
        field: 'id',
        direction: 'desc'
      }
    ]
  }
};

findWalletsFnInput

Input for findWallets

Attribute	Type	Description
`foreign`	`string \| number`	Wallet foreign
`name`	`string \| number`	Wallet name
`type`	`WalletType ▶`	Type of the wallet
`status`	`WalletStatus ▶`	Current status for the wallet
`metadata`	`MetadataSearch ▶`	Metadata filter for custom properties
▶`options`	`{}`	Optional flags for input

findWalletsFnOutput

Output of findWallets

Attribute	Type	Always	Description
▶`wallets`	`({})[]`	✓	Found wallets
▶`metadata`	`{}`	✓	Metadata about the search

getBalance

Get a specific token/wallet balance

exampleexample result

await client.getBalance(
  {
    wallet: 'myMbyExistingWallet',
    token: 'MBYTOKEN',
    datetime: '2020-01-01',
  },
  {
    create_wallet_if_not_exists: true,
    create_token_if_not_exists: true,
    create_if_not_exists: true,
    // GENERALOPTIONS
  },
);

{
  balance: {
    token_id: 4,
    wallet_id: 19,
    wallet_foreign: 'myMbyExistingWallet',
    wallet_metadata: null,
    token_foreign: 'MBYTOKEN',
    token_metadata: null,
    pending_amount: 0,
    pending_amount_to: 0,
    pending_amount_from: 0,
    finished_amount: 0,
    available_balance: 0,
    amount: 0,
    latest_control_hash: null,
    updated_at: '2026-01-01T10:00:00.000Z'
  }
};

getBalanceFnInput

Input for getBalance

Attribute	Type	Required	Description
`token`	`string \| number`		Id of the token to get balance in
`wallet`	`string \| number`	✓	Id of the wallet to get balance for
`datetime`	`string`		Date and time this balance should be got
▶`options`	`{}`		Optional flags for input

getBalanceFnOutput

Output of getBalance

Attribute	Type	Always	Description
▶`balance`	`{}`

getBalanceHistory

Get a list of changes to token/wallet balance

exampleexample result

await TEST.client.getBalanceHistory(
  {
    wallet: 'newWallet',
    token: 'USD',
  },
  {
    create_token_if_not_exists: true,
    create_wallet_if_not_exists: true,
    limit: 5,
    select: [
      'transfer_identifier',
      'pending_amount',
      'finished_amount',
      'pending_amount_from',
      'pending_amount_to',
      'amount',
      // 'balance_id',
      // 'transfer_id',
      // 'transfer_control_hash',
      // 'transfer_from_wallet_id',
      // 'transfer_from_wallet_foreign',
      // 'transfer_to_wallet_id',
      // 'transfer_to_wallet_foreign',
      // 'transfer_amount',
      // 'transfer_type',
      // 'transfer_status',
      // 'transfer_force',
      // 'transfer_created_at',
      // 'transfer_updated_at',
      // 'transfer_metadata',
      // 'transfer_transfer_group_id',
      // 'transfer_transfer_group_identifier',
      // 'transfer_reverses_id',
      // 'transfer_reverses_identifier',
      // 'transfer_status_finalized_at',
      // 'token_id',
      // 'token_foreign',
      // 'wallet_id',
      // 'wallet_foreign',
      // 'latest_control_hash',
      // 'updated_at',
    ],
    offset: 0,
    order: 'desc',
    return_metadata_total: true,
    // GENERALOPTIONS
  },
);

{
  balances: [
    {
      transfer_identifier: 'depositUSD',
      pending_amount: 0,
      pending_amount_to: 0,
      pending_amount_from: 0,
      finished_amount: 10,
      amount: 10
    },
    {
      transfer_identifier: 'depositUSD',
      pending_amount: 10,
      pending_amount_to: 10,
      pending_amount_from: 0,
      finished_amount: 0,
      amount: 10
    }
  ],
  metadata: {
    limit: 5,
    offset: 0,
    total: 2,
    more_rows: false
  }
};

getBalanceHistoryFnInput

Input for getBalanceHistory

Attribute	Type	Required	Description
`token`	`string \| number`		Id of the token to get balance in
`wallet`	`string \| number`	✓	Id of the wallet to get balance for
`datetime`	`string`		Select entries older than
▶`options`	`{}`		Optional flags for input

getBalanceHistoryFnOutput

Output of getBalanceHistory

Attribute	Type	Always	Description
▶`balances`	`({})[]`	✓	Resolved balance change objects
▶`metadata`	`{}`	✓	Metadata about the search

getWallet

Get information about a specific Wallet

exampleexample result

await client.getWallet(
  {
    wallet: TEST.INFO.WALLETS.withEURFunds0.foreign,
  },
  {
    // GENERALOPTIONS
    ignore_cache: true,
    create_if_not_exists: true,
    return_only_id: false,
  },
);

{
  wallet: {
    id: 16,
    foreign: '2026-01-01T10:00:00.000Z',
    name: null,
    metadata: null,
    type: 'regular',
    default_allow_negative: false,
    default_allow_positive: true,
    created_at: '2026-01-01T10:00:00.000Z',
    updated_at: '2026-01-01T10:00:00.000Z',
    status: 'active',
    default_dtw_to: '110',
    default_dtw_from: '011'
  }
};

getWalletFnInput

Input for getWallet

Attribute	Type	Required	Description
`wallet`	`string \| number`	✓	Wallet foreign
▶`options`	`{}`		Optional flags for input

getWalletFnOutput

Output of getWallet

Attribute	Type	Always	Description
▶`wallet`	`{}`

updateWallet

Update a Wallet

exampleexample result

await client.updateWallet(
  {
    wallet: TEST.INFO.WALLETS.withEURFunds0.foreign,
    name: 'WT4',
    status: 'disabled',
    metadata: {
      metadata_number: 2,
    },
  },
  {
    return_when_not_updated: true,
    // GENERALOPTIONS
  },
);

{
  wallet: {
    id: 16,
    foreign: '2026-01-01T10:00:00.000Z',
    name: 'WT4',
    metadata: {
      metadata_number: 2
    },
    type: 'regular',
    default_allow_negative: false,
    default_allow_positive: true,
    created_at: '2026-01-01T10:00:00.000Z',
    updated_at: '2026-01-01T10:00:00.000Z',
    status: 'disabled',
    default_dtw_to: '110',
    default_dtw_from: '011'
  },
  updated: true
};

updateWalletFnInput

Input for updateWallet

Attribute	Type	Required	Description
`wallet`	`string \| number`	✓	Wallet foreign
`metadata`	`Metadata ▶`		Key/value object describing this wallet
`name`	`string`		User provided key for wallet. Must be unique
`status`	`WalletStatus ▶`		Current status for the wallet
`default_allow_positive`	`boolean`		Boolean indicating if wallet (pending_amount + finished_amount) can be positive. Used for token balance to deny positive balance.
`default_allow_negative`	`boolean`		Boolean indicating if wallet (pending_amount + finished_amount) can be negative
▶`options`	`{}`		Optional flags for input

updateWalletFnOutput

Output of updateWallet

Attribute	Type	Always	Description
▶`wallet`	`{}`		Wallet\|Entities who can make transfers in this system
`updated`	`boolean`		Boolean showing if the wallet was updated

Wallets ​

Quick Reference ​

createWallet ​

createWalletFnInput ​

createWalletFnOutput ​

findBalances ​

findBalancesFnInput ​

findBalancesFnOutput ​

findWallets ​

findWalletsFnInput ​

findWalletsFnOutput ​

getBalance ​

getBalanceFnInput ​

getBalanceFnOutput ​

getBalanceHistory ​

getBalanceHistoryFnInput ​

getBalanceHistoryFnOutput ​

getWallet ​

getWalletFnInput ​

getWalletFnOutput ​

updateWallet ​

updateWalletFnInput ​

updateWalletFnOutput ​

Wallets

Quick Reference

createWallet

createWalletFnInput

createWalletFnOutput

findBalances

findBalancesFnInput

findBalancesFnOutput

findWallets

findWalletsFnInput

findWalletsFnOutput

getBalance

getBalanceFnInput

getBalanceFnOutput

getBalanceHistory

getBalanceHistoryFnInput

getBalanceHistoryFnOutput

getWallet

getWalletFnInput

getWalletFnOutput

updateWallet

updateWalletFnInput

updateWalletFnOutput