Skip to content

PERS-api docs (2.0.2)

Download OpenAPI description
swagger.json
swagger.yaml
Overview
Languages
Servers
Mock server

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

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 financial 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 financial operations

Get authenticated user's sent transactions

Request

Get transactions where the authenticated user is the sender. Replaces GET /transaction/auth/sender

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

Responses

User sent transactions

Bodyapplication/jsonArray [
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"
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"
  }
]

Get authenticated user's received transactions

Request

Get transactions where the authenticated user is the recipient. Replaces GET /transaction/auth/recipient

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

Responses

User received transactions

Bodyapplication/jsonArray [
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"
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"
  }
]

Get all transactions with pagination (Admin)

Request

Get all transactions with structured pagination and filtering. RLS ensures tenant isolation automatically. Replaces GET /transaction/admin

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

Responses

Paginated transactions list

Bodyapplication/json
dataArray of arraysrequired

Array of data items

paginationobjectrequired

Pagination metadata

Example: {"page":1,"limit":50,"total":150,"pages":3,"hasNext":true,"hasPrev":false}
Response
application/json
{
  "data": [],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 150,
    "pages": 3,
    "hasNext": true,
    "hasPrev": false
  }
}

Query transactions by sender (Admin)

Request

Get transactions by sender for any account. Replaces POST /transaction/admin/sender

Security
tenantAdminJWT
Bodyapplication/jsonrequired
accountIdstring

Account ID (businessId or userId). System will auto-detect account type.

Example: "user123"
accountTypestringrequired

Account type

Enum"user""business""tenant""system""external"
Example: "user"
accountAddressstring

Direct account address (fallback if account ID not found)

Example: "0x742d35Cc5dB3dC0F0e8f0b0d2fA0c3fA2ed5D0f8"
curl -i -X POST \
  https://docs.pers.ninja/_mock/swagger/transactions/query-sender \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountId": "user123",
    "accountType": "user",
    "accountAddress": "0x742d35Cc5dB3dC0F0e8f0b0d2fA0c3fA2ed5D0f8"
  }'

Responses

Transactions as sender

Bodyapplication/jsonArray [
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"
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"
  }
]

Query transactions by recipient (Admin)

Request

Get transactions by recipient for any account. Replaces POST /transaction/admin/recipient

Security
tenantAdminJWT
Bodyapplication/jsonrequired
accountIdstring

Account ID (businessId or userId). System will auto-detect account type.

Example: "user123"
accountTypestringrequired

Account type

Enum"user""business""tenant""system""external"
Example: "user"
accountAddressstring

Direct account address (fallback if account ID not found)

Example: "0x742d35Cc5dB3dC0F0e8f0b0d2fA0c3fA2ed5D0f8"
curl -i -X POST \
  https://docs.pers.ninja/_mock/swagger/transactions/query-recipient \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountId": "user123",
    "accountType": "user",
    "accountAddress": "0x742d35Cc5dB3dC0F0e8f0b0d2fA0c3fA2ed5D0f8"
  }'

Responses

Transactions as recipient

Bodyapplication/jsonArray [
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"
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"
  }
]

Get transaction by ID

Request

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

Security
projectKey
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"
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"
}

Create system transaction (Admin)

Request

Create any type of transaction (MINT/TRANSFER/BURN) using administrative privileges. Replaces POST /transaction/admin/transaction

Security
tenantAdminJWT
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/system \
  -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",
      "nftTokenId": "721",
      "chainId": 1
    },
    "amount": 100
  }'

Responses

System transaction created

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"
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"
}

Create user transaction

Request

Create transaction for authenticated user. Sender automatically set to authenticated user. Replaces POST /transaction/auth/transaction

Security
authUserJWT
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/user \
  -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",
      "nftTokenId": "721",
      "chainId": 1
    },
    "amount": 100
  }'

Responses

User transaction created

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"
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"
}

Create business transaction

Request

Create transaction for business context. Replaces POST /transaction/business/transaction

Security
projectKey and businessApiKey
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/business \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -H 'x-project-key: YOUR_API_KEY_HERE' \
  -d '{
    "web3TransactionType": "TRANSFER",
    "sender": {
      "accountId": "user123",
      "accountType": "user",
      "accountAddress": "0x742d35Cc5dB3dC0F0e8f0b0d2fA0c3fA2ed5D0f8"
    },
    "recipient": {
      "accountId": "user123",
      "accountType": "user",
      "accountAddress": "0x742d35Cc5dB3dC0F0e8f0b0d2fA0c3fA2ed5D0f8"
    },
    "token": {
      "tokenDbId": "uuid-12345-67890",
      "contractAddress": "0x742d35Cc5dB3dC0F0e8f0b0d2fA0c3fA2ed5D0f8",
      "nftTokenId": "721",
      "chainId": 1
    },
    "amount": 100
  }'

Responses

Business transaction created

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"
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 transaction for client-side signing

Request

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

Security
projectKey or authUserJWT
Bodyapplication/jsonrequired
contractAddressstringrequired

Token address for the transaction

contractTokenIdstring

Contract token ID, can be null for burn transactions

amountnumberrequired

Amount of tokens to transfer in the transaction

recipientAddressstring

Recipient address, can be null for burn transactions

senderAddressstringrequired

Sender address

curl -i -X POST \
  https://docs.pers.ninja/_mock/swagger/transactions/prepare \
  -H 'Content-Type: application/json' \
  -H 'x-project-key: YOUR_API_KEY_HERE' \
  -d '{
    "contractAddress": "string",
    "contractTokenId": "string",
    "amount": 0,
    "recipientAddress": "string",
    "senderAddress": "string"
  }'

Responses

Transaction prepared successfully

Bodyapplication/json
transactionIdstringrequired

Transaction ID, this is the transaction hash or identifier

dataobjectrequired

Prepared transaction data ready for signing

walletStatusstringrequired

Current status of the wallet signing process

Enum"WALLET_AND_SIGNING_READY""WALLET_MISSING_SIGNING_ACCOUNT""WALLET_NOT_FOUND"
Response
application/json
{
  "transactionId": "string",
  "data": {},
  "walletStatus": "WALLET_AND_SIGNING_READY"
}

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
transactionIdstringrequired

Transaction ID, this is the transaction hash or identifier

dataobjectrequired

Prepared transaction data ready for signing

walletStatusstringrequired

Current status of the wallet signing process

Enum"WALLET_AND_SIGNING_READY""WALLET_MISSING_SIGNING_ACCOUNT""WALLET_NOT_FOUND"
Response
application/json
{
  "transactionId": "string",
  "data": {},
  "walletStatus": "WALLET_AND_SIGNING_READY"
}

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
Path
idstringrequired
Bodyapplication/jsonrequired
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/{id}/submit' \
  -H 'Content-Type: application/json' \
  -H 'x-project-key: YOUR_API_KEY_HERE' \
  -d '{
    "type": "legacy",
    "signature": "0x1234567890abcdef...",
    "signedTransaction": "0xf86c0a8255f0..."
  }'

Responses

Transaction submitted successfully

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"
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"
}

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