Skip to content

PERS-api docs (2.0.7)

Download OpenAPI description
swagger.json
swagger.yaml
Overview
Languages
Servers
Mock server
https://docs.pers.ninja/_mock/swagger/
https://explorins-loyalty.ngrok.io/
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

Transaction Management System

Comprehensive transaction management for credits and tokens with secure processing and real-time balance updates. Handles all operations within the loyalty platform.
Transaction Operations:

•
Token Minting:
Create new tokens and add to user accounts

•
Token Transfers:
Secure peer-to-peer token transfers between users

•
Token Burning:
Remove tokens from circulation with proper audit trails

•
Balance Queries:
Real-time balance checks across multiple token types

•
Transaction Authorization:
Verify user permissions and sufficient balances

•
Transaction History:
Complete audit logs for all operations

Get current user / business sent transactions

Request

Convenience endpoint for user / business sent transactions. Internally uses the unified /transactions endpoint with role=SENDER filter.

Security
projectKey or authJWT
curl -i -X GET \
  https://docs.pers.ninja/_mock/swagger/transactions/me/sent \
  -H 'x-project-key: YOUR_API_KEY_HERE'

Responses

Get current user / business received transactions

Request

Convenience endpoint for user / business received transactions. Internally uses the unified /transactions endpoint with role=RECIPIENT filter.

Security
projectKey or authJWT
curl -i -X GET \
  https://docs.pers.ninja/_mock/swagger/transactions/me/received \
  -H 'x-project-key: YOUR_API_KEY_HERE'

Responses

Get all transactions with advanced filtering

Request

Get transactions with comprehensive filtering options: - participantId: Filter by user/business/tenant ID - role: Filter by SENDER, RECIPIENT, or both (omit for all) - status: Filter by transaction status - tokenType: Filter by token type - Standard pagination parameters supported

Security
authJWT
Query
participantIdstring
rolestring
Enum"SENDER""RECIPIENT"
statusstring
Enum"created""processing""pending_signature""broadcasted""succeeded""failed""cancelled""expired"
tokenTypestring
pagenumber

Page number (1-based)

limitnumber

Items per page

sortBystring

Sort field

sortOrderstring

Sort order

Enum"ASC""DESC"
curl -i -X GET \
  'https://docs.pers.ninja/_mock/swagger/transactions?participantId=string&role=SENDER&status=created&tokenType=string&page=0&limit=0&sortBy=string&sortOrder=ASC' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Create transaction

Request

Create any type of transaction (MINT/TRANSFER/BURN) using role-based trigger detection. Sender will be determined based on the authentication context or provided explicitly (Pending verification). Depending on transaction type and signing context will either return a prepared transaction for client-side signing or execute server-side directly.

Security
authJWT
Bodyapplication/jsonrequired
web3TransactionTypestringrequired

Transaction type for easier detection and routing

Enum"MINT""TRANSFER""BURN"
Example: "TRANSFER"
senderobject
recipientobject
tokenobject
amountnumberrequired

Transaction amount

Example: 100
curl -i -X POST \
  https://docs.pers.ninja/_mock/swagger/transactions \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "web3TransactionType": "TRANSFER",
    "sender": {
      "accountId": "user123",
      "accountType": "user",
      "accountAddress": "0x742d35Cc5dB3dC0F0e8f0b0d2fA0c3fA2ed5D0f8"
    },
    "recipient": {
      "accountId": "user123",
      "accountType": "user",
      "accountAddress": "0x742d35Cc5dB3dC0F0e8f0b0d2fA0c3fA2ed5D0f8"
    },
    "token": {
      "tokenDbId": "uuid-12345-67890",
      "contractAddress": "0x742d35Cc5dB3dC0F0e8f0b0d2fA0c3fA2ed5D0f8",
      "contractTokenId": "721",
      "chainId": 1
    },
    "amount": 100
  }'

Responses

transaction created

Bodyapplication/json
transactionobjectrequired
transaction.​amountnumberrequired

Transaction amount

transaction.​idstringrequired

Transaction id

transaction.​tokenAddressstringrequired

Transaction token address

transaction.​contractTokenIdobject or nullrequired

Transaction token contract id, this is the blockchain contract id of the token

transaction.​tokenTypestringrequired

Transaction token type

transaction.​senderAddressstringrequired

Sender address

transaction.​recipientAddressobjectrequired

Recipient address

transaction.​transactionHashobjectrequired

Transaction hash

transaction.​typestringrequired

Transaction type

Enum"MINT""TRANSFER""BURN"
transaction.​triggerProcessTypestringrequired

Trigger process type

Enum"PURCHASE""SPEND""TRANSFER""EARN""CAMPAIGN_USER_CLAIM""CAMPAIGN_SYSTEM_CLAIM""CAMPAIGN_BUSINESS_CLAIM""REDEMPTION_SPEND""REDEMPTION_RECEIVE""MIGRATION"
transaction.​triggerProcessIdobjectrequired

Trigger process id, this is the id of the entity that triggered the transaction if applicable (e.g. CampaignUserClaim id)

transaction.​statusstringrequired

Transaction status

Enum"created""processing""pending_signature""broadcasted""succeeded""failed""cancelled""expired"
transaction.​createdAtobjectrequired

create date

transaction.​updatedAtobjectrequired

update date

transaction.​tenantIdstringrequired

Tenant ID for multi-tenant isolation

transaction.​chainIdnumberrequired

Blockchain chain ID

transaction.​senderIdobject or nullrequired

Sender entity ID (polymorphic reference)

transaction.​senderOwnerTypestring or nullrequired

Sender entity type (user, business, system etc.)

Enum"user""business""tenant""system""external"
transaction.​recipientIdobject or nullrequired

Recipient entity ID (polymorphic reference)

transaction.​recipientOwnerTypestring or nullrequired

Recipient entity type (user, Business, system, etc.)

Enum"user""business""tenant""system""external"
transactionStatusstringrequired

Current status of the transaction

Enum"created""processing""pending_signature""broadcasted""succeeded""failed""cancelled""expired"
signingDataobject or nullrequired

Prepared transaction data ready for signing (if applicable)

actionableobject or nullrequired
actionable.​messageobject

User-friendly message describing the action

actionable.​actionUrlobject

URL to perform the action

actionable.​authTokenobject

Authentication token for the action

actionable.​actionTypestringrequired

Type of action to be performed

walletSigningStatusstringrequired

Current status of the wallet signing process

Response
application/json
{
  "transaction": {
    "amount": 0,
    "id": "string",
    "tokenAddress": "string",
    "contractTokenId": {},
    "tokenType": "string",
    "senderAddress": "string",
    "recipientAddress": {},
    "transactionHash": {},
    "type": "MINT",
    "triggerProcessType": "PURCHASE",
    "triggerProcessId": {},
    "status": "created",
    "createdAt": {},
    "updatedAt": {},
    "tenantId": "string",
    "chainId": 0,
    "senderId": {},
    "senderOwnerType": "user",
    "recipientId": {},
    "recipientOwnerType": "user"
  },
  "transactionStatus": "created",
  "signingData": {},
  "actionable": {
    "message": {},
    "actionUrl": {},
    "authToken": {},
    "actionType": "string"
  },
  "walletSigningStatus": "string"
}

Get transaction by ID

Request

Get single transaction by ID. Requires valid project API key.

Security
projectKey or authJWT
Path
idstringrequired
curl -i -X GET \
  'https://docs.pers.ninja/_mock/swagger/transactions/{id}' \
  -H 'x-project-key: YOUR_API_KEY_HERE'

Responses

Transaction found

Bodyapplication/json
amountnumberrequired

Transaction amount

idstringrequired

Transaction id

tokenAddressstringrequired

Transaction token address

contractTokenIdobject or nullrequired

Transaction token contract id, this is the blockchain contract id of the token

tokenTypestringrequired

Transaction token type

senderAddressstringrequired

Sender address

recipientAddressobjectrequired

Recipient address

transactionHashobjectrequired

Transaction hash

typestringrequired

Transaction type

Enum"MINT""TRANSFER""BURN"
triggerProcessTypestringrequired

Trigger process type

Enum"PURCHASE""SPEND""TRANSFER""EARN""CAMPAIGN_USER_CLAIM""CAMPAIGN_SYSTEM_CLAIM""CAMPAIGN_BUSINESS_CLAIM""REDEMPTION_SPEND""REDEMPTION_RECEIVE""MIGRATION"
triggerProcessIdobjectrequired

Trigger process id, this is the id of the entity that triggered the transaction if applicable (e.g. CampaignUserClaim id)

statusstringrequired

Transaction status

Enum"created""processing""pending_signature""broadcasted""succeeded""failed""cancelled""expired"
createdAtobjectrequired

create date

updatedAtobjectrequired

update date

tenantIdstringrequired

Tenant ID for multi-tenant isolation

chainIdnumberrequired

Blockchain chain ID

senderIdobject or nullrequired

Sender entity ID (polymorphic reference)

senderOwnerTypestring or nullrequired

Sender entity type (user, business, system etc.)

Enum"user""business""tenant""system""external"
recipientIdobject or nullrequired

Recipient entity ID (polymorphic reference)

recipientOwnerTypestring or nullrequired

Recipient entity type (user, Business, system, etc.)

Enum"user""business""tenant""system""external"
Response
application/json
{
  "amount": 0,
  "id": "string",
  "tokenAddress": "string",
  "contractTokenId": {},
  "tokenType": "string",
  "senderAddress": "string",
  "recipientAddress": {},
  "transactionHash": {},
  "type": "MINT",
  "triggerProcessType": "PURCHASE",
  "triggerProcessId": {},
  "status": "created",
  "createdAt": {},
  "updatedAt": {},
  "tenantId": "string",
  "chainId": 0,
  "senderId": {},
  "senderOwnerType": "user",
  "recipientId": {},
  "recipientOwnerType": "user"
}

Prepare existing transaction for client-side signing

Request

Prepares transaction data for client-side execution from existing transaction ID. Returns the data needed for the client to sign and submit the transaction.

Security
projectKey or authUserJWT
Path
idstringrequired
curl -i -X GET \
  'https://docs.pers.ninja/_mock/swagger/transactions/{id}/prepare' \
  -H 'x-project-key: YOUR_API_KEY_HERE'

Responses

Transaction prepared successfully

Bodyapplication/json
transactionobjectrequired
transaction.​amountnumberrequired

Transaction amount

transaction.​idstringrequired

Transaction id

transaction.​tokenAddressstringrequired

Transaction token address

transaction.​contractTokenIdobject or nullrequired

Transaction token contract id, this is the blockchain contract id of the token

transaction.​tokenTypestringrequired

Transaction token type

transaction.​senderAddressstringrequired

Sender address

transaction.​recipientAddressobjectrequired

Recipient address

transaction.​transactionHashobjectrequired

Transaction hash

transaction.​typestringrequired

Transaction type

Enum"MINT""TRANSFER""BURN"
transaction.​triggerProcessTypestringrequired

Trigger process type

Enum"PURCHASE""SPEND""TRANSFER""EARN""CAMPAIGN_USER_CLAIM""CAMPAIGN_SYSTEM_CLAIM""CAMPAIGN_BUSINESS_CLAIM""REDEMPTION_SPEND""REDEMPTION_RECEIVE""MIGRATION"
transaction.​triggerProcessIdobjectrequired

Trigger process id, this is the id of the entity that triggered the transaction if applicable (e.g. CampaignUserClaim id)

transaction.​statusstringrequired

Transaction status

Enum"created""processing""pending_signature""broadcasted""succeeded""failed""cancelled""expired"
transaction.​createdAtobjectrequired

create date

transaction.​updatedAtobjectrequired

update date

transaction.​tenantIdstringrequired

Tenant ID for multi-tenant isolation

transaction.​chainIdnumberrequired

Blockchain chain ID

transaction.​senderIdobject or nullrequired

Sender entity ID (polymorphic reference)

transaction.​senderOwnerTypestring or nullrequired

Sender entity type (user, business, system etc.)

Enum"user""business""tenant""system""external"
transaction.​recipientIdobject or nullrequired

Recipient entity ID (polymorphic reference)

transaction.​recipientOwnerTypestring or nullrequired

Recipient entity type (user, Business, system, etc.)

Enum"user""business""tenant""system""external"
transactionStatusstringrequired

Current status of the transaction

Enum"created""processing""pending_signature""broadcasted""succeeded""failed""cancelled""expired"
signingDataobject or nullrequired

Prepared transaction data ready for signing (if applicable)

actionableobject or nullrequired
actionable.​messageobject

User-friendly message describing the action

actionable.​actionUrlobject

URL to perform the action

actionable.​authTokenobject

Authentication token for the action

actionable.​actionTypestringrequired

Type of action to be performed

walletSigningStatusstringrequired

Current status of the wallet signing process

Response
application/json
{
  "transaction": {
    "amount": 0,
    "id": "string",
    "tokenAddress": "string",
    "contractTokenId": {},
    "tokenType": "string",
    "senderAddress": "string",
    "recipientAddress": {},
    "transactionHash": {},
    "type": "MINT",
    "triggerProcessType": "PURCHASE",
    "triggerProcessId": {},
    "status": "created",
    "createdAt": {},
    "updatedAt": {},
    "tenantId": "string",
    "chainId": 0,
    "senderId": {},
    "senderOwnerType": "user",
    "recipientId": {},
    "recipientOwnerType": "user"
  },
  "transactionStatus": "created",
  "signingData": {},
  "actionable": {
    "message": {},
    "actionUrl": {},
    "authToken": {},
    "actionType": "string"
  },
  "walletSigningStatus": "string"
}

Submit client-side signed transaction

Request

Submits a signed transaction from the client. This method is used to finalize the transaction after the client has signed it.

Security
projectKey or authUserJWT
Bodyapplication/jsonrequired
transactionIdstringrequired

Transaction ID, this is the transaction hash or identifier

typestringrequired

Transaction format type for submission

Enum"legacy""EIP-2930""EIP-1559""EIP-712"
Example: "legacy"
signaturestring

EIP-712 structured data for smart wallet meta-transactions (required when type is EIP-712)

Example: "0x1234567890abcdef..."
signedTransactionstring

Pre-signed blockchain transaction in RLP encoded hex format (required for legacy, EIP-2930, EIP-1559)

Example: "0xf86c0a8255f0..."
curl -i -X POST \
  https://docs.pers.ninja/_mock/swagger/transactions/submit \
  -H 'Content-Type: application/json' \
  -H 'x-project-key: YOUR_API_KEY_HERE' \
  -d '{
    "transactionId": "string",
    "type": "legacy",
    "signature": "0x1234567890abcdef...",
    "signedTransaction": "0xf86c0a8255f0..."
  }'

Responses

Transaction submitted successfully

Bodyapplication/json
transactionobjectrequired
transaction.​amountnumberrequired

Transaction amount

transaction.​idstringrequired

Transaction id

transaction.​tokenAddressstringrequired

Transaction token address

transaction.​contractTokenIdobject or nullrequired

Transaction token contract id, this is the blockchain contract id of the token

transaction.​tokenTypestringrequired

Transaction token type

transaction.​senderAddressstringrequired

Sender address

transaction.​recipientAddressobjectrequired

Recipient address

transaction.​transactionHashobjectrequired

Transaction hash

transaction.​typestringrequired

Transaction type

Enum"MINT""TRANSFER""BURN"
transaction.​triggerProcessTypestringrequired

Trigger process type

Enum"PURCHASE""SPEND""TRANSFER""EARN""CAMPAIGN_USER_CLAIM""CAMPAIGN_SYSTEM_CLAIM""CAMPAIGN_BUSINESS_CLAIM""REDEMPTION_SPEND""REDEMPTION_RECEIVE""MIGRATION"
transaction.​triggerProcessIdobjectrequired

Trigger process id, this is the id of the entity that triggered the transaction if applicable (e.g. CampaignUserClaim id)

transaction.​statusstringrequired

Transaction status

Enum"created""processing""pending_signature""broadcasted""succeeded""failed""cancelled""expired"
transaction.​createdAtobjectrequired

create date

transaction.​updatedAtobjectrequired

update date

transaction.​tenantIdstringrequired

Tenant ID for multi-tenant isolation

transaction.​chainIdnumberrequired

Blockchain chain ID

transaction.​senderIdobject or nullrequired

Sender entity ID (polymorphic reference)

transaction.​senderOwnerTypestring or nullrequired

Sender entity type (user, business, system etc.)

Enum"user""business""tenant""system""external"
transaction.​recipientIdobject or nullrequired

Recipient entity ID (polymorphic reference)

transaction.​recipientOwnerTypestring or nullrequired

Recipient entity type (user, Business, system, etc.)

Enum"user""business""tenant""system""external"
transactionStatusstringrequired

Current status of the transaction

Enum"created""processing""pending_signature""broadcasted""succeeded""failed""cancelled""expired"
signingDataobject or nullrequired

Prepared transaction data ready for signing (if applicable)

actionableobject or nullrequired
actionable.​messageobject

User-friendly message describing the action

actionable.​actionUrlobject

URL to perform the action

actionable.​authTokenobject

Authentication token for the action

actionable.​actionTypestringrequired

Type of action to be performed

walletSigningStatusstringrequired

Current status of the wallet signing process

Response
application/json
{
  "transaction": {
    "amount": 0,
    "id": "string",
    "tokenAddress": "string",
    "contractTokenId": {},
    "tokenType": "string",
    "senderAddress": "string",
    "recipientAddress": {},
    "transactionHash": {},
    "type": "MINT",
    "triggerProcessType": "PURCHASE",
    "triggerProcessId": {},
    "status": "created",
    "createdAt": {},
    "updatedAt": {},
    "tenantId": "string",
    "chainId": 0,
    "senderId": {},
    "senderOwnerType": "user",
    "recipientId": {},
    "recipientOwnerType": "user"
  },
  "transactionStatus": "created",
  "signingData": {},
  "actionable": {
    "message": {},
    "actionUrl": {},
    "authToken": {},
    "actionType": "string"
  },
  "walletSigningStatus": "string"
}

Export all transactions as CSV

Request

Downloads all transactions as a CSV file. RLS ensures tenant isolation automatically. File includes all transaction data formatted for business analysis.

Security
tenantAdminJWT
curl -i -X GET \
  https://docs.pers.ninja/_mock/swagger/transactions/export/csv \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

CSV file download

Headers
Content-Typestring

MIME type of the file

Example: "text/csv"
Content-Dispositionstring

File download attachment

Example: "attachment; filename=\"transactions_2024-01-15.csv\""
Bodyapplication/json
string(binary)
Response
application/json
"string"

Get transaction analytics

Request

Get transaction analytics with dynamic filtering, grouping, and metrics. Optimized for dashboard modules: stamps count, rewards analysis, top users, etc. RLS ensures tenant isolation automatically.

Security
tenantAdminJWT
Bodyapplication/jsonrequired

Analytics configuration with filters, grouping, and metrics

filtersobject

Dynamic filters based on TransactionDTO fields - all transaction fields available

Example: {"status":"SUCCEEDED","tokenType":"STAMP","triggerProcessType":"MINT","tenantId":"tenant-123","chainId":1}
groupByArray of strings

Fields to group by - any TransactionDTO field plus computed time fields

Example: ["tokenType","month","status","chainId"]
groupByExpressionsArray of objects(GroupByExpressionDTO)

Complex CASE WHEN expressions for advanced grouping scenarios

Example: [{"expression":"CASE WHEN senderOwnerType = user THEN senderId WHEN recipientOwnerType = user THEN recipientId END","alias":"userId","label":"User ID"}]
metricsstring

Metrics to calculate

Enum"count""sum""avg""min""max"
Example: ["count"]
sortBystring

Field to order results by (supports expression aliases)

Enum"count""sum""avg""min""max""createdAt"
Example: "count"
sortOrdernumber

Order direction

Value{"ASC":"ASC","DESC":"DESC"}
Example: "DESC"
limitnumber[ 1 .. 100 ]

Maximum number of results to return

Example: 10
startDatestring(date-time)

Start date for analytics (ISO format)

Example: "2024-01-01T00:00:00.000Z"
endDatestring(date-time)

End date for analytics (ISO format)

Example: "2024-12-31T23:59:59.999Z"
curl -i -X POST \
  https://docs.pers.ninja/_mock/swagger/transactions/analytics \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "filters": {
      "status": "SUCCEEDED",
      "tokenType": "STAMP"
    },
    "groupBy": [
      "month"
    ],
    "metrics": [
      "count"
    ],
    "orderBy": "count",
    "orderDirection": "DESC",
    "limit": 12
  }'

Responses

Analytics results retrieved successfully

Bodyapplication/json
resultsArray of arraysrequired

Analytics results array with dynamic fields and expression aliases

Example: [{"userId":"user-123","count":45},{"userAddress":"0xabc...def","count":32},{"tokenType":"STAMP","count":150,"month":"2024-01-01T00:00:00.000Z"}]
totalGroupsnumberrequired

Total number of result groups

Example: 3
metadataobjectrequired

Query execution metadata

Example: {"executionTime":"45ms"}
Response
application/json
{
  "results": [
    { … },
    { … },
    { … }
  ],
  "totalGroups": 3,
  "metadata": {
    "executionTime": "45ms"
  }
}

Users

Operations

Balances

Operations

Files

Operations

Web3 Chains

Operations

Contracts

Operations

Auth

Operations

Root

Operations

Well-known

Operations

webhooks

Business Types

Operations

Redemption Types

Operations

Redemption Redeems

Operations

Redemption Tokens

Operations

API Keys

Operations