Create Transaction

Submit a transaction for processing with optional privacy protection

POST /v1/transactions

Wallet Mode

curl -X POST "https://api.unipay.com/v1/transactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "send",
    "quoteId": "quote_1234567890abcdef",
    "mode": "wallet",
    "sender": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "recipients": [
      {
        "address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
        "amount": "100.0"
      }
    ],
    "signedTransaction": "base64_encoded_signed_transaction"
  }'

Wallet Mode Response

{
  "transactionId": "tx_abcdef1234567890",
  "status": "pending",
  "mode": "wallet",
  "signature": "5VERv8NMvQakCcXn7JQVpMhHkPfft9kTrYpo9wqtKn5VuoKXxU22odq5RKjgdK9AxAFHsqDsy4z5fhFYaKkPWrHRMbodGGBBRn7AoTokBjpByCqVu6r9Ac2LpzQcDwAoRQ",
  "createdAt": "2026-04-22T12:30:00Z"
}

Submit transactions for send, swap, or payroll operations. Supports both wallet mode (direct signing) and private mode (privacy-enhanced routing).

Request Body

type · string · required

Transaction type: send, swap, or payroll

quoteId · string · required

Quote ID from the /quote endpoint

mode · string · default: "wallet"

Execution mode: wallet or private

sender · string · required

Sender wallet address (base58 encoded)

recipients · array · required

Array of recipient objects

Show Recipient Object

address · string · required

Recipient wallet address

amount · string · required

Amount to send (string to preserve precision)

signedTransaction · string

Base64 encoded signed transaction (required for wallet mode)

Response

transactionId · string

Unique transaction identifier

status · string

Current status: pending, processing, completed, or failed

mode · string

Execution mode: wallet or private

signature · string

Transaction signature (wallet mode only)

ephemeralAddress · string

Deposit address for private mode transactions

createdAt · string

Transaction creation timestamp (ISO 8601)

Wallet Mode

curl -X POST "https://api.unipay.com/v1/transactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "send",
    "quoteId": "quote_1234567890abcdef",
    "mode": "wallet",
    "sender": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "recipients": [
      {
        "address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
        "amount": "100.0"
      }
    ],
    "signedTransaction": "base64_encoded_signed_transaction"
  }'

Wallet Mode Response

{
  "transactionId": "tx_abcdef1234567890",
  "status": "pending",
  "mode": "wallet",
  "signature": "5VERv8NMvQakCcXn7JQVpMhHkPfft9kTrYpo9wqtKn5VuoKXxU22odq5RKjgdK9AxAFHsqDsy4z5fhFYaKkPWrHRMbodGGBBRn7AoTokBjpByCqVu6r9Ac2LpzQcDwAoRQ",
  "createdAt": "2026-04-22T12:30:00Z"
}

Transaction Types

Send

Direct token transfer to a single recipient:

{
  "type": "send",
  "recipients": [
    {"address": "...", "amount": "100.0"}
  ]
}

Swap

Token exchange (requires quote with different input/output assets):

{
  "type": "swap", 
  "recipients": [
    {"address": "your_address", "amount": "10.0"}
  ]
}

Payroll

Batch payments to multiple recipients:

{
  "type": "payroll",
  "recipients": [
    {"address": "employee1", "amount": "2500.0"},
    {"address": "employee2", "amount": "3000.0"}
  ]
}

Execution Modes

Wallet Mode

• Requires signedTransaction in request body
• Transaction is broadcast immediately
• Returns transaction signature
• Lower fees (network only)

Private Mode

• No signed transaction required
• Returns ephemeral deposit address
• User sends funds to ephemeral address
• Higher fees (network + routing)

Status Flow

Status	Description
pending	Transaction submitted, awaiting processing
processing	Private mode: routing in progress
completed	Transaction confirmed on-chain
failed	Transaction failed or reverted

Error Responses

error.code · string

Error code identifier

error.message · string

Human-readable error message

error.details · object

Additional error context

Common Errors

Code	Description
INVALID_QUOTE	Quote expired or not found
INVALID_SIGNATURE	Malformed signed transaction
INSUFFICIENT_BALANCE	Not enough tokens for transaction
INVALID_RECIPIENT	Malformed recipient address
ROUTING_UNAVAILABLE	Private mode temporarily unavailable