Skip to content

PERS-api Documentation (2.0.12)

PERS API Documentation

This RESTful API enables seamless integration of Web3 loyalty, token management, and engagement features into your applications.

Usage Guidelines:

  • RESTful Design: Resources are accessed via standard HTTP methods (GET, POST, PUT, DELETE) with predictable, resource-oriented URLs.
  • Authentication: Secure access is enforced via Bearer Tokens (JWT) and Project Keys (defining the Tenant context).
  • Data Format: All requests and responses utilize standard JSON formatting.

Explore the modules below for detailed endpoint specifications, schemas, and testing capabilities.

Download OpenAPI description
swagger.json
swagger.yaml
Overview
Languages
Servers
Mock server
https://docs.pers.ninja/_mock/swagger
Production API
https://api.pers.ninja/v2

Tenants

Operations

Admins

Operations

Tokens

Operations

Campaigns

Operations

Campaign Tags

Operations

Campaign Tokens

Operations

Campaign Triggers

Operations

Campaign Engagements

Operations

Campaign Claims

Operations

Redemptions

Operations

Purchases

Operations

Businesses

Operations

Transactions

Operations

Users

Operations

Balances

Operations

Files

Operations

Web3 Chains

Operations

Smart Contract Management

Smart contract deployment and interaction management for blockchain-based loyalty operations. Handles contract lifecycle and blockchain integration.
Contract Operations:

•
Contract Deployment:
Deploy loyalty-related smart contracts to blockchain networks

•
Contract Interaction:
Execute smart contract functions for token operations

•
Contract Monitoring:
Track contract events and transaction confirmations

•
Contract Upgrades:
Manage contract versioning and upgrade procedures

•
Multi-Chain Contracts:
Deploy and manage contracts across multiple blockchains

Create a new Web3 contract (Admin)

Request

Create a new Web3 contract with administrative privileges. Requires tenant admin access. Replaces POST /contract

Security
authJWT
Bodyapplication/jsonrequired
implementationAddressstring

this is implementation address, the address of the contract that is being used as implementation for the proxy. This is only used for proxy contracts

contractAddressstringrequired

this is the address of the contract

ownerAddressstring

this is the address of the owner of the contract

factoryAddressstring or null

this is the address of the factory contract that deploys this contract

Example: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
chainIdnumberrequired

this is the chain id of the contract

contractVersionstring

this is the version of the contract

contractTypestringrequired

this is the type of the contract

Enum"SMART_WALLET_FACTORY""SMART_WALLET_IMPLEMENTATION""SMART_WALLET_PROXY""COUNTERFACTUAL_WALLET_FACTORY""COUNTERFACTUAL_WALLET_IMPLEMENTATION""COUNTERFACTUAL_WALLET_PROXY""TOKEN_CONTRACT"
nativeTokenTypestring or nullrequired

this is the native token type of the contract, this is only used for native tokens

Enum"ERC20""ERC1155""ERC721"
saltstring

this is the salt of the contract, this is only used for proxy contract factories to generate unique contracts

txHashstring or null

this is the transaction hash of the contract deployment, this is only used for deployed contracts

Example: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
isProxybooleanrequired

this is the flag to check if the contract is a proxy contract

abiUrlstring

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

deploymentStatusstringrequired

current deployment status of the contract

Enum"COMPUTED""DEPLOYED""FAILED"
curl -i -X POST \
  https://docs.pers.ninja/_mock/swagger/contracts \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "implementationAddress": "string",
    "contractAddress": "string",
    "ownerAddress": "string",
    "factoryAddress": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "chainId": 0,
    "contractVersion": "string",
    "contractType": "SMART_WALLET_FACTORY",
    "nativeTokenType": "ERC20",
    "salt": "string",
    "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "isProxy": true,
    "abiUrl": "string",
    "deploymentStatus": "COMPUTED"
  }'

Responses

Contract created successfully

Bodyapplication/json
implementationAddressstring

this is implementation address, the address of the contract that is being used as implementation for the proxy. This is only used for proxy contracts

contractAddressstringrequired

this is the address of the contract

ownerAddressstring

this is the address of the owner of the contract

factoryAddressstring or null

this is the address of the factory contract that deploys this contract

Example: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
chainIdnumberrequired

this is the chain id of the contract

contractVersionstring

this is the version of the contract

contractTypestringrequired

this is the type of the contract

Enum"SMART_WALLET_FACTORY""SMART_WALLET_IMPLEMENTATION""SMART_WALLET_PROXY""COUNTERFACTUAL_WALLET_FACTORY""COUNTERFACTUAL_WALLET_IMPLEMENTATION""COUNTERFACTUAL_WALLET_PROXY""TOKEN_CONTRACT"
nativeTokenTypestring or nullrequired

this is the native token type of the contract, this is only used for native tokens

Enum"ERC20""ERC1155""ERC721"
saltstring

this is the salt of the contract, this is only used for proxy contract factories to generate unique contracts

txHashstring or null

this is the transaction hash of the contract deployment, this is only used for deployed contracts

Example: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
isProxybooleanrequired

this is the flag to check if the contract is a proxy contract

abiUrlstring

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

deploymentStatusstringrequired

current deployment status of the contract

Enum"COMPUTED""DEPLOYED""FAILED"
idstringrequired

this is the id of the contract

abiobjectrequired

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

tenantIdobjectrequired

this is the tenant id of the contract, this can be null for generic contracts

Response
application/json
{
  "implementationAddress": "string",
  "contractAddress": "string",
  "ownerAddress": "string",
  "factoryAddress": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "chainId": 0,
  "contractVersion": "string",
  "contractType": "SMART_WALLET_FACTORY",
  "nativeTokenType": "ERC20",
  "salt": "string",
  "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "isProxy": true,
  "abiUrl": "string",
  "deploymentStatus": "COMPUTED",
  "id": "string",
  "abi": {},
  "tenantId": {}
}

Auth

Operations

Root

Operations

Well-known

Operations

Trigger Sources

Operations

Business Types

Operations

Redemption Types

Operations

Redemption Redeems

Operations

Redemption Tokens

Operations

API Keys

Operations