[PERS SDK - v2.3.26](/sdk-reference/readme) / [Exports](/sdk-reference/modules) / TokenManager

# Class: TokenManager

Domain Token Manager - Clean, high-level interface for business token operations

Handles business domain tokens (reward tokens, credit tokens, NFTs, status tokens).
This is separate from AuthTokenManager which handles authentication tokens.

Provides a simplified API for token management including retrieving token information,
managing different types of tokens (credit, reward, status), and administrative operations.
Maintains access to the full token SDK for advanced blockchain and token operations.

**`Example`**

```typescript
// Get all available tokens
const tokens = await sdk.tokens.getTokens();
console.log(`Found ${tokens.length} tokens`);

// Get active credit token
const creditToken = await sdk.tokens.getActiveCreditToken();
console.log('Credit token:', creditToken.name);

// Get reward tokens
const rewards = await sdk.tokens.getRewardTokens();
```

**`Example`**

```typescript
// Get all token types
const types = await sdk.tokens.getTokenTypes();

// Get status tokens for user progression
const statusTokens = await sdk.tokens.getStatusTokens();

// Get token by blockchain contract
const token = await sdk.tokens.getTokenByContract('0x123...', 'token-id');
```

**`Example`**

```typescript
// Admin: Create new token type
const newToken = await sdk.tokens.createToken({
  name: 'VIP Points',
  symbol: 'VIP',
  type: 'REWARD'
});

// Admin: Toggle token status
await sdk.tokens.toggleTokenActive('token-123');
```

## Table of contents

### Constructors

- [constructor](/sdk-reference/classes/tokenmanager#constructor)


### Methods

- [getTokens](/sdk-reference/classes/tokenmanager#gettokens)
- [getTokenTypes](/sdk-reference/classes/tokenmanager#gettokentypes)
- [getActiveCreditToken](/sdk-reference/classes/tokenmanager#getactivecredittoken)
- [getRewardTokens](/sdk-reference/classes/tokenmanager#getrewardtokens)
- [getStatusTokens](/sdk-reference/classes/tokenmanager#getstatustokens)
- [getTokenByContract](/sdk-reference/classes/tokenmanager#gettokenbycontract)
- [getTokenMetadata](/sdk-reference/classes/tokenmanager#gettokenmetadata)
- [getRewards](/sdk-reference/classes/tokenmanager#getrewards)
- [getStamps](/sdk-reference/classes/tokenmanager#getstamps)
- [createToken](/sdk-reference/classes/tokenmanager#createtoken)
- [updateToken](/sdk-reference/classes/tokenmanager#updatetoken)
- [toggleTokenActive](/sdk-reference/classes/tokenmanager#toggletokenactive)
- [deleteTokenMetadata](/sdk-reference/classes/tokenmanager#deletetokenmetadata)
- [getTokenService](/sdk-reference/classes/tokenmanager#gettokenservice)
- [exportMetadataCSV](/sdk-reference/classes/tokenmanager#exportmetadatacsv)
- [setTokenMetadataApproval](/sdk-reference/classes/tokenmanager#settokenmetadataapproval)


## Constructors

### constructor

• **new TokenManager**(`apiClient`, `eventEmitter?`): [`TokenManager`](/sdk-reference/classes/tokenmanager)

#### Parameters

| Name | Type |
|  --- | --- |
| `apiClient` | [`PersApiClient`](/sdk-reference/classes/persapiclient) |
| `eventEmitter?` | [`PersEventEmitter`](/sdk-reference/classes/perseventemitter) |


#### Returns

[`TokenManager`](/sdk-reference/classes/tokenmanager)

#### Defined in

[managers/token-manager.ts:64](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/token-manager.ts#L64)

## Methods

### getTokens

▸ **getTokens**(`options?`): `Promise`<`PaginatedResponseDTO`<`TokenDTO`>>

Get all available tokens

Retrieves all tokens available in the system, including credit tokens,
reward tokens, and status tokens. This includes both active and inactive tokens.

#### Parameters

| Name | Type |
|  --- | --- |
| `options?` | `PaginationOptions` |


#### Returns

`Promise`<`PaginatedResponseDTO`<`TokenDTO`>>

Promise resolving to array of tokens with complete information

**`Example`**

```typescript
const tokens = await sdk.tokens.getTokens();

tokens.forEach(token => {
  console.log(`${token.name} (${token.symbol})`);
  console.log(`Type: ${token.type}`);
  console.log(`Active: ${token.isActive}`);
  console.log(`Contract: ${token.contractAddress}`);
});
```

#### Defined in

[managers/token-manager.ts:90](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/token-manager.ts#L90)

### getTokenTypes

▸ **getTokenTypes**(`options?`): `Promise`<`PaginatedResponseDTO`<`TokenTypeDTO`>>

Get all token types

Retrieves the available token type definitions and their configurations.
This includes metadata about how different token types behave in the system.

#### Parameters

| Name | Type |
|  --- | --- |
| `options?` | `PaginationOptions` |


#### Returns

`Promise`<`PaginatedResponseDTO`<`TokenTypeDTO`>>

Promise resolving to token type configurations

**`Example`**

```typescript
const types = await sdk.tokens.getTokenTypes();
console.log('Available token types:', types);

// Use for token creation or validation
const isValidType = types.some(type => type.name === 'REWARD');
```

#### Defined in

[managers/token-manager.ts:111](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/token-manager.ts#L111)

### getActiveCreditToken

▸ **getActiveCreditToken**(): `Promise`<`TokenDTO`>

Get active credit token

Retrieves the currently active credit token used for the main loyalty currency.
There is typically only one active credit token per tenant.

#### Returns

`Promise`<`TokenDTO`>

Promise resolving to active credit token

**`Throws`**

When no active credit token is found

**`Example`**

```typescript
try {
  const creditToken = await sdk.tokens.getActiveCreditToken();
  console.log('Main loyalty currency:', creditToken.name);
  console.log('Symbol:', creditToken.symbol);
  console.log('Exchange rate:', creditToken.exchangeRate);
} catch (error) {
  console.log('No active credit token found');
}
```

#### Defined in

[managers/token-manager.ts:136](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/token-manager.ts#L136)

### getRewardTokens

▸ **getRewardTokens**(`options?`): `Promise`<`PaginatedResponseDTO`<`TokenDTO`>>

Get reward tokens

Retrieves all tokens designated as rewards that can be earned through
campaigns, challenges, or other loyalty activities.

#### Parameters

| Name | Type |
|  --- | --- |
| `options?` | `PaginationOptions` |


#### Returns

`Promise`<`PaginatedResponseDTO`<`TokenDTO`>>

Promise resolving to array of reward tokens

**`Example`**

```typescript
const rewardTokens = await sdk.tokens.getRewardTokens();

console.log('Available rewards:');
rewardTokens.forEach(token => {
  console.log(`- ${token.name}: ${token.description}`);
});

// Use for campaign rewards or redemption options
const discountToken = rewardTokens.find(t => t.name.includes('Discount'));
```

#### Defined in

[managers/token-manager.ts:161](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/token-manager.ts#L161)

### getStatusTokens

▸ **getStatusTokens**(`options?`): `Promise`<`PaginatedResponseDTO`<`TokenDTO`>>

Get status tokens

Retrieves tokens that represent user status or achievement levels.
These are typically used for user progression and tier systems.

#### Parameters

| Name | Type |
|  --- | --- |
| `options?` | `PaginationOptions` |


#### Returns

`Promise`<`PaginatedResponseDTO`<`TokenDTO`>>

Promise resolving to array of status tokens

**`Example`**

```typescript
const statusTokens = await sdk.tokens.getStatusTokens();

console.log('Status levels available:');
statusTokens.forEach(token => {
  console.log(`${token.name} - ${token.description}`);
});

// Use for user tier display or progression tracking
const vipToken = statusTokens.find(t => t.name === 'VIP Status');
```

#### Defined in

[managers/token-manager.ts:186](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/token-manager.ts#L186)

### getTokenByContract

▸ **getTokenByContract**(`contractAddress`, `contractTokenId?`): `Promise`<`TokenDTO`>

Get token by contract address

Retrieves a specific token by its blockchain contract address and optional
token ID. Useful for blockchain integrations and Web3 operations.

#### Parameters

| Name | Type | Default value | Description |
|  --- | --- | --- | --- |
| `contractAddress` | `string` | `undefined` | Blockchain contract address of the token |
| `contractTokenId` | `null` | `string` | `null` | Optional specific token ID within the contract (for NFTs) |


#### Returns

`Promise`<`TokenDTO`>

Promise resolving to matching token

**`Throws`**

When token with specified contract address is not found

**`Example`**

```typescript
// Get ERC20 token by contract address
const token = await sdk.tokens.getTokenByContract('0x123...');
console.log('ERC20 token:', token.name);
```

**`Example`**

```typescript
// Get specific NFT by contract and token ID
const nft = await sdk.tokens.getTokenByContract(
  '0x456...',
  'token-123'
);
console.log('NFT:', nft.name, 'ID:', nft.contractTokenId);
```

#### Defined in

[managers/token-manager.ts:218](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/token-manager.ts#L218)

### getTokenMetadata

▸ **getTokenMetadata**(`options?`): `Promise`<`PaginatedResponseDTO`<`TokenMetadataDTO`>>

Get all token metadata with filtering, pagination, and include relations

Retrieves token metadata (rewards/stamps) with server-side filtering, pagination,
and optional include relations for additional data.
Useful for displaying rewards (ERC1155) or stamps (ERC721) in admin tables.
Non-admin users always get active metadata only.

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `options?` | `TokenMetadataQueryParams` | Filter, pagination, and include options |


#### Returns

`Promise`<`PaginatedResponseDTO`<`TokenMetadataDTO`>>

Promise resolving to paginated token metadata

**`Example`**

```typescript
const rewards = await sdk.tokens.getTokenMetadata({
  tokenType: 'ERC1155',
  active: true,
  page: 1,
  limit: 10,
  sortBy: 'name',
  sortOrder: 'ASC',
  include: ['mintCount', 'burnCount', 'token']
});

rewards.data.forEach(r => {
  console.log(`${r.name}: ${r.mintCount} minted, ${r.burnCount} burned`);
  console.log(`Contract: ${r.included?.token?.contractAddress}`);
});
```

**`Example`**

```typescript
const stamps = await sdk.tokens.getTokenMetadata({
  tokenType: 'ERC721',
  search: 'gold',
  include: ['ownerBusiness', 'token']
});

stamps.data.forEach(s => {
  console.log(`${s.name} owned by ${s.included?.ownerBusiness?.displayName}`);
});
```

#### Defined in

[managers/token-manager.ts:264](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/token-manager.ts#L264)

### getRewards

▸ **getRewards**(`options?`): `Promise`<`PaginatedResponseDTO`<`TokenMetadataDTO`>>

Get rewards (ERC1155 token metadata) with filtering, pagination, and include relations

Convenience method for fetching reward metadata. Rewards are ERC1155 tokens
that represent collectible items, vouchers, or other redeemable rewards.

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `options?` | [`RewardsFilterOptions`](/sdk-reference/modules#rewardsfilteroptions) | Filter, pagination, and include options (tokenType is set automatically) |


#### Returns

`Promise`<`PaginatedResponseDTO`<`TokenMetadataDTO`>>

Promise resolving to paginated reward metadata

**`Example`**

```typescript
const rewards = await sdk.tokens.getRewards({ 
  active: true, 
  limit: 10,
  include: ['mintCount', 'burnCount', 'token', 'ownerBusiness']
});

rewards.data.forEach(r => {
  console.log(`${r.name}: ${r.mintCount ?? 0} minted`);
  if (r.included?.token) {
    console.log(`  Chain: ${r.included.token.chainId}, Contract: ${r.included.token.contractAddress}`);
  }
});
```

#### Defined in

[managers/token-manager.ts:293](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/token-manager.ts#L293)

### getStamps

▸ **getStamps**(`options?`): `Promise`<`PaginatedResponseDTO`<`TokenMetadataDTO`>>

Get stamps (ERC721 token metadata) with filtering, pagination, and include relations

Convenience method for fetching stamp metadata. Stamps are ERC721 tokens
that represent achievements, badges, or collectible status markers.

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `options?` | [`StampsFilterOptions`](/sdk-reference/modules#stampsfilteroptions) | Filter, pagination, and include options (tokenType is set automatically) |


#### Returns

`Promise`<`PaginatedResponseDTO`<`TokenMetadataDTO`>>

Promise resolving to paginated stamp metadata

**`Example`**

```typescript
const stamps = await sdk.tokens.getStamps({ 
  active: true, 
  limit: 10,
  include: ['mintCount', 'burnCount', 'token', 'ownerBusiness']
});

stamps.data.forEach(s => {
  console.log(`${s.name}: ${s.mintCount ?? 0} minted`);
  if (s.included?.ownerBusiness) {
    console.log(`  Owner: ${s.included.ownerBusiness.displayName}`);
  }
});
```

#### Defined in

[managers/token-manager.ts:322](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/token-manager.ts#L322)

### createToken

▸ **createToken**(`tokenData`): `Promise`<`TokenDTO`>

Admin: Create new token

Creates a new token type in the system. This operation requires administrator
privileges and is typically used for setting up new loyalty currencies,
rewards, or status tokens.

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `tokenData` | `any` | Token creation data including name, symbol, type, and configuration |


#### Returns

`Promise`<`TokenDTO`>

Promise resolving to created token

**`Throws`**

When not authenticated as admin or validation fails

**`Example`**

```typescript
// Admin operation - create new loyalty currency
const creditToken = await sdk.tokens.createToken({
  name: 'Hotel Points',
  symbol: 'HP',
  type: 'CREDIT',
  isActive: true,
  exchangeRate: 1.0,
  description: 'Main loyalty currency for hotel rewards'
});
```

**`Example`**

```typescript
// Admin operation - create new reward type
const rewardToken = await sdk.tokens.createToken({
  name: '10% Discount Coupon',
  symbol: 'DISC10',
  type: 'REWARD',
  isActive: true,
  description: '10% discount on next purchase'
});
```

#### Defined in

[managers/token-manager.ts:362](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/token-manager.ts#L362)

### updateToken

▸ **updateToken**(`tokenId`, `tokenData`): `Promise`<`TokenDTO`>

Admin: Update token

Updates an existing token's configuration. This operation requires administrator
privileges and can modify token properties such as name, description, or status.

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `tokenId` | `string` | ID of the token to update |
| `tokenData` | `any` | Token update data (partial update supported) |


#### Returns

`Promise`<`TokenDTO`>

Promise resolving to updated token

**`Throws`**

When not authenticated as admin or token not found

**`Example`**

```typescript
// Admin operation - update token configuration
const updated = await sdk.tokens.updateToken('token-123', {
  description: 'Updated token description',
  exchangeRate: 1.25,
  isActive: true
});

console.log('Token updated:', updated.name);
```

#### Defined in

[managers/token-manager.ts:389](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/token-manager.ts#L389)

### toggleTokenActive

▸ **toggleTokenActive**(`tokenId`): `Promise`<`TokenDTO`>

Admin: Toggle token active status

Toggles the active/inactive status of a token. Inactive tokens are not
available for new operations but existing holdings remain valid.
Requires administrator privileges.

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `tokenId` | `string` | ID of the token to toggle |


#### Returns

`Promise`<`TokenDTO`>

Promise resolving to updated token

**`Throws`**

When not authenticated as admin or token not found

**`Example`**

```typescript
// Admin operation - disable a token temporarily
const updated = await sdk.tokens.toggleTokenActive('seasonal-token-123');

if (updated.isActive) {
  console.log('Token reactivated');
} else {
  console.log('Token deactivated');
}
```

#### Defined in

[managers/token-manager.ts:416](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/token-manager.ts#L416)

### deleteTokenMetadata

▸ **deleteTokenMetadata**(`metadataId`): `Promise`<`void`>

Admin: Delete token metadata (soft delete)

Soft deletes token metadata by setting deletedAt timestamp.
Requires administrator privileges. Will fail with 409 Conflict
if metadata is currently in use by active campaigns or redemptions.

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `metadataId` | `string` | ID of the token metadata to delete |


#### Returns

`Promise`<`void`>

**`Throws`**

When not authenticated as admin

**`Throws`**

409 Conflict if metadata is in use

**`Example`**

```typescript
try {
  await sdk.tokens.deleteTokenMetadata('metadata-123');
  console.log('Token metadata deleted');
} catch (error) {
  if (error.statusCode === 409) {
    console.log('Cannot delete: metadata is used by campaigns/redemptions');
  }
}
```

#### Defined in

[managers/token-manager.ts:443](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/token-manager.ts#L443)

### getTokenService

▸ **getTokenService**(): [`TokenService`](/sdk-reference/classes/tokenservice)

Get the full token SDK for advanced operations

Provides access to the complete TokenSDK instance for advanced blockchain
operations, token balances, transfers, and other operations not covered
by the high-level manager methods.

#### Returns

[`TokenService`](/sdk-reference/classes/tokenservice)

TokenSDK instance with full API access

**`Example`**

```typescript
const tokenSDK = sdk.tokens.getTokenSDK();

// Access token balance operations
const balances = await tokenSDK.getTokenBalances('user-123');

// Access blockchain operations
const web3Operations = tokenSDK.getWeb3Operations();

// Access token API directly
const tokenApi = tokenSDK.api;
```

#### Defined in

[managers/token-manager.ts:470](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/token-manager.ts#L470)

### exportMetadataCSV

▸ **exportMetadataCSV**(`options?`): `Promise`<`Blob`>

Admin: Export token metadata to CSV

Returns a CSV file with all token metadata (rewards/stamps) for the tenant.
Supports date range filtering.

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `options?` | `Object` | Export options (dateFrom, dateTo) |
| `options.dateFrom?` | `string` | - |
| `options.dateTo?` | `string` | - |


#### Returns

`Promise`<`Blob`>

Promise resolving to CSV blob

**`Throws`**

When not authenticated as tenant admin

**`Example`**

```typescript
// Export all token metadata
const csvBlob = await sdk.tokens.exportMetadataCSV();

// Export metadata created in date range
const csvBlob = await sdk.tokens.exportMetadataCSV({
  dateFrom: '2026-01-01',
  dateTo: '2026-06-30'
});

// Download the CSV
const url = URL.createObjectURL(csvBlob);
const a = document.createElement('a');
a.href = url;
a.download = 'token-metadata.csv';
a.click();
```

#### Defined in

[managers/token-manager.ts:507](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/token-manager.ts#L507)

### setTokenMetadataApproval

▸ **setTokenMetadataApproval**(`tokenMetadataId`, `status`, `reason?`): `Promise`<`TokenMetadataDTO`>

Admin: Approve token metadata

Approves token metadata that is pending approval. This operation is only available
when the tenant has token metadata approval enabled in their approval settings.

#### Parameters

| Name | Type | Description |
|  --- | --- | --- |
| `tokenMetadataId` | `string` | ID of the token metadata to approve |
| `status` | `"approved"` | `"rejected"` | - |
| `reason?` | `string` | - |


#### Returns

`Promise`<`TokenMetadataDTO`>

Promise resolving to updated token metadata with approval metadata

**`Throws`**

When not authenticated as tenant admin or token metadata not found

**`Example`**

```ts
`	ypescript
const approved = await sdk.tokens.approveTokenMetadata('metadata-123');
console.log('Token metadata approved at:', approved.approval?.approvedAt);
`
```

#### Defined in

[managers/token-manager.ts:531](https://github.com/eXplorins/PERS-sdks/blob/main/packages/pers-sdk/packages/pers-sdk/src/managers/token-manager.ts#L531)