sitemap.xml llms.txt
Skip to main content

Wallet Functions

To manage wallets, use the functions exported by the Wallet adapter.

Importing the adapter​

To use the functions of the Wallet adapter, import it as shown:
import { walletAdapter } from 'epicenter-libs';

The walletAdapter namespace exports functions that make calls to the Wallet API.

learn more

For descriptions of the objects used by the Wallet adapter functions, read Wallet Entities.

Update​

The update() function creates a new wallet or updates an existing one. The wallet is identified by the user-specific scope.

Wallet entries can be updated. They are key/value pairs containing user data required in the specified scope.

Note

If userKey is not provided, the function automatically uses the userKey from the current session.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a POST request to the /wallet endpoint.
  • Accepts a list of wallet items consisting of label and value pairs.
  • Returns the updated wallet.
Function signature
export async function update(
    scope: { userKey: string | undefined } & GenericScope,
    items: WalletItemCreateInView[],
    optionals: RoutingOptions = {},
): Promise<WalletReadOutView>

Parameters​

  • scope ({ userKey: string | undefined } & GenericScope) – The user-specific scope of the wallet
    • scopeBoundary – Scope entity
    • scopeKey (string) – Scope key
    • userKey (string) – The user whose wallet is being updated. If omitted, the current session's userKey is used
  • items (WalletItemCreateInView[]) – List of wallet items to update
    • label (string) – Identifier for the wallet entry
    • value? (string, optional) – Value associated with the label
  • optionals (Type: RoutingOptions): Additional routing options

Return value​

A promise that resolves to a WalletReadOutView object containing the updated wallet.

Usage example​

import { walletAdapter, SCOPE_BOUNDARY } from 'epicenter-libs';

// Add a user's phone number to their wallet
const scope = {
    userKey: '000001796733eef0842f4d6d960997018a33',
    scopeBoundary: SCOPE_BOUNDARY.GROUP,
    scopeKey: '0000017dd3bf540e5ada5b1e058f08f20461',
};

const wallet = await walletAdapter.update(scope, [
    { label: 'phone', value: '555-555-5555' }
]);

Retrieve​

Retrieve a single wallet or a list of wallets in a scope.

Get wallet​

The get() function retrieves a user's wallet within a specified scope.

Note

If userKey is not provided, the function automatically uses the userKey from the current session.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a GET request to the /wallet/{SCOPE_BOUNDARY}/{SCOPE_KEY}/{USER_KEY} endpoint.
  • Returns a WalletReadOutView object.
  • If the wallet does not exist, the function returns undefined.
Function signature
export async function get(
    scope: { userKey: string } & GenericScope,
    optionals: RoutingOptions = {},
): Promise<WalletReadOutView | undefined>

Parameters​

  • scope ({ userKey: string } & GenericScope) – The user-specific scope of the wallet
    • scopeBoundary – Scope entity
    • scopeKey (string) – Scope key
    • userKey (string) – The user whose wallet is being updated. If omitted, the current session's userKey is used
  • optionals (Type: RoutingOptions): Additional routing options

Return value​

A promise that resolves to one of the following:

  • A WalletReadOutView object containing the wallet data, or
  • undefined if the wallet is not found.

Usage example​

import { walletAdapter, SCOPE_BOUNDARY } from 'epicenter-libs';

// Get a user's wallet
const scope = {
    userKey: '000001796733eef0842f4d6d960997018a33',
    scopeBoundary: SCOPE_BOUNDARY.GROUP,
    scopeKey: '0000017dd3bf540e5ada5b1e058f08f20461',
};

const wallet = await walletAdapter.get(scope);

Get wallets in scope​

The withScope() function retrieves all wallets within a specified scope.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a GET request to the /wallet/with/{SCOPE_BOUNDARY}/{SCOPE_KEY} endpoint.
  • Supports pagination using the first and max parameters.
  • Returns a paginated list of wallet objects.
  • If no wallets are found (a 404 response), resolves to undefined rather than throwing.
Function signature
export async function withScope(
    scope: GenericScope,
    optionals: {
        first?: number;
        max?: number;
    } & RoutingOptions = {},
): Promise<Page<WalletReadOutView>>

Parameters​

  • scope (GenericScope) – Scope of the wallets
    • scopeBoundary – Scope entity
    • scopeKey (string) – Scope key
  • optionals (Type: { first?: number; max?: number } & RoutingOptions):
    • first? (number) – Index from which to begin returning results. Defaults to 0.
    • max? (number) – Maximum number of wallets to return
    • RoutingOptions – Additional routing options

Return value​

A promise that resolves to:

  • A Page<WalletReadOutView> object containing a paginated list of wallets.
  • undefined if no wallets are found in the given scope.

Usage example​

import { walletAdapter, SCOPE_BOUNDARY } from 'epicenter-libs';

// Get all wallets under a group
const scope = {
    scopeBoundary: SCOPE_BOUNDARY.GROUP,
    scopeKey: '0000017dd3bf540e5ada5b1e058f08f20461',
};

const wallets = await walletAdapter.withScope(scope);