Get all reward token contracts

PERS-api docs (1.8.2)

Download OpenAPI description

swagger.json

swagger.yaml

Overview

Servers

Mock server

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

https://explorins-loyalty.ngrok.io/

https://api.pers.ninja/v1.8/

Introduction

Introducing PERS (Phygital Experience Rewards System) the ultimate SaaS of Loyalty & Reward System. Connect PERS API to your system and get ready to create multi-projects, with your own dashboard and independent database, while ensuring users data confidentiality. This structure enables:

Interoperable Rewards
Boost Customer Engagement
Simplified Management
Effortless Integration
Security and Privacy
Data-Driven Strategy

Setup Flow

This diagram illustrates the comprehensive flow of creating and connecting various components within the SaaS PERS ecosystem. It outlines the interactions and dependencies between Tokens, Campaigns, Redemptions, Purchase, and Business entities. API Flow

Claim Campaign

The Claim System Flow in SaaS PERS outlines the process through which rewards and tokens can be claimed by different entities within the system. This flow ensures that the claiming process is secure, efficient, and flexible, catering to various use cases and integration requirements. This flow ensures that the process of claiming rewards is adaptable to various scenarios, making it seamless for system administrators, business partners, and end-users to interact with the reward system efficiently.

Tenant

Operations

Token

Operations

Description

The Token module in SaaS PERS is a versatile system enabling users to earn or spend various types of tokens. Tokens can be categorised as Credits, Rewards, or Status. This module ensures seamless management of token transactions, providing a robust foundation for creating engaging reward experiences. It supports multiple token operations, including issuance, balance checks, and redemption, thus facilitating a dynamic and customizable rewards ecosystem. The Token module is designed to be easily integrated into any business model, providing a flexible and scalable solution to enhance customer loyalty and engagement.

ADMIN: Create a new testnet token contract

Request

Create a new testnet token contract for project. This can later be converted into a mainnet version

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""ERC721""ERC1155"

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/token/admin \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "contractAddress": "string",
    "abiUrl": "string",
    "type": "ERC20",
    "decimals": 0
  }'

Responses

Token created

Bodyapplication/json

idstringrequired

Id of the token

contractAddressstringrequired

Address of the token

metadataobject

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""ERC721""ERC1155"

Response

application/json

{
  "id": "string",
  "contractAddress": "string",
  "metadata": {},
  "abi": {},
  "chainId": 0,
  "abiUrl": {},
  "name": "string",
  "symbol": "string",
  "decimals": 0,
  "isActive": true,
  "isGallery": true,
  "type": "ERC20"
}

ADMIN: Create mainnet token Address for existing token

Request

Create mainnet token Address for existing token

Path

idstringrequired

contractAddressstringrequired

chainIdstringrequired

curl -i -X PUT \
  'https://docs.pers.ninja/_mock/swagger/token/admin/{id}/mainnet/{contractAddress}/chain/{chainId}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Mainnet token Address created

Bodyapplication/json

idstringrequired

Id of the token

contractAddressstringrequired

Address of the token

metadataobject

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""ERC721""ERC1155"

Response

application/json

{
  "id": "string",
  "contractAddress": "string",
  "metadata": {},
  "abi": {},
  "chainId": 0,
  "abiUrl": {},
  "name": "string",
  "symbol": "string",
  "decimals": 0,
  "isActive": true,
  "isGallery": true,
  "type": "ERC20"
}

ADMIN: Toggle token active

Request

Toggle token active to be used

Path

idstringrequired

curl -i -X PUT \
  'https://docs.pers.ninja/_mock/swagger/token/admin/{id}/toggle-active' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Token toggled

Bodyapplication/json

idstringrequired

Id of the token

contractAddressstringrequired

Address of the token

metadataobject

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""ERC721""ERC1155"

Response

application/json

{
  "id": "string",
  "contractAddress": "string",
  "metadata": {},
  "abi": {},
  "chainId": 0,
  "abiUrl": {},
  "name": "string",
  "symbol": "string",
  "decimals": 0,
  "isActive": true,
  "isGallery": true,
  "type": "ERC20"
}

ADMIN: Update token

Request

Update token

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/token/admin/{id}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "isGallery": true,
    "name": "string",
    "symbol": "string"
  }'

Responses

Token updates

Bodyapplication/json

idstringrequired

Id of the token

contractAddressstringrequired

Address of the token

metadataobject

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""ERC721""ERC1155"

Response

application/json

{
  "id": "string",
  "contractAddress": "string",
  "metadata": {},
  "abi": {},
  "chainId": 0,
  "abiUrl": {},
  "name": "string",
  "symbol": "string",
  "decimals": 0,
  "isActive": true,
  "isGallery": true,
  "type": "ERC20"
}

ADMIN: Create token metadata

Request

Create token metadata for a specific token contract

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/token/admin/{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

Bodyapplication/json

imageUrlstring

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

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
}

ADMIN: Toggle token metadata active

Request

Toggle token metadata active

Path

idstringrequired

curl -i -X PUT \
  'https://docs.pers.ninja/_mock/swagger/token/admin/metadata/{id}/toggle-active' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Token metadata toggled

Bodyapplication/json

imageUrlstring

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

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
}

ADMIN: Create a new token type

Request

Create a new token type for project

Bodyapplication/jsonrequired

nativeTokenTypestringrequired

Token native Types:

ERC20: used for credits
ERC721: used for stamps and NFTs
ERC1155: used for rewards

Enum"ERC20""ERC721""ERC1155"

namestring

Token type name

imageUrlstring

Token type image url

descriptionstring

Token type description

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

Responses

Token type created

Bodyapplication/json

nativeTokenTypestringrequired

Token native Types:

ERC20: used for credits
ERC721: used for stamps and NFTs
ERC1155: used for rewards

Enum"ERC20""ERC721""ERC1155"

namestring

Token type name

imageUrlstring

Token type image url

descriptionstring

Token type description

Response

application/json

{
  "nativeTokenType": "ERC20",
  "name": "string",
  "imageUrl": "string",
  "description": "string"
}

Get all token types

Request

Get all token types

curl -i -X GET \
  https://docs.pers.ninja/_mock/swagger/token/type \
  -H 'x-project-key: YOUR_API_KEY_HERE'

Responses

Token types

Bodyapplication/jsonArray [

nativeTokenTypestringrequired

Token native Types:

ERC20: used for credits
ERC721: used for stamps and NFTs
ERC1155: used for rewards

Enum"ERC20""ERC721""ERC1155"

namestring

Token type name

imageUrlstring

Token type image url

descriptionstring

Token type description

]

Response

application/json

[
  {
    "nativeTokenType": "ERC20",
    "name": "string",
    "imageUrl": "string",
    "description": "string"
  }
]

Get token by address

Request

Get token by contract address

Path

contractAddressstringrequired

Query

contractTokenIdstring

Token ID for ERC721 or ERC1155 tokens

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

Responses

Token

Bodyapplication/json

idstringrequired

Id of the token

contractAddressstringrequired

Address of the token

metadataobject

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""ERC721""ERC1155"

Response

application/json

{
  "id": "string",
  "contractAddress": "string",
  "metadata": {},
  "abi": {},
  "chainId": 0,
  "abiUrl": {},
  "name": "string",
  "symbol": "string",
  "decimals": 0,
  "isActive": true,
  "isGallery": true,
  "type": "ERC20"
}

Get all token contracts

Request

Get all token contracts

Query

activestring

Filter for active tokens only (default: true)

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

Responses

Tokens

Bodyapplication/jsonArray [

idstringrequired

Id of the token

contractAddressstringrequired

Address of the token

metadataobject

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""ERC721""ERC1155"

]

Response

application/json

[
  {
    "id": "string",
    "contractAddress": "string",
    "metadata": {},
    "abi": {},
    "chainId": 0,
    "abiUrl": {},
    "name": "string",
    "symbol": "string",
    "decimals": 0,
    "isActive": true,
    "isGallery": true,
    "type": "ERC20"
  }
]

Get active credit token contracts

Request

Get active credit token contracts

curl -i -X GET \
  https://docs.pers.ninja/_mock/swagger/token/credit \
  -H 'x-project-key: YOUR_API_KEY_HERE'

Responses

Credit token

Bodyapplication/json

idstringrequired

Id of the token

contractAddressstringrequired

Address of the token

metadataobject

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""ERC721""ERC1155"

Response

application/json

{
  "id": "string",
  "contractAddress": "string",
  "metadata": {},
  "abi": {},
  "chainId": 0,
  "abiUrl": {},
  "name": "string",
  "symbol": "string",
  "decimals": 0,
  "isActive": true,
  "isGallery": true,
  "type": "ERC20"
}

Get all reward token contracts

Request

Get all reward token contracts

Query

activestring

Filter for active reward tokens only (default: true)

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

Responses

Reward tokens

Bodyapplication/jsonArray [

idstringrequired

Id of the token

contractAddressstringrequired

Address of the token

metadataobject

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""ERC721""ERC1155"

]

Response

application/json

[
  {
    "id": "string",
    "contractAddress": "string",
    "metadata": {},
    "abi": {},
    "chainId": 0,
    "abiUrl": {},
    "name": "string",
    "symbol": "string",
    "decimals": 0,
    "isActive": true,
    "isGallery": true,
    "type": "ERC20"
  }
]

Get all status token contracts

Request

Get all status token contracts

Query

activestring

Filter for active status tokens only (default: true)

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

Responses

Status tokens

Bodyapplication/jsonArray [

idstringrequired

Id of the token

contractAddressstringrequired

Address of the token

metadataobject

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""ERC721""ERC1155"

]

Response

application/json

[
  {
    "id": "string",
    "contractAddress": "string",
    "metadata": {},
    "abi": {},
    "chainId": 0,
    "abiUrl": {},
    "name": "string",
    "symbol": "string",
    "decimals": 0,
    "isActive": true,
    "isGallery": true,
    "type": "ERC20"
  }
]

Campaign

Operations

Redemption

Operations

Purchase

Operations

Business

Operations

Transaction

Operations

User

User endpoints

Operations

Admin

Operations

Auth

Operations

Web3 Contract

Operations

Web3 Chain

Operations

Root

Operations

Balance

Operations

File

Operations

PERS-api docs (1.8.2)

Introduction

Setup Flow

Claim Campaign

Tenant

Token

Description

ADMIN: Create a new testnet token contract

Request

Responses

Was this helpful?

ADMIN: Create mainnet token Address for existing token

Request

Responses

Was this helpful?

ADMIN: Toggle token active

Request

Responses

Was this helpful?

ADMIN: Update token

Request

Responses

Was this helpful?

ADMIN: Create token metadata

Request

Responses

Was this helpful?

ADMIN: Toggle token metadata active

Request

Responses

Was this helpful?

ADMIN: Create a new token type

Request

Responses

Was this helpful?

Get all token types

Request

Responses

Was this helpful?

Get token by address

Request

Responses

Was this helpful?

Get all token contracts

Request

Responses

Was this helpful?

Get active credit token contracts

Request

Responses

Was this helpful?

Get all reward token contracts

Request

Responses

Was this helpful?

Get all status token contracts

Request

Responses

Was this helpful?

Campaign

Redemption

Purchase

Business

Transaction

User

Admin

Auth

Web3 Contract

Web3 Chain

Root

Balance

File