# Create transaction

Create any type of transaction (MINT/TRANSFER/BURN) using role-based trigger detection.
**Sender resolution — `sender` field is optional:**
If `sender` is omitted, it defaults to the **authenticated caller**:
- Business JWT → sender = your business (`{ accountId: <your business id>, accountType: "business" }`)
- User JWT → sender = your user
- Tenant/admin JWT → sender = the tenant

So a business that wants to send from itself can simply omit `sender` and only provide `recipient` + `amount`.
> **Business "pull from user" rule:** When a **business** initiates a charge where the `sender` is a **user**
(not the business itself), the business must have `canChargeToken = true`, otherwise the request is **rejected** (`403`).
- `recipient` omitted → automatically set to the authenticated business (convenience for POS flows).
- `recipient` explicitly set to the business → allowed.
- `recipient` explicitly set to anyone else → **rejected** (`403`). A business cannot route a user's tokens to a third party.

This rule only applies when the business is pulling from a user. When the business is the `sender`
(rewarding / sending its own tokens), `recipient` is required and may be any valid account.

> **Note:** If `sender` **is** provided, the value is used as-is (no override). The create call does not
reject a mismatched `sender.accountId`, but the transaction cannot actually settle from an account the
caller does not control: signing/submission enforce custody ownership downstream (a business must be the
sender or engaged business to sign; the sender's custodial wallet is required to submit). Prefer omitting
`sender` when acting as yourself.

**Token resolution — `token` field is optional:**
If `token` is omitted, the server automatically resolves the active credit token for the tenant.
This works for all sender types (user, business, tenant).
> **Production recommendation:** Always specify `token` explicitly using `contractAddress` + `chainId`.
The fallback is safe as long as there is exactly one active credit token per tenant (the standard setup),
but omitting it makes the intent implicit and harder to debug. If a second credit token were ever
activated, the fallback would silently pick one with no error.

**Spend semantics — caller-controlled via `web3TransactionType`:**
The `web3TransactionType` you provide is always respected. The platform uses one simple rule to derive intent when you omit it:
- `recipient` present → **TRANSFER** (balance or token moves to the recipient).
- `recipient` absent → **BURN** (token is destroyed; no recipient on chain).

For **ERC721 / ERC1155** charges at point of sale, you choose the right semantic:
- **BURN** — user presents a ticket/stamp and it is consumed (destroyed on-chain). Omit `recipient` or pass `web3TransactionType: "BURN"`.
- **TRANSFER** — user gives custody of the NFT to the business (trade, deposit). Set `recipient` = business and `web3TransactionType: "TRANSFER"`.

For **ERC20** (credits/points) charges, use **TRANSFER** so the balance moves to the business wallet.
**Reward issuance mode (`issuanceMode` on the response):**
Reward-generating transactions (campaign claims, redemption rewards) record how the token was economically issued:
- `TENANT_DELEGATED_MINT` — tenant master wallet mints (ERC20 with `canMintToken`, or NFTs without a business owner).
- `BUSINESS_OWNED_MINT` — business custodial wallet mints its own NFT template.
- `BUSINESS_BALANCE_TRANSFER` — business transfers ERC20 from its own balance (`canMintToken=false`).

Non-reward transactions leave `issuanceMode` = `null`. See the Tokenomics guide in the platform documentation for the full model.
**ERC721 MINT with Dynamic Context:**
For ERC721 mints, you can provide a `context` object for template interpolation and AI prompts.
Values become available as `{{context.xxx}}` placeholders in TokenMetadata name/description.
**Example — minimal credit transfer (token omitted, fallback applies):**

```json
{
  "web3TransactionType": "TRANSFER",
  "sender":    { "accountId": "user-uuid",     "accountType": "user" },
  "recipient": { "accountId": "business-uuid", "accountType": "business" },
  "amount": 100
}
```
**Example — explicit token (recommended for production):**

```json
{
  "web3TransactionType": "TRANSFER",
  "sender":    { "accountId": "user-uuid",     "accountType": "user" },
  "recipient": { "accountId": "business-uuid", "accountType": "business" },
  "token":     { "contractAddress": "0x...", "chainId": 39123 },
  "amount": 100
}
```
**Example — ERC721 MINT with dynamic context:**

```json
{
  "web3TransactionType": "MINT",
  "recipient": { "accountId": "user-uuid", "accountType": "user" },
  "token": { "tokenEntityId": "token-uuid" },
  "amount": 1,
  "context": {
    "awardReason": "Employee of the Month",
    "recipientName": "John Smith"
  }
}
```
Depending on transaction type and signing context, returns prepared transaction for client-side signing or executes server-side directly.

Endpoint: POST /transactions
Version: 2.0.59
Security: authJWT

## Security:

  - `authJWT` (unknown)
    http bearer JWT

## Request fields (application/json):

  - `web3TransactionType` (string, required)
    Transaction type for easier detection and routing
    Enum: "MINT", "TRANSFER", "BURN"

  - `sender` (object)
    Transaction sender, will be resolved from auth context if not provided. if provided and different from auth user, signing capabilities will be checked or transaction will be rejected.

  - `sender.accountId` (string)
    Account ID (businessId or userId). System will auto-detect account type.
    Example: user123

  - `sender.accountType` (string, required)
    Account type
    Enum: "user", "business", "tenant", "system", "external"

  - `sender.accountAddress` (string)
    Direct account address (fallback if account ID not found)
    Example: 0x742d35Cc5dB3dC0F0e8f0b0d2fA0c3fA2ed5D0f8

  - `recipient` (object)
    Transaction recipient (not required for BURN operations)

  - `token` (object)
    Token identification with multiple resolution strategies. If not provided, defaults to active credit token.

  - `token.tokenDbId` (string)
    Database token UUID - highest priority for resolution
    Example: uuid-12345-67890

  - `token.contractAddress` (string)
    Smart contract address on blockchain
    Example: 0x742d35Cc5dB3dC0F0e8f0b0d2fA0c3fA2ed5D0f8

  - `token.contractTokenId` (string)
    Blockchain token ID (on-chain identifier) - STANDARDIZED FIELD
    Example: 721

  - `token.chainId` (number)
    Blockchain chain ID - auto-resolved from token if not provided
    Example: 1

  - `amount` (number, required)
    Transaction amount
    Example: 100

  - `engagedBusinessId` (string)
    Business commercially involved in this transaction (for stats/reporting). Used for POS scenarios.
    Example: business-uuid-123

  - `authorizedSubmitterId` (string)
    Entity authorized to submit this transaction. For POS flow, this is typically the business. Defaults to sender if not provided.
    Example: entity-uuid-456

  - `authorizedSubmitterType` (string)
    Type of entity authorized to submit (USER, BUSINESS). Defaults to USER if not provided.
    Enum: "user", "business", "tenant", "system", "external"

  - `context` (object)
    **ERC721 MINT only** - Dynamic context for template interpolation and AI prompts.
For direct mint transactions, this context is applied as trusted admin context (no `allowExternalContextOverwrite` check needed since caller is admin/system).
**Template Interpolation:** Values become available as `{{context.keyName}}` placeholders in TokenMetadata name/description fields and AI prompts.
**Special validity keys:**
- `validityDate` - Base date for trigger-based validity
- `validityEndDate` - End date for date ranges (e.g., hotel checkout)
- `validityDuration` - Override duration in days/hours

**Custom keys:** Any arbitrary key becomes `{{context.keyName}}` placeholder.
**Example:**

```json
{
  "web3TransactionType": "MINT",
  "recipient": { "accountId": "user-uuid", "accountType": "USER" },
  "token": { "tokenEntityId": "token-uuid" },
  "amount": 1,
  "context": {
    "awardReason": "Employee of the Month",
    "awardDate": "2026-04-16",
    "recipientName": "John Smith"
  }
}
```
    Example: {"awardReason":"Employee of the Month","awardDate":"2026-04-16","recipientName":"John Smith"}

## Response 200:

  - `200` (unknown)
    transaction created

## Response 200 fields (application/json):

  - `transaction` (object, required)
    Transaction details

  - `transaction.amount` (string, required)
    Transaction amount

  - `transaction.id` (string, required)
    Transaction id

  - `transaction.tokenAddress` (string, required)
    Transaction token address

  - `transaction.contractTokenId` (string, required)
    Transaction token contract id, this is the blockchain contract id of the token

  - `transaction.tokenType` (string, required)
    Transaction token type

  - `transaction.senderAddress` (string, required)
    Sender address

  - `transaction.recipientAddress` (string, required)
    Recipient address

  - `transaction.transactionHash` (string, required)
    Transaction hash

  - `transaction.type` (string, required)
    Transaction type
    Enum: "MINT", "TRANSFER", "BURN"

  - `transaction.triggerProcessType` (string, required)
    Trigger process type
    Enum: "PURCHASE", "SPEND", "TRANSFER", "EARN", "CAMPAIGN_USER_CLAIM", "CAMPAIGN_SYSTEM_CLAIM", "CAMPAIGN_BUSINESS_CLAIM", "REDEMPTION_SPEND", "REDEMPTION_RECEIVE", "REDEMPTION_PRICE_TOKEN_TRANSFER", "MIGRATION", "ADMIN_TRIGGERED", "BUSINESS_TRIGGERED"

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

  - `transaction.status` (string, required)
    Transaction status
    Enum: "created", "processing", "pending_signature", "pending_submission", "broadcasted", "succeeded", "failed", "cancelled", "expired"

  - `transaction.createdAt` (string, required)
    Transaction creation timestamp

  - `transaction.updatedAt` (string, required)
    Transaction last update timestamp

  - `transaction.tenantId` (string, required)
    Tenant ID for multi-tenant isolation

  - `transaction.chainId` (number, required)
    Blockchain chain ID

  - `transaction.senderId` (string, required)
    Sender entity ID (polymorphic reference)

  - `transaction.senderOwnerType` (string, required)
    Sender entity type (user, business, system etc.)
    Enum: "user", "business", "tenant", "system", "external"

  - `transaction.recipientId` (string, required)
    Recipient entity ID (polymorphic reference)

  - `transaction.recipientOwnerType` (string, required)
    Recipient entity type (user, Business, system, etc.)
    Enum: "user", "business", "tenant", "system", "external"

  - `transaction.message` (string, required)
    Optional message associated with the transaction, e.g. for error details

  - `transaction.engagedBusinessId` (string, required)
    Business commercially involved in this transaction (for stats/reporting)

  - `transaction.authorizedSubmitterId` (string, required)
    Entity authorized to submit this transaction (for POS flow security)

  - `transaction.authorizedSubmitterType` (string, required)
    Type of entity authorized to submit (USER, BUSINESS, etc.)
    Enum: "user", "business", "tenant", "system", "external"

  - `transaction.userCountryCode` (string, required)
    ISO 3166-1 alpha-2 country code derived from IP geolocation

  - `transaction.anonymizedIpAddress` (string, required)
    Anonymized IP address (last octet zeroed for privacy)

  - `transaction.metadataUri` (string, required)
    IPFS/storage URL for token metadata. For ERC721: unique URI per minted token. For ERC1155: shared URI per token type. Example: ipfs://Qm.../metadata.json
    Example: ipfs://QmXyz123.../metadata.json

  - `transaction.tokenMetadataIncrementalId` (number, required)
    Token metadata template ID - stable reference for mint/burn counting. For ERC1155: same as on-chain tokenId. For ERC721: template lookup key (preserved since on-chain ID differs).

  - `transaction.issuanceMode` (string)
    Economic issuance mechanism for reward transactions. TENANT_DELEGATED_MINT: master wallet mints. BUSINESS_OWNED_MINT: business owns the token contract. BUSINESS_BALANCE_TRANSFER: business transfers from own wallet balance. Null for non-reward or legacy transactions.
    Enum: "TENANT_DELEGATED_MINT", "BUSINESS_OWNED_MINT", "BUSINESS_BALANCE_TRANSFER"

  - `transaction.included` (object)
    Included related entities. Only populated when include parameter is specified. Contains sender, recipient, and/or engaged business entities based on requested relations.

  - `transaction.included.sender` (any)
    Included sender entity (User or Business)

  - `transaction.included.sender.id` (string, required)

  - `transaction.included.sender.email` (string)

  - `transaction.included.sender.identifierEmail` (string, required)
    Universal identifier email for deterministic operations. Generated from B2B inputs (email, externalId) for wallet salt generation and external integrations.
    Example: user123@user.pers.internal

  - `transaction.included.sender.firstName` (string, required)
    User first name

  - `transaction.included.sender.lastName` (string, required)
    User last name

  - `transaction.included.sender.externalId` (string, required)
    User external id

  - `transaction.included.sender.accountAddress` (string, required)
    User account address

  - `transaction.included.sender.instagramAccountId` (string, required)
    Instagram account id

  - `transaction.included.sender.googleAccountName` (string, required)
    Google account name

  - `transaction.included.sender.customData` (object, required)
    Custom data

  - `transaction.included.sender.publicProfile` (object, required)
    Public profile data

  - `transaction.included.sender.isActive` (boolean, required)
    Is active

  - `transaction.included.sender.currentSigningAccountId` (string)
    Current active signing account ID for external wallet operations

  - `transaction.included.sender.wallets` (array, required)
    User-owned counterfactual smart contract wallets that can receive tokens

  - `transaction.included.sender.wallets.id` (string, required)
    Unique identifier for the internal wallet

  - `transaction.included.sender.wallets.ownerType` (string, required)
    Owner type for polymorphic ownership
    Enum: "user", "business", "tenant", "system", "external"

  - `transaction.included.sender.wallets.ownerId` (string, required)
    Owner ID for polymorphic ownership
    Example: user_123

  - `transaction.included.sender.wallets.walletManagementType` (string, required)
    Type of internal wallet
    Enum: "custodial", "non-custodial"

  - `transaction.included.sender.wallets.address` (string, required)
    CREATE2 generated address that can receive tokens

  - `transaction.included.sender.wallets.chainId` (number, required)
    Blockchain network chain identifier

  - `transaction.included.sender.wallets.status` (string, required)
    Current status of the wallet
    Enum: "pending", "active", "suspended", "archived"

  - `transaction.included.sender.wallets.ownerSigningAccountId` (string)
    ID of signing account that owns this internal wallet

  - `transaction.included.sender.wallets.tags` (array, required)
    Tags associated with the wallet for categorization

  - `transaction.included.sender.wallets.createdAt` (string, required)
    Timestamp when the wallet was created

  - `transaction.included.sender.wallets.updatedAt` (string, required)
    Timestamp when the wallet was last updated

  - `transaction.included.sender.createdAt` (string, required)
    Timestamp when the user was created

  - `transaction.included.sender.updatedAt` (string, required)
    Timestamp when the user was last updated

  - `transaction.included.sender.registrationSource` (object)
    Registration source tracking for analytics - captures channel and attribution when user was created
    Example: {"channel":"web","medium":"referral","campaign":"launch_2026"}

  - `transaction.included.sender.lastActivityAt` (string)
    Last activity timestamp. Updated whenever user generates tokens (login or refresh). Tracks last time user was active (~1 hour precision).

  - `transaction.included.sender.activityCount` (number)
    Total activity count. Increments on every token generation (login + refresh). Measures true user engagement.
    Example: 42

  - `transaction.included.sender.included` (object)
    Included related entities. Only populated when include parameter is specified.

  - `transaction.included.sender.included.statusTypes` (array)
    User status types earned based on token balances (via ?include=status)

  - `transaction.included.sender.included.statusTypes.name` (string, required)
    User Status Type name

  - `transaction.included.sender.included.statusTypes.description` (string)
    User Status Type description

  - `transaction.included.sender.included.statusTypes.minTokenBalance` (string, required)
    User Status Type eligible Token Addresses

  - `transaction.included.sender.included.statusTypes.discountPercentage` (number, required)
    User Status Type discount Rate in percentage

  - `transaction.included.sender.included.statusTypes.imageUrl` (string)
    User Status Type image Url

  - `transaction.included.sender.included.statusTypes.eligibleTokenAddresses` (array)
    Eligible token contract addresses for this status type
    Example: ["0x1234...","0x5678..."]

  - `transaction.included.sender.included.statusTypes.tags` (array)
    Tags for categorization and filtering
    Example: ["vip","premium","gold"]

  - `transaction.included.sender.included.statusTypes.order` (number)
    Explicit ordering for status hierarchy (higher = more prestigious). If not set, falls back to minTokenBalance for ordering.
    Example: 100

  - `transaction.included.sender.included.statusTypes.id` (number, required)
    User Status Type id

  - `transaction.included.sender.included.tokenBalances` (array)
    Token balances for user wallets (via ?include=balances)

  - `transaction.included.sender.included.tokenBalances.accountAddress` (string, required)

  - `transaction.included.sender.included.tokenBalances.tokenBalances` (array, required)

  - `transaction.included.sender.included.tokenBalances.tokenBalances.contractAddress` (string, required)

  - `transaction.included.sender.included.tokenBalances.tokenBalances.chainId` (number, required)

  - `transaction.included.sender.included.tokenBalances.tokenBalances.balance` (number, required)

  - `transaction.included.sender.included.tokenBalances.tokenBalances.tokenName` (string)

  - `transaction.included.sender.included.tokenBalances.tokenBalances.tokenSymbol` (string)

  - `transaction.included.sender.included.tokenBalances.tokenBalances.tokenType` (string, required)

  - `transaction.included.sender.included.tokenBalances.tokenBalances.tokenId` (string, required)

  - `transaction.included.sender.included.tokenBalances.tokenBalances.metadataUri` (string, required)

  - `transaction.included.sender.included.tokenBalances.tokenBalances.metadata` (object, required)
    Token metadata (loaded from IPFS/storage when needed for filtering)

  - `transaction.included.sender.id` (string, required)
    The id of the business, this is unique and will be used to identify the business.

  - `transaction.included.sender.email` (string, required)
    The email of the business, this is unique and will be used to identify the business.

  - `transaction.included.sender.accountAddress` (string, required)
    The address of the business, this is the address that will be shown to the public.

  - `transaction.included.sender.wallets` (array, required)
    Business-owned counterfactual smart contract wallets that can receive tokens

  - `transaction.included.sender.businessLegalName` (string, required)
    The legal name of the business, this is the name that will be used for legal purposes.

  - `transaction.included.sender.registrationNumber` (string, required)
    The business registration number (e.g., company registration, VAT number, EIN)

  - `transaction.included.sender.displayName` (string, required)
    The display name of the business, this is the name that will be shown to the public.

  - `transaction.included.sender.description` (string, required)
    The description of the business, this is the description that will be shown to the public.

  - `transaction.included.sender.shortDescription` (string, required)
    The short description of the business, this is the description that will be shown to the public.

  - `transaction.included.sender.websiteUrl` (string, required)
    The website of the business, this is the website that will be shown to the public.

  - `transaction.included.sender.imageUrl` (string, required)
    The image of the business, this is the image that will be shown to the public.

  - `transaction.included.sender.logoUrl` (string, required)
    Logo URL for the business

  - `transaction.included.sender.streetAddress` (string, required)
    The address of the business, this is the address that will be shown to the public.

  - `transaction.included.sender.phoneNumber` (string, required)
    The phone number of the business.

  - `transaction.included.sender.neighborhood` (string, required)
    Neighborhood/area name (e.g., "West Bay", "Pearl Qatar", "Lusail") - auto-populated from geocoding

  - `transaction.included.sender.district` (string, required)
    District/administrative area - auto-populated from geocoding

  - `transaction.included.sender.city` (string, required)
    The city of the business, this is the city that will be shown to the public.

  - `transaction.included.sender.postalCode` (string, required)
    The postal code of the business, this is the postal code that will be shown to the public.

  - `transaction.included.sender.country` (string, required)
    The country of the business (auto-populated from geocoding if coordinates provided)

  - `transaction.included.sender.countryCode` (string, required)
    ISO 3166-1 alpha-2 country code (e.g., QA, US, AE) - auto-populated from geocoding
    Example: QA

  - `transaction.included.sender.coordsLatitude` (number, required)
    The latitude of the business, this is the latitude that will be shown to the public.

  - `transaction.included.sender.coordsLongitude` (number, required)
    The longitude of the business, this is the longitude that will be shown to the public.

  - `transaction.included.sender.businessType` (object, required)
    The business type of the business, this is the business type that will be shown to the public.

  - `transaction.included.sender.businessType.id` (string)
    Business type id

  - `transaction.included.sender.businessType.name` (string, required)
    Business type name

  - `transaction.included.sender.businessType.description` (string, required)
    Business type description

  - `transaction.included.sender.businessType.code` (string, required)
    Business type code

  - `transaction.included.sender.businessType.iconUrl` (string, required)
    Business type icon url

  - `transaction.included.sender.isActive` (boolean, required)
    The status of the business, this is the status that will be shown to the public.

  - `transaction.included.sender.approval` (object, required)
    Approval metadata for this business.

  - `transaction.included.sender.approval.status` (string, required)
    Approval state: pending_approval = awaiting admin review, approved = active, rejected = denied.
    Enum: "pending_approval", "approved", "rejected"

  - `transaction.included.sender.approval.approvedAt` (string)
    Timestamp when the entity was approved or rejected by an admin.

  - `transaction.included.sender.approval.approvedBy` (string)
    Admin user ID who approved or rejected this entity.

  - `transaction.included.sender.approval.rejectionReason` (string)
    Reason provided when the entity was rejected.

  - `transaction.included.sender.canMintToken` (boolean, required)
    The ability to mint token for the business, this is the ability that will be shown to the public.

  - `transaction.included.sender.canChargeToken` (boolean, required)
    The ability to charge token for the business, this is the ability that will be shown to the public.

  - `transaction.included.sender.canManageUsers` (boolean, required)
    The ability to manage users for the business, this is the ability that will be shown to the public.

  - `transaction.included.sender.canReceiveDonation` (boolean, required)
    The ability to receive donation for the business, this is the ability that will be shown to the public.

  - `transaction.included.sender.tags` (array, required)
    Tags for categorization and filtering

  - `transaction.included.sender.customData` (object, required)
    Custom business data including Google Places information (placeID, currentOpeningHours)
    Example: {"placeID":"ChIJN1t_tDeuEmsRUsoyG83frY4","currentOpeningHours":{"open_now":true,"weekday_text":["Monday: 9:00 AM – 5:00 PM","Tuesday: 9:00 AM – 5:00 PM"]}}

  - `transaction.included.recipient` (any)
    Included recipient entity (User or Business)

  - `transactionStatus` (string, required)
    Current status of the transaction
    Enum: "created", "processing", "pending_signature", "pending_submission", "broadcasted", "succeeded", "failed", "cancelled", "expired"

  - `signingData` (object, required)
    Prepared transaction data ready for signing (if applicable)

  - `actionable` (object, required)
    Actionable details for the transaction, if applicable

  - `actionable.message` (string)
    User-friendly message describing the action

  - `actionable.actionUrl` (string)
    URL to perform the action

  - `actionable.authToken` (string)
    Authentication token for the action

  - `actionable.actionType` (string, required)
    Type of action to be performed

  - `walletSigningStatus` (string, required)
    Current status of the wallet signing process

  - `signatureData` (object)
    Signature data (populated when transaction is signed but not submitted)

## Response 201 fields (application/json):

  - `transaction` (object, required)
    Transaction details

  - `transaction.amount` (string, required)
    Transaction amount

  - `transaction.id` (string, required)
    Transaction id

  - `transaction.tokenAddress` (string, required)
    Transaction token address

  - `transaction.contractTokenId` (string, required)
    Transaction token contract id, this is the blockchain contract id of the token

  - `transaction.tokenType` (string, required)
    Transaction token type

  - `transaction.senderAddress` (string, required)
    Sender address

  - `transaction.recipientAddress` (string, required)
    Recipient address

  - `transaction.transactionHash` (string, required)
    Transaction hash

  - `transaction.type` (string, required)
    Transaction type
    Enum: "MINT", "TRANSFER", "BURN"

  - `transaction.triggerProcessType` (string, required)
    Trigger process type
    Enum: "PURCHASE", "SPEND", "TRANSFER", "EARN", "CAMPAIGN_USER_CLAIM", "CAMPAIGN_SYSTEM_CLAIM", "CAMPAIGN_BUSINESS_CLAIM", "REDEMPTION_SPEND", "REDEMPTION_RECEIVE", "REDEMPTION_PRICE_TOKEN_TRANSFER", "MIGRATION", "ADMIN_TRIGGERED", "BUSINESS_TRIGGERED"

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

  - `transaction.status` (string, required)
    Transaction status
    Enum: "created", "processing", "pending_signature", "pending_submission", "broadcasted", "succeeded", "failed", "cancelled", "expired"

  - `transaction.createdAt` (string, required)
    Transaction creation timestamp

  - `transaction.updatedAt` (string, required)
    Transaction last update timestamp

  - `transaction.tenantId` (string, required)
    Tenant ID for multi-tenant isolation

  - `transaction.chainId` (number, required)
    Blockchain chain ID

  - `transaction.senderId` (string, required)
    Sender entity ID (polymorphic reference)

  - `transaction.senderOwnerType` (string, required)
    Sender entity type (user, business, system etc.)
    Enum: "user", "business", "tenant", "system", "external"

  - `transaction.recipientId` (string, required)
    Recipient entity ID (polymorphic reference)

  - `transaction.recipientOwnerType` (string, required)
    Recipient entity type (user, Business, system, etc.)
    Enum: "user", "business", "tenant", "system", "external"

  - `transaction.message` (string, required)
    Optional message associated with the transaction, e.g. for error details

  - `transaction.engagedBusinessId` (string, required)
    Business commercially involved in this transaction (for stats/reporting)

  - `transaction.authorizedSubmitterId` (string, required)
    Entity authorized to submit this transaction (for POS flow security)

  - `transaction.authorizedSubmitterType` (string, required)
    Type of entity authorized to submit (USER, BUSINESS, etc.)
    Enum: "user", "business", "tenant", "system", "external"

  - `transaction.userCountryCode` (string, required)
    ISO 3166-1 alpha-2 country code derived from IP geolocation

  - `transaction.anonymizedIpAddress` (string, required)
    Anonymized IP address (last octet zeroed for privacy)

  - `transaction.metadataUri` (string, required)
    IPFS/storage URL for token metadata. For ERC721: unique URI per minted token. For ERC1155: shared URI per token type. Example: ipfs://Qm.../metadata.json
    Example: ipfs://QmXyz123.../metadata.json

  - `transaction.tokenMetadataIncrementalId` (number, required)
    Token metadata template ID - stable reference for mint/burn counting. For ERC1155: same as on-chain tokenId. For ERC721: template lookup key (preserved since on-chain ID differs).

  - `transaction.issuanceMode` (string)
    Economic issuance mechanism for reward transactions. TENANT_DELEGATED_MINT: master wallet mints. BUSINESS_OWNED_MINT: business owns the token contract. BUSINESS_BALANCE_TRANSFER: business transfers from own wallet balance. Null for non-reward or legacy transactions.
    Enum: "TENANT_DELEGATED_MINT", "BUSINESS_OWNED_MINT", "BUSINESS_BALANCE_TRANSFER"

  - `transaction.included` (object)
    Included related entities. Only populated when include parameter is specified. Contains sender, recipient, and/or engaged business entities based on requested relations.

  - `transaction.included.sender` (any)
    Included sender entity (User or Business)

  - `transaction.included.sender.id` (string, required)

  - `transaction.included.sender.email` (string)

  - `transaction.included.sender.identifierEmail` (string, required)
    Universal identifier email for deterministic operations. Generated from B2B inputs (email, externalId) for wallet salt generation and external integrations.
    Example: user123@user.pers.internal

  - `transaction.included.sender.firstName` (string, required)
    User first name

  - `transaction.included.sender.lastName` (string, required)
    User last name

  - `transaction.included.sender.externalId` (string, required)
    User external id

  - `transaction.included.sender.accountAddress` (string, required)
    User account address

  - `transaction.included.sender.instagramAccountId` (string, required)
    Instagram account id

  - `transaction.included.sender.googleAccountName` (string, required)
    Google account name

  - `transaction.included.sender.customData` (object, required)
    Custom data

  - `transaction.included.sender.publicProfile` (object, required)
    Public profile data

  - `transaction.included.sender.isActive` (boolean, required)
    Is active

  - `transaction.included.sender.currentSigningAccountId` (string)
    Current active signing account ID for external wallet operations

  - `transaction.included.sender.wallets` (array, required)
    User-owned counterfactual smart contract wallets that can receive tokens

  - `transaction.included.sender.wallets.id` (string, required)
    Unique identifier for the internal wallet

  - `transaction.included.sender.wallets.ownerType` (string, required)
    Owner type for polymorphic ownership
    Enum: "user", "business", "tenant", "system", "external"

  - `transaction.included.sender.wallets.ownerId` (string, required)
    Owner ID for polymorphic ownership
    Example: user_123

  - `transaction.included.sender.wallets.walletManagementType` (string, required)
    Type of internal wallet
    Enum: "custodial", "non-custodial"

  - `transaction.included.sender.wallets.address` (string, required)
    CREATE2 generated address that can receive tokens

  - `transaction.included.sender.wallets.chainId` (number, required)
    Blockchain network chain identifier

  - `transaction.included.sender.wallets.status` (string, required)
    Current status of the wallet
    Enum: "pending", "active", "suspended", "archived"

  - `transaction.included.sender.wallets.ownerSigningAccountId` (string)
    ID of signing account that owns this internal wallet

  - `transaction.included.sender.wallets.tags` (array, required)
    Tags associated with the wallet for categorization

  - `transaction.included.sender.wallets.createdAt` (string, required)
    Timestamp when the wallet was created

  - `transaction.included.sender.wallets.updatedAt` (string, required)
    Timestamp when the wallet was last updated

  - `transaction.included.sender.createdAt` (string, required)
    Timestamp when the user was created

  - `transaction.included.sender.updatedAt` (string, required)
    Timestamp when the user was last updated

  - `transaction.included.sender.registrationSource` (object)
    Registration source tracking for analytics - captures channel and attribution when user was created
    Example: {"channel":"web","medium":"referral","campaign":"launch_2026"}

  - `transaction.included.sender.lastActivityAt` (string)
    Last activity timestamp. Updated whenever user generates tokens (login or refresh). Tracks last time user was active (~1 hour precision).

  - `transaction.included.sender.activityCount` (number)
    Total activity count. Increments on every token generation (login + refresh). Measures true user engagement.
    Example: 42

  - `transaction.included.sender.included` (object)
    Included related entities. Only populated when include parameter is specified.

  - `transaction.included.sender.included.statusTypes` (array)
    User status types earned based on token balances (via ?include=status)

  - `transaction.included.sender.included.statusTypes.name` (string, required)
    User Status Type name

  - `transaction.included.sender.included.statusTypes.description` (string)
    User Status Type description

  - `transaction.included.sender.included.statusTypes.minTokenBalance` (string, required)
    User Status Type eligible Token Addresses

  - `transaction.included.sender.included.statusTypes.discountPercentage` (number, required)
    User Status Type discount Rate in percentage

  - `transaction.included.sender.included.statusTypes.imageUrl` (string)
    User Status Type image Url

  - `transaction.included.sender.included.statusTypes.eligibleTokenAddresses` (array)
    Eligible token contract addresses for this status type
    Example: ["0x1234...","0x5678..."]

  - `transaction.included.sender.included.statusTypes.tags` (array)
    Tags for categorization and filtering
    Example: ["vip","premium","gold"]

  - `transaction.included.sender.included.statusTypes.order` (number)
    Explicit ordering for status hierarchy (higher = more prestigious). If not set, falls back to minTokenBalance for ordering.
    Example: 100

  - `transaction.included.sender.included.statusTypes.id` (number, required)
    User Status Type id

  - `transaction.included.sender.included.tokenBalances` (array)
    Token balances for user wallets (via ?include=balances)

  - `transaction.included.sender.included.tokenBalances.accountAddress` (string, required)

  - `transaction.included.sender.included.tokenBalances.tokenBalances` (array, required)

  - `transaction.included.sender.included.tokenBalances.tokenBalances.contractAddress` (string, required)

  - `transaction.included.sender.included.tokenBalances.tokenBalances.chainId` (number, required)

  - `transaction.included.sender.included.tokenBalances.tokenBalances.balance` (number, required)

  - `transaction.included.sender.included.tokenBalances.tokenBalances.tokenName` (string)

  - `transaction.included.sender.included.tokenBalances.tokenBalances.tokenSymbol` (string)

  - `transaction.included.sender.included.tokenBalances.tokenBalances.tokenType` (string, required)

  - `transaction.included.sender.included.tokenBalances.tokenBalances.tokenId` (string, required)

  - `transaction.included.sender.included.tokenBalances.tokenBalances.metadataUri` (string, required)

  - `transaction.included.sender.included.tokenBalances.tokenBalances.metadata` (object, required)
    Token metadata (loaded from IPFS/storage when needed for filtering)

  - `transaction.included.sender.id` (string, required)
    The id of the business, this is unique and will be used to identify the business.

  - `transaction.included.sender.email` (string, required)
    The email of the business, this is unique and will be used to identify the business.

  - `transaction.included.sender.accountAddress` (string, required)
    The address of the business, this is the address that will be shown to the public.

  - `transaction.included.sender.wallets` (array, required)
    Business-owned counterfactual smart contract wallets that can receive tokens

  - `transaction.included.sender.businessLegalName` (string, required)
    The legal name of the business, this is the name that will be used for legal purposes.

  - `transaction.included.sender.registrationNumber` (string, required)
    The business registration number (e.g., company registration, VAT number, EIN)

  - `transaction.included.sender.displayName` (string, required)
    The display name of the business, this is the name that will be shown to the public.

  - `transaction.included.sender.description` (string, required)
    The description of the business, this is the description that will be shown to the public.

  - `transaction.included.sender.shortDescription` (string, required)
    The short description of the business, this is the description that will be shown to the public.

  - `transaction.included.sender.websiteUrl` (string, required)
    The website of the business, this is the website that will be shown to the public.

  - `transaction.included.sender.imageUrl` (string, required)
    The image of the business, this is the image that will be shown to the public.

  - `transaction.included.sender.logoUrl` (string, required)
    Logo URL for the business

  - `transaction.included.sender.streetAddress` (string, required)
    The address of the business, this is the address that will be shown to the public.

  - `transaction.included.sender.phoneNumber` (string, required)
    The phone number of the business.

  - `transaction.included.sender.neighborhood` (string, required)
    Neighborhood/area name (e.g., "West Bay", "Pearl Qatar", "Lusail") - auto-populated from geocoding

  - `transaction.included.sender.district` (string, required)
    District/administrative area - auto-populated from geocoding

  - `transaction.included.sender.city` (string, required)
    The city of the business, this is the city that will be shown to the public.

  - `transaction.included.sender.postalCode` (string, required)
    The postal code of the business, this is the postal code that will be shown to the public.

  - `transaction.included.sender.country` (string, required)
    The country of the business (auto-populated from geocoding if coordinates provided)

  - `transaction.included.sender.countryCode` (string, required)
    ISO 3166-1 alpha-2 country code (e.g., QA, US, AE) - auto-populated from geocoding
    Example: QA

  - `transaction.included.sender.coordsLatitude` (number, required)
    The latitude of the business, this is the latitude that will be shown to the public.

  - `transaction.included.sender.coordsLongitude` (number, required)
    The longitude of the business, this is the longitude that will be shown to the public.

  - `transaction.included.sender.businessType` (object, required)
    The business type of the business, this is the business type that will be shown to the public.

  - `transaction.included.sender.businessType.id` (string)
    Business type id

  - `transaction.included.sender.businessType.name` (string, required)
    Business type name

  - `transaction.included.sender.businessType.description` (string, required)
    Business type description

  - `transaction.included.sender.businessType.code` (string, required)
    Business type code

  - `transaction.included.sender.businessType.iconUrl` (string, required)
    Business type icon url

  - `transaction.included.sender.isActive` (boolean, required)
    The status of the business, this is the status that will be shown to the public.

  - `transaction.included.sender.approval` (object, required)
    Approval metadata for this business.

  - `transaction.included.sender.approval.status` (string, required)
    Approval state: pending_approval = awaiting admin review, approved = active, rejected = denied.
    Enum: "pending_approval", "approved", "rejected"

  - `transaction.included.sender.approval.approvedAt` (string)
    Timestamp when the entity was approved or rejected by an admin.

  - `transaction.included.sender.approval.approvedBy` (string)
    Admin user ID who approved or rejected this entity.

  - `transaction.included.sender.approval.rejectionReason` (string)
    Reason provided when the entity was rejected.

  - `transaction.included.sender.canMintToken` (boolean, required)
    The ability to mint token for the business, this is the ability that will be shown to the public.

  - `transaction.included.sender.canChargeToken` (boolean, required)
    The ability to charge token for the business, this is the ability that will be shown to the public.

  - `transaction.included.sender.canManageUsers` (boolean, required)
    The ability to manage users for the business, this is the ability that will be shown to the public.

  - `transaction.included.sender.canReceiveDonation` (boolean, required)
    The ability to receive donation for the business, this is the ability that will be shown to the public.

  - `transaction.included.sender.tags` (array, required)
    Tags for categorization and filtering

  - `transaction.included.sender.customData` (object, required)
    Custom business data including Google Places information (placeID, currentOpeningHours)
    Example: {"placeID":"ChIJN1t_tDeuEmsRUsoyG83frY4","currentOpeningHours":{"open_now":true,"weekday_text":["Monday: 9:00 AM – 5:00 PM","Tuesday: 9:00 AM – 5:00 PM"]}}

  - `transaction.included.recipient` (any)
    Included recipient entity (User or Business)

  - `transactionStatus` (string, required)
    Current status of the transaction
    Enum: "created", "processing", "pending_signature", "pending_submission", "broadcasted", "succeeded", "failed", "cancelled", "expired"

  - `signingData` (object, required)
    Prepared transaction data ready for signing (if applicable)

  - `actionable` (object, required)
    Actionable details for the transaction, if applicable

  - `actionable.message` (string)
    User-friendly message describing the action

  - `actionable.actionUrl` (string)
    URL to perform the action

  - `actionable.authToken` (string)
    Authentication token for the action

  - `actionable.actionType` (string, required)
    Type of action to be performed

  - `walletSigningStatus` (string, required)
    Current status of the wallet signing process

  - `signatureData` (object)
    Signature data (populated when transaction is signed but not submitted)