Skip to content
Download OpenAPI description
Overview
Languages
Servers
Mock server

https://docs.pers.ninja/_mock/swagger/

https://api.pers.ninja/v2/

Operations
Operations
Operations

Token Management System

Token system for PERS loyalty platform managing various token types including Credits, Rewards, and Status tokens. Provides comprehensive token lifecycle management from creation to redemption.
**Token Operations:**

• **Token Creation:** Define custom token types with specific properties and rules

• **Token Distribution:** Mint and distribute tokens to users through campaigns

• **Balance Management:** Track token balances across user accounts

• **Token Transfer:** Enable token transfers between users when configured

• **Token Burning:** Remove tokens from circulation for deflationary mechanics ![Token Module](https://s3.eu-west-1.amazonaws.com/pers.assets.prod/tenant/a0df6ebf-51cc-4c18-afcd-0de355c250dc_DemoApp_eXplorins/Documentation/Tokens_image.png)

Request

Retrieve all token contracts for the project. Only admins can access inactive tokens via ?active=false parameter.

Security
projectKey
Query
activestring

Filter for active tokens only (default: true). Non-admin users always get active tokens only.

curl -i -X GET \
  'https://docs.pers.ninja/_mock/swagger/tokens?active=string' \
  -H 'x-project-key: YOUR_API_KEY_HERE'

Responses

Tokens retrieved successfully

Bodyapplication/jsonArray [
idstringrequired

Id of the token

contractAddressstringrequired

Address of the token

metadataArray of objects(TokenMetadataDTO)

Metadata of the token, this is optional and can be null in case of Point token

abiobjectrequired

this is the abi of the contract, this is the interface of the contract to interact with it

chainIdnumberrequired

this is the chain id of the chain where the token is deployed

abiUrlobjectrequired

this is the url of the abi of the contract, to be used to fetch the abi of the contract

namestring

this is the name of the token contract

symbolstring

this is the symbol of the token contract, this is optional and can be null

decimalsnumber

this is the decimals of the token. This is optional and only used for ERC20 tokens (Points)

isActivebooleanrequired

This can be used to enable or disable the token

isGallerybooleanrequired

This can be used to enable or disable the token for gallery

typestringrequired

This is the underlying web3 native type of the token contract

Enum"ERC20""ERC1155""ERC721"
]
Response
application/json
[ { "id": "string", "contractAddress": "string", "metadata": [ … ], "abi": {}, "chainId": 0, "abiUrl": {}, "name": "string", "symbol": "string", "decimals": 0, "isActive": true, "isGallery": true, "type": "ERC20" } ]

Request

ADMIN: Create a new testnet token contract for the project. This can later be converted to mainnet.

Security
tenantAdminJWT
Bodyapplication/jsonrequired
contractAddressstringrequired

Contract address is the address of the token contract on chain.

abiUrlstring

The ABI URL is the URL to the contract ABI. This is an optional field. If not provided, the contract ABI will be fetched from PERS instance depending on selected token type.

typestringrequired
Enum"ERC20""ERC1155""ERC721"
decimalsnumber

Decimals is the number of decimals the token uses. This is useful for ERC20 tokens.

curl -i -X POST \
  https://docs.pers.ninja/_mock/swagger/tokens \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "contractAddress": "string",
    "abiUrl": "string",
    "type": "ERC20",
    "decimals": 0
  }'

Responses

Token created successfully

Bodyapplication/json
idstringrequired

Id of the token

contractAddressstringrequired

Address of the token

metadataArray of objects(TokenMetadataDTO)

Metadata of the token, this is optional and can be null in case of Point token

abiobjectrequired

this is the abi of the contract, this is the interface of the contract to interact with it

chainIdnumberrequired

this is the chain id of the chain where the token is deployed

abiUrlobjectrequired

this is the url of the abi of the contract, to be used to fetch the abi of the contract

namestring

this is the name of the token contract

symbolstring

this is the symbol of the token contract, this is optional and can be null

decimalsnumber

this is the decimals of the token. This is optional and only used for ERC20 tokens (Points)

isActivebooleanrequired

This can be used to enable or disable the token

isGallerybooleanrequired

This can be used to enable or disable the token for gallery

typestringrequired

This is the underlying web3 native type of the token contract

Enum"ERC20""ERC1155""ERC721"
Response
application/json
{ "id": "string", "contractAddress": "string", "metadata": [ { … } ], "abi": {}, "chainId": 0, "abiUrl": {}, "name": "string", "symbol": "string", "decimals": 0, "isActive": true, "isGallery": true, "type": "ERC20" }

Request

Retrieve token information by contract address

Security
projectKey
Path
contractAddressstringrequired
Query
contractTokenIdstring

Token ID for ERC721 or ERC1155 tokens

curl -i -X GET \
  'https://docs.pers.ninja/_mock/swagger/tokens/address/{contractAddress}?contractTokenId=string' \
  -H 'x-project-key: YOUR_API_KEY_HERE'

Responses

Token retrieved successfully

Bodyapplication/json
idstringrequired

Id of the token

contractAddressstringrequired

Address of the token

metadataArray of objects(TokenMetadataDTO)

Metadata of the token, this is optional and can be null in case of Point token

abiobjectrequired

this is the abi of the contract, this is the interface of the contract to interact with it

chainIdnumberrequired

this is the chain id of the chain where the token is deployed

abiUrlobjectrequired

this is the url of the abi of the contract, to be used to fetch the abi of the contract

namestring

this is the name of the token contract

symbolstring

this is the symbol of the token contract, this is optional and can be null

decimalsnumber

this is the decimals of the token. This is optional and only used for ERC20 tokens (Points)

isActivebooleanrequired

This can be used to enable or disable the token

isGallerybooleanrequired

This can be used to enable or disable the token for gallery

typestringrequired

This is the underlying web3 native type of the token contract

Enum"ERC20""ERC1155""ERC721"
Response
application/json
{ "id": "string", "contractAddress": "string", "metadata": [ { … } ], "abi": {}, "chainId": 0, "abiUrl": {}, "name": "string", "symbol": "string", "decimals": 0, "isActive": true, "isGallery": true, "type": "ERC20" }

Request

Retrieve the active point token contract for the project

Security
projectKey
curl -i -X GET \
  https://docs.pers.ninja/_mock/swagger/tokens/points \
  -H 'x-project-key: YOUR_API_KEY_HERE'

Responses

Point token retrieved successfully

Bodyapplication/json
idstringrequired

Id of the token

contractAddressstringrequired

Address of the token

metadataArray of objects(TokenMetadataDTO)

Metadata of the token, this is optional and can be null in case of Point token

abiobjectrequired

this is the abi of the contract, this is the interface of the contract to interact with it

chainIdnumberrequired

this is the chain id of the chain where the token is deployed

abiUrlobjectrequired

this is the url of the abi of the contract, to be used to fetch the abi of the contract

namestring

this is the name of the token contract

symbolstring

this is the symbol of the token contract, this is optional and can be null

decimalsnumber

this is the decimals of the token. This is optional and only used for ERC20 tokens (Points)

isActivebooleanrequired

This can be used to enable or disable the token

isGallerybooleanrequired

This can be used to enable or disable the token for gallery

typestringrequired

This is the underlying web3 native type of the token contract

Enum"ERC20""ERC1155""ERC721"
Response
application/json
{ "id": "string", "contractAddress": "string", "metadata": [ { … } ], "abi": {}, "chainId": 0, "abiUrl": {}, "name": "string", "symbol": "string", "decimals": 0, "isActive": true, "isGallery": true, "type": "ERC20" }

Request

Retrieve all reward token contracts (ERC1155 tokens). Only admins can access inactive tokens via ?active=false parameter.

Security
projectKey
Query
activestring

Filter for active reward tokens only (default: true). Non-admin users always get active tokens only.

curl -i -X GET \
  'https://docs.pers.ninja/_mock/swagger/tokens/rewards?active=string' \
  -H 'x-project-key: YOUR_API_KEY_HERE'

Responses

Reward tokens retrieved successfully

Bodyapplication/jsonArray [
idstringrequired

Id of the token

contractAddressstringrequired

Address of the token

metadataArray of objects(TokenMetadataDTO)

Metadata of the token, this is optional and can be null in case of Point token

abiobjectrequired

this is the abi of the contract, this is the interface of the contract to interact with it

chainIdnumberrequired

this is the chain id of the chain where the token is deployed

abiUrlobjectrequired

this is the url of the abi of the contract, to be used to fetch the abi of the contract

namestring

this is the name of the token contract

symbolstring

this is the symbol of the token contract, this is optional and can be null

decimalsnumber

this is the decimals of the token. This is optional and only used for ERC20 tokens (Points)

isActivebooleanrequired

This can be used to enable or disable the token

isGallerybooleanrequired

This can be used to enable or disable the token for gallery

typestringrequired

This is the underlying web3 native type of the token contract

Enum"ERC20""ERC1155""ERC721"
]
Response
application/json
[ { "id": "string", "contractAddress": "string", "metadata": [ … ], "abi": {}, "chainId": 0, "abiUrl": {}, "name": "string", "symbol": "string", "decimals": 0, "isActive": true, "isGallery": true, "type": "ERC20" } ]

Request

Retrieve all stamp token contracts (ERC721 tokens). Only admins can access inactive tokens via ?active=false parameter.

Security
projectKey
Query
activestring

Filter for active stamp tokens only (default: true). Non-admin users always get active tokens only.

curl -i -X GET \
  'https://docs.pers.ninja/_mock/swagger/tokens/stamps?active=string' \
  -H 'x-project-key: YOUR_API_KEY_HERE'

Responses

Stamp tokens retrieved successfully

Bodyapplication/jsonArray [
idstringrequired

Id of the token

contractAddressstringrequired

Address of the token

metadataArray of objects(TokenMetadataDTO)

Metadata of the token, this is optional and can be null in case of Point token

abiobjectrequired

this is the abi of the contract, this is the interface of the contract to interact with it

chainIdnumberrequired

this is the chain id of the chain where the token is deployed

abiUrlobjectrequired

this is the url of the abi of the contract, to be used to fetch the abi of the contract

namestring

this is the name of the token contract

symbolstring

this is the symbol of the token contract, this is optional and can be null

decimalsnumber

this is the decimals of the token. This is optional and only used for ERC20 tokens (Points)

isActivebooleanrequired

This can be used to enable or disable the token

isGallerybooleanrequired

This can be used to enable or disable the token for gallery

typestringrequired

This is the underlying web3 native type of the token contract

Enum"ERC20""ERC1155""ERC721"
]
Response
application/json
[ { "id": "string", "contractAddress": "string", "metadata": [ … ], "abi": {}, "chainId": 0, "abiUrl": {}, "name": "string", "symbol": "string", "decimals": 0, "isActive": true, "isGallery": true, "type": "ERC20" } ]

Request

Retrieve all available token types for the project

Security
projectKey
curl -i -X GET \
  https://docs.pers.ninja/_mock/swagger/tokens/types \
  -H 'x-project-key: YOUR_API_KEY_HERE'

Responses

Token types retrieved successfully

Bodyapplication/jsonArray [
nativeTokenTypestringrequired

Token native Types: - ERC20: used for credits - ERC721: used for stamps and NFTs - ERC1155: used for rewards

Enum"ERC20""ERC1155""ERC721"
namestring

Token type name

imageUrlstring

Token type image url

descriptionstring

Token type description

]
Response
application/json
[ { "nativeTokenType": "ERC20", "name": "string", "imageUrl": "string", "description": "string" } ]

Request

ADMIN: Create a new token type for the project

Security
tenantAdminJWT
Bodyapplication/jsonrequired
nativeTokenTypestringrequired

Token native Types: - ERC20: used for credits - ERC721: used for stamps and NFTs - ERC1155: used for rewards

Enum"ERC20""ERC1155""ERC721"
namestring

Token type name

imageUrlstring

Token type image url

descriptionstring

Token type description

curl -i -X POST \
  https://docs.pers.ninja/_mock/swagger/tokens/types \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "nativeTokenType": "ERC20",
    "name": "string",
    "imageUrl": "string",
    "description": "string"
  }'

Responses

Token type created successfully

Bodyapplication/json
nativeTokenTypestringrequired

Token native Types: - ERC20: used for credits - ERC721: used for stamps and NFTs - ERC1155: used for rewards

Enum"ERC20""ERC1155""ERC721"
namestring

Token type name

imageUrlstring

Token type image url

descriptionstring

Token type description

Response
application/json
{ "nativeTokenType": "ERC20", "name": "string", "imageUrl": "string", "description": "string" }

Request

ADMIN: Update token contract information

Security
tenantAdminJWT
Path
idstringrequired
Bodyapplication/jsonrequired
isGalleryboolean

This indicates if token should be included as a gallery. This is useful for ERC721 or ERC1155 tokens.

namestring

The name of the token

symbolstring

The symbol of the token

curl -i -X PUT \
  'https://docs.pers.ninja/_mock/swagger/tokens/{id}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "isGallery": true,
    "name": "string",
    "symbol": "string"
  }'

Responses

Token updated successfully

Bodyapplication/json
idstringrequired

Id of the token

contractAddressstringrequired

Address of the token

metadataArray of objects(TokenMetadataDTO)

Metadata of the token, this is optional and can be null in case of Point token

abiobjectrequired

this is the abi of the contract, this is the interface of the contract to interact with it

chainIdnumberrequired

this is the chain id of the chain where the token is deployed

abiUrlobjectrequired

this is the url of the abi of the contract, to be used to fetch the abi of the contract

namestring

this is the name of the token contract

symbolstring

this is the symbol of the token contract, this is optional and can be null

decimalsnumber

this is the decimals of the token. This is optional and only used for ERC20 tokens (Points)

isActivebooleanrequired

This can be used to enable or disable the token

isGallerybooleanrequired

This can be used to enable or disable the token for gallery

typestringrequired

This is the underlying web3 native type of the token contract

Enum"ERC20""ERC1155""ERC721"
Response
application/json
{ "id": "string", "contractAddress": "string", "metadata": [ { … } ], "abi": {}, "chainId": 0, "abiUrl": {}, "name": "string", "symbol": "string", "decimals": 0, "isActive": true, "isGallery": true, "type": "ERC20" }

Request

ADMIN: Toggle token active status to enable/disable usage

Security
tenantAdminJWT
Path
idstringrequired
curl -i -X PUT \
  'https://docs.pers.ninja/_mock/swagger/tokens/{id}/status' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Token status updated successfully

Bodyapplication/json
idstringrequired

Id of the token

contractAddressstringrequired

Address of the token

metadataArray of objects(TokenMetadataDTO)

Metadata of the token, this is optional and can be null in case of Point token

abiobjectrequired

this is the abi of the contract, this is the interface of the contract to interact with it

chainIdnumberrequired

this is the chain id of the chain where the token is deployed

abiUrlobjectrequired

this is the url of the abi of the contract, to be used to fetch the abi of the contract

namestring

this is the name of the token contract

symbolstring

this is the symbol of the token contract, this is optional and can be null

decimalsnumber

this is the decimals of the token. This is optional and only used for ERC20 tokens (Points)

isActivebooleanrequired

This can be used to enable or disable the token

isGallerybooleanrequired

This can be used to enable or disable the token for gallery

typestringrequired

This is the underlying web3 native type of the token contract

Enum"ERC20""ERC1155""ERC721"
Response
application/json
{ "id": "string", "contractAddress": "string", "metadata": [ { … } ], "abi": {}, "chainId": 0, "abiUrl": {}, "name": "string", "symbol": "string", "decimals": 0, "isActive": true, "isGallery": true, "type": "ERC20" }

Request

ADMIN: Associate mainnet contract address with existing testnet token

Security
tenantAdminJWT
Path
idstringrequired
Bodyapplication/jsonrequired
contractAddressstringrequired

Mainnet contract address

chainIdnumberrequired

Chain ID for the mainnet contract

curl -i -X PUT \
  'https://docs.pers.ninja/_mock/swagger/tokens/{id}/mainnet' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "contractAddress": "string",
    "chainId": 0
  }'

Responses

Mainnet contract address set successfully

Bodyapplication/json
idstringrequired

Id of the token

contractAddressstringrequired

Address of the token

metadataArray of objects(TokenMetadataDTO)

Metadata of the token, this is optional and can be null in case of Point token

abiobjectrequired

this is the abi of the contract, this is the interface of the contract to interact with it

chainIdnumberrequired

this is the chain id of the chain where the token is deployed

abiUrlobjectrequired

this is the url of the abi of the contract, to be used to fetch the abi of the contract

namestring

this is the name of the token contract

symbolstring

this is the symbol of the token contract, this is optional and can be null

decimalsnumber

this is the decimals of the token. This is optional and only used for ERC20 tokens (Points)

isActivebooleanrequired

This can be used to enable or disable the token

isGallerybooleanrequired

This can be used to enable or disable the token for gallery

typestringrequired

This is the underlying web3 native type of the token contract

Enum"ERC20""ERC1155""ERC721"
Response
application/json
{ "id": "string", "contractAddress": "string", "metadata": [ { … } ], "abi": {}, "chainId": 0, "abiUrl": {}, "name": "string", "symbol": "string", "decimals": 0, "isActive": true, "isGallery": true, "type": "ERC20" }

Request

ADMIN: Create metadata for a specific token contract

Security
tenantAdminJWT
Path
idstringrequired
Bodyapplication/jsonrequired
imageUrlstring

This is the URL to the image of the item. Can be just about any type of image (including SVGs, which will be cached into PNGs by OpenSea), IPFS or Arweave URLs or paths. We recommend using a minimum 3000 x 3000 image.

externalUrlstring

This is the URL that will appear below the asset's image

descriptionstring

A human-readable description of the item. Markdown is supported.

namestring

Name of the item.

expiryDatestring(date-time)

expiry date in case of an utility reward

animationUrlstring

A URL to a multi-media attachment for the item. The file extensions GLTF, GLB, WEBM, MP4, M4V, OGV, and OGG are supported, along with the audio-only extensions MP3, WAV, and OGA. Animation_url also supports HTML pages, allowing you to build rich experiences and interactive NFTs using JavaScript canvas, WebGL, and more. Scripts and relative paths within the HTML page are now supported. However, access to browser extensions is not supported.

youtubeUrlstring

A URL to a YouTube video (only used if animation_url is not provide

creatorAccountAddressstring

Creator Address

previewUrlstring

Preview Url

curl -i -X POST \
  'https://docs.pers.ninja/_mock/swagger/tokens/{id}/metadata' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "imageUrl": "string",
    "externalUrl": "string",
    "description": "string",
    "name": "string",
    "expiryDate": "2019-08-24T14:15:22Z",
    "animationUrl": "string",
    "youtubeUrl": "string",
    "creatorAccountAddress": "string",
    "previewUrl": "string"
  }'

Responses

Token metadata created successfully

Bodyapplication/json
imageUrlstring

This is the URL to the image of the item. Can be just about any type of image (including SVGs, which will be cached into PNGs by OpenSea), IPFS or Arweave URLs or paths. We recommend using a minimum 3000 x 3000 image.

externalUrlstring

This is the URL that will appear below the asset's image

descriptionstring

A human-readable description of the item. Markdown is supported.

namestring

Name of the item.

expiryDatestring(date-time)

expiry date in case of an utility reward

animationUrlstring

A URL to a multi-media attachment for the item. The file extensions GLTF, GLB, WEBM, MP4, M4V, OGV, and OGG are supported, along with the audio-only extensions MP3, WAV, and OGA. Animation_url also supports HTML pages, allowing you to build rich experiences and interactive NFTs using JavaScript canvas, WebGL, and more. Scripts and relative paths within the HTML page are now supported. However, access to browser extensions is not supported.

youtubeUrlstring

A URL to a YouTube video (only used if animation_url is not provide

creatorAccountAddressstring

Creator Address

previewUrlstring

Preview Url

idstringrequired

Token Metadata id

animationWeb3StorageUrlstring

web3 storage url for the animation file

imageWeb3StorageUrlstring

web3 storage url for the image

web3StorageUrlstring

Storage Url

tokenMetadataIncrementalIdnumberrequired

Token Metadata Incremental Id

isActivebooleanrequired

Is active

Response
application/json
{ "imageUrl": "string", "externalUrl": "string", "description": "string", "name": "string", "expiryDate": "2019-08-24T14:15:22Z", "animationUrl": "string", "youtubeUrl": "string", "creatorAccountAddress": "string", "previewUrl": "string", "id": "string", "animationWeb3StorageUrl": "string", "imageWeb3StorageUrl": "string", "web3StorageUrl": "string", "tokenMetadataIncrementalId": 0, "isActive": true }

Request

ADMIN: Toggle token metadata active status

Security
tenantAdminJWT
Path
idstringrequired
curl -i -X PUT \
  'https://docs.pers.ninja/_mock/swagger/tokens/metadata/{id}/status' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Token metadata status updated successfully

Bodyapplication/json
imageUrlstring

This is the URL to the image of the item. Can be just about any type of image (including SVGs, which will be cached into PNGs by OpenSea), IPFS or Arweave URLs or paths. We recommend using a minimum 3000 x 3000 image.

externalUrlstring

This is the URL that will appear below the asset's image

descriptionstring

A human-readable description of the item. Markdown is supported.

namestring

Name of the item.

expiryDatestring(date-time)

expiry date in case of an utility reward

animationUrlstring

A URL to a multi-media attachment for the item. The file extensions GLTF, GLB, WEBM, MP4, M4V, OGV, and OGG are supported, along with the audio-only extensions MP3, WAV, and OGA. Animation_url also supports HTML pages, allowing you to build rich experiences and interactive NFTs using JavaScript canvas, WebGL, and more. Scripts and relative paths within the HTML page are now supported. However, access to browser extensions is not supported.

youtubeUrlstring

A URL to a YouTube video (only used if animation_url is not provide

creatorAccountAddressstring

Creator Address

previewUrlstring

Preview Url

idstringrequired

Token Metadata id

animationWeb3StorageUrlstring

web3 storage url for the animation file

imageWeb3StorageUrlstring

web3 storage url for the image

web3StorageUrlstring

Storage Url

tokenMetadataIncrementalIdnumberrequired

Token Metadata Incremental Id

isActivebooleanrequired

Is active

Response
application/json
{ "imageUrl": "string", "externalUrl": "string", "description": "string", "name": "string", "expiryDate": "2019-08-24T14:15:22Z", "animationUrl": "string", "youtubeUrl": "string", "creatorAccountAddress": "string", "previewUrl": "string", "id": "string", "animationWeb3StorageUrl": "string", "imageWeb3StorageUrl": "string", "web3StorageUrl": "string", "tokenMetadataIncrementalId": 0, "isActive": true }
Operations
Operations
Operations
Operations
Operations
Operations
Operations
Operations
Operations
Operations
Operations
Operations
Operations
Operations
Operations
Operations
Operations