Transaction Guide

Base URL: https://developers.bitpowr.com/api/v1/transactions

Authentication: Bearer token required in Authorization header

Common Transaction Parameters

Core Workflow Parameters

Parameter	Type	Description	Supported Chains
`idempotencyKey`	string	Unique key to prevent duplicate transactions	All chains
`queued`	boolean	Whether to queue transaction or send directly	All chains
`memo`	string	Memo string included in blockchain transaction	Stellar, Solana
`dependsOn`	array	List of transaction IDs to wait for completion	All chains
`customerId`	string	Customer identifier for transaction tracking	All chains
`subAccountId`	string	Sub-account to spend from automatically	All chains
`walletId`	string	Wallet to spend from automatically	All chains
`description`	string	Transaction description	All chains
`assetType`	string	Crypto currency e.g ETH, BTC, USDT, USDT_BASE	All chains
`from`	string	List of addresses to spend from	All chians

1. Idempotent Transactions

Prevent duplicate transactions and race conditions by using idempotency keys. This ensures that multiple identical requests don't create multiple transactions.

How Idempotency Works

First Request: Creates new transaction with the idempotency key
Duplicate Requests: Should return the original transaction instead of creating new ones
Scope: Keys are scoped to your account/wallet

Basic Idempotent Transaction

curl --request POST \
     --url https://developers.bitpowr.com/api/v1/transactions \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer <encodedToken>' \
     -d '{
          "walletId": "e3455-15b5-46ad-84de-34555",
          "assetType": "BTC",
          "tos": [{
              "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
              "value": "0.001"
          }],
          "idempotencyKey": "payment-order-12345-attempt-1",
          "description": "Idempotent Bitcoin payment"
      }'

Idempotency Key Best Practices

// Generate idempotency key with order ID and timestamp
const generateIdempotencyKey = (orderId, userId) => {
  const timestamp = Date.now();
  return `order-${orderId}-user-${userId}-${timestamp}`;
};

// Example usage
const idempotencyKey = generateIdempotencyKey("12345", "user789");

Handling Idempotent Responses

const createTransaction = async (transactionData) => {
  try {
    const response = await fetch('/api/v1/transactions', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer <token>'
      },
      body: JSON.stringify({
        ...transactionData,
        idempotencyKey: generateIdempotencyKey(transactionData.orderId)
      })
    });
    
    const result = await response.json();
    
    if (response.status === 201) {
      console.log('New transaction created:', result.data.uid);
    } else if (response.status === 200) {
      console.log('Existing transaction returned:', result.data.uid);
    }
    
    return result;
  } catch (error) {
    console.error('Transaction failed:', error);
  }
};

2. Queued vs Direct Processing

Control whether transactions are processed immediately or queued for batch processing.

Direct Processing (`queued: false`)

curl --request POST \
     --url https://developers.bitpowr.com/api/v1/transactions \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer <encodedToken>' \
     -d '{
          "walletId": "e3455-15b5-46ad-84de-34555",
          "assetType": "ETH",
          "tos": [{
              "address": "0x742d35Cc6644C0532925a3b8C17DAb6F2c8f1234",
              "value": "0.1"
          }],
          "queued": false,
          "description": "Immediate ETH transfer"
      }'

Direct Processing Characteristics:

Transaction processed immediately
Response includes blockchain hash
Faster for single transactions
Higher resource usage

Queued Processing (`queued: true`)

curl --request POST \
     --url https://developers.bitpowr.com/api/v1/transactions \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer <encodedToken>' \
     -d '{
          "walletId": "e3455-15b5-46ad-84de-34555",
          "assetType": "USDC_ETH",
          "tos": [{
              "address": "0x742d35Cc6644C0532925a3b8C17DAb6F2c8f1234",
              "value": "100"
          }],
          "queued": true,
          "description": "Queued USDC transfer"
      }'

Queued Processing Characteristics:

Transaction added to processing queue
Response does not include hash initially
Better for batch operations
Optimized resource usage
Handles nonce management automatically

When to Use Each Mode

Use Case	Recommended Mode	Reason
High-frequency trading	`queued: false`	Immediate execution needed
Batch payments	`queued: true`	Optimized processing
User-initiated transfers	`queued: false`	Better user experience
Automated workflows	`queued: true`	Efficient resource usage
Emergency transactions	`queued: false`	Immediate processing

3. Memo Support

Include memo strings in blockchain transactions for Stellar and Solana networks.

Stellar Memo Transaction

curl --request POST \
     --url https://developers.bitpowr.com/api/v1/transactions \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer <encodedToken>' \
     -d '{
          "walletId": "e3455-15b5-46ad-84de-34555",
          "assetType": "XLM",
          "tos": [{
              "address": "GAHK7EEG2WWHVKDNT4CEQFZGKF2LGDSW2IVM4S5DP42RBW3K6BTODB4A",
              "value": "10"
          }],
          "memo": "Payment for Invoice INV-2024-001",
          "description": "Stellar payment with memo"
      }'

Solana Memo Transaction

curl --request POST \
     --url https://developers.bitpowr.com/api/v1/transactions \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer <encodedToken>' \
     -d '{
          "walletId": "e3455-15b5-46ad-84de-34555",
          "assetType": "SOL",
          "tos": [{
              "address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
              "value": "1"
          }],
          "memo": "Monthly subscription payment - User ID: 12345",
          "description": "SOL payment with memo"
      }'

Memo Use Cases

Invoice References: Link payments to specific invoices
Order IDs: Connect transactions to e-commerce orders
User Identification: Include user IDs for payment tracking. E.g username, email
Compliance: Required information for regulatory compliance
Internal Tracking: Business-specific reference data

Memo Limitations

Chain	Max Length	Encoding	Notes
Stellar	28 bytes	UTF-8	Text memo type
Solana	~1000 chars	UTF-8	Part of transaction data

4. Transaction Dependencies

Ensure transactions are processed in specific order by using the dependsOn parameter.

Basic Dependency Example

# First transaction
curl --request POST \
     --url https://developers.bitpowr.com/api/v1/transactions \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer <encodedToken>' \
     -d '{
          "walletId": "e3455-15b5-46ad-84de-34555",
          "assetType": "ETH",
          "tos": [{
              "address": "0x742d35Cc6644C0532925a3b8C17DAb6F2c8f1234",
              "value": "1"
          }],
          "idempotencyKey": "funding-tx-001",
          "description": "Initial funding transaction"
      }'

# Response: { "data": { "uid": "tx-funding-123" } }

# Dependent transaction
curl --request POST \
     --url https://developers.bitpowr.com/api/v1/transactions \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer <encodedToken>' \
     -d '{
          "walletId": "e3455-15b5-46ad-84de-34555",
          "assetType": "USDC_ETH",
          "tos": [{
              "address": "0x1180a4c0c71b5eb0256edcffcc3389f1f085c502",
              "value": "100"
          }],
          "dependsOn": ["tx-funding-123"],
          "idempotencyKey": "payment-tx-001",
          "description": "Payment after funding"
      }'

Multiple Dependencies

curl --request POST \
     --url https://developers.bitpowr.com/api/v1/transactions \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer <encodedToken>' \
     -d '{
          "walletId": "e3455-15b5-46ad-84de-34555",
          "assetType": "BTC",
          "tos": [{
              "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
              "value": "0.01"
          }],
          "dependsOn": ["tx-gas_funding-456", "tx-approve-789"],
          "description": "Final payment after approvals"
      }'

Dependency Use Cases

Sequential Workflows: Ensure transactions happen in order
Conditional Payments: Wait for approvals before processing
Multi-Step Operations: Complex business logic requiring order
Risk Management: Verify previous transactions before proceeding
Compliance Workflows: Wait for compliance checks

Dependency Behavior

Waiting State: Dependent transactions remain in QUEUE until dependencies complete
Failure Handling: If any dependency fails, dependent transaction may be cancelled
Timeout: Dependencies have timeout limits to prevent indefinite waiting
Circular Dependencies: System prevents circular dependency chains

5. Customer Tracking

Associate transactions with specific customers for better organization and reporting.

Customer-Linked Transaction

curl --request POST \
     --url https://developers.bitpowr.com/api/v1/transactions \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer <encodedToken>' \
     -d '{
          "walletId": "e3455-15b5-46ad-84de-34555",
          "assetType": "USDC_ETH",
          "tos": [{
              "address": "0x742d35Cc6644C0532925a3b8C17DAb6F2c8f1234",
              "value": "500"
          }],
          "customerId": "customer-premium-789",
          "idempotencyKey": "premium-payment-001",
          "description": "Premium service payment"
      }'

Customer Analytics Example

// Filter transactions by customer
const getCustomerTransactions = async (customerId) => {
  const response = await fetch(`/api/v1/transactions?customerId=${customerId}`, {
    headers: { 'Authorization': 'Bearer <token>' }
  });
  return response.json();
};

// Customer transaction summary
const getCustomerSummary = async (customerId) => {
  const transactions = await getCustomerTransactions(customerId);
  
  return {
    totalTransactions: transactions.length,
    totalVolume: transactions.reduce((sum, tx) => sum + parseFloat(tx.amount), 0),
    successRate: transactions.filter(tx => tx.status === 'CONFIRMED').length / transactions.length,
    lastTransaction: transactions[0]?.createdAt
  };
};

Customer Tracking Benefits

Transaction History: Easy customer transaction lookup
Analytics: Customer-specific transaction analytics
Support: Quick customer support with transaction history
Compliance: Customer due diligence and reporting
Business Intelligence: Customer behavior analysis

6. Sub-Account Management

Use sub-accounts to automatically select addresses and UTXOs for transactions without specifying exact sources.

Sub-Account Transaction

curl --request POST \
     --url https://developers.bitpowr.com/api/v1/transactions \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer <encodedToken>' \
     -d '{
          "walletId": "e3455-15b5-46ad-84de-34555",
          "assetType": "BTC",
          "subAccountId": "trading-account-001",
          "tos": [{
              "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
              "value": "0.005"
          }],
          "description": "Payment from trading sub-account"
      }'

Sub-Account with Customer Tracking

curl --request POST \
     --url https://developers.bitpowr.com/api/v1/transactions \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer <encodedToken>' \
     -d '{
          "walletId": "e3455-15b5-46ad-84de-34555",
          "assetType": "USDC_SOL",
          "subAccountId": "customer-wallet-456",
          "customerId": "premium-customer-789",
          "tos": [{
              "address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
              "value": "1000"
          }],
          "memo": "Large payment from customer wallet",
          "description": "Customer-to-customer transfer"
      }'

Sub-Account Error Handling

# This will cause an error - mixing sub-account with explicit address
curl --request POST \
     --url https://developers.bitpowr.com/api/v1/transactions \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer <encodedToken>' \
     -d '{
          "walletId": "e3455-15b5-46ad-84de-34555",
          "assetType": "ETH",
          "subAccountId": "trading-account-001",
          "from": ["0x40fa00fe4a0a655240fede3149e9ea55118241e2"],
          "tos": [{
              "address": "0x742d35Cc6644C0532925a3b8C17DAb6F2c8f1234",
              "value": "0.1"
          }]
      }'

Error Response:

{
  "status": "error",
  "message": "Address 0x40fa... is not under sub-account trading-account-001"
}

Sub-Account Features

Automatic Selection: System selects optimal addresses/UTXOs
Isolation: Transactions isolated to specific sub-account funds
Simplified Usage: No need to track individual addresses
Error Prevention: Prevents using addresses from wrong sub-accounts
Balance Management: Clear separation/segregation of funds by purpose

7. Combined Advanced Features

Example combining multiple advanced features for a complex business workflow.

E-commerce Order Processing

curl --request POST \
     --url https://developers.bitpowr.com/api/v1/transactions \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer <encodedToken>' \
     -d '{
          "walletId": "e3455-15b5-46ad-84de-34555",
          "assetType": "USDC_ETH",
          "subAccountId": "escrow-account-001",
          "customerId": "customer-premium-789",
          "tos": [{
              "address": "0x742d35Cc6644C0532925a3b8C17DAb6F2c8f1234",
              "value": "2500"
          }],
          "dependsOn": ["gas_funding", "payment_send"],
          "idempotencyKey": "order-12345-payment-final",
          "queued": true,
          "description": "E-commerce order payment after all verifications"
      }'

Subscription Payment Workflow

curl --request POST \
     --url https://developers.bitpowr.com/api/v1/transactions \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer <encodedToken>' \
     -d '{
          "walletId": "e3455-15b5-46ad-84de-34555",
          "assetType": "SOL",
          "subAccountId": "subscription-wallet",
          "customerId": "subscriber-monthly-456",
          "tos": [{
              "address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
              "value": "50"
          }],
          "memo": "Monthly subscription - Plan Premium - Month 3",
          "idempotencyKey": "subscription-456-month-3-2025-01",
          "queued": true,
          "description": "Monthly subscription payment"
      }'

Transaction Response with Advanced Features

{
  "status": "success",
  "data": {
    "hash": "0x8f2a5b3c9d1e4f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a",
    "status": "PENDING",
    "amount": "2500",
    "uid": "6680c116-c803-4e46-aa99-2f261cd216ac",
    "assetType": "USDC_ETH",
    "chain": "ETHEREUM",
    "fee": "0.000195",
    "ref": "BTP-EthTx123#ABC456",
    "network": "MAINNET",
    "customerId": "customer-premium-789",
    "subAccountId": "escrow-account-001",
    "idempotencyKey": "order-12345-payment-final",
    "queued": true,
    "dependsOn": ["kyc-verification-tx", "fraud-check-tx"],
    "memo": null,
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-01-15T10:30:00Z"
  }
}

Best Practices

Idempotency

Unique Keys: Use business-specific identifiers in keys
Key Format: Include timestamp and context for uniqueness
Key Storage: Store keys for audit and debugging
Retry Logic: Use same key for retries

Queue Management

Direct for Urgent: Use direct processing for time-sensitive transactions
Queue for Batch: Use queued processing for bulk operations
Monitor Queues: Track queue depths and processing times
Error Handling: Handle queue failures gracefully

Dependencies

Limit Depth: Avoid deep dependency chains
Timeout Planning: Plan for dependency timeouts
Failure Handling: Define behavior when dependencies fail
Status Monitoring: Monitor dependency resolution

Organization

Customer Linking: Always link transactions to customers when possible
Sub-Account Strategy: Use sub-accounts for clear fund separation
Memo Usage: Include relevant reference information
Description Standards: Use consistent description formats