Transaction Management API

Get Wallet Transactions

Retrieves paginated list of wallet transactions with optional filtering.

Endpoint

GET /api/wallet/{wallet}/transaction

Parameters

• wallet (integer): Wallet ID

Query Parameters

• page (numeric, optional): Page number (default: 1)
• limit (numeric, optional): Items per page, max 1000 (default: 10)
• token (string, optional): Filter by token symbol

Response

{
  "status": "success",
  "message": "Wallet transactions fetched successfully",
  "data": [
    {
      "id": 1,
      "amount": "0.100000000000000000",
      "type": "transfer",
      "status": "confirmed",
      "tx_hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "block_number": 12345678,
      "block_timestamp": "2024-01-01 00:00:00",
      "block_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
      "nonce": 1,
      "gas": "0.000000000000021000",
      "gas_price": "0.00000002000000000",
      "gas_used": "0.000000000000021000",
      "cumulative_gas_used": "0.000000000000021000",
      "receipt_status": true,
      "symbol": "ETH",
      "created_at": "2024-01-01 00:00:00",
      "updated_at": "2024-01-01 00:00:00"
    }
  ]
}

Example Request

curl -H "Authorization: Bearer {token}" \
     "https://zafira-app.vratts.com/api/wallet/1/transaction?page=1&limit=10&token=ETH"

Create Wallet Transaction

Creates a new wallet transaction.

Endpoint

POST /api/wallet/{wallet}/transaction/create

Parameters

• wallet (integer): Wallet ID

Request Body

{
  "amount": 0.1,
  "token": "ETH",
  "address": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6"
}

Request Parameters

• amount (numeric, required): Transaction amount
• token (string, required): Token symbol
• address (string, required): Destination address

Response

{
  "status": "success",
  "message": "Wallet transaction created successfully",
  "data": {
    "id": 1,
    "amount": "0.100000000000000000",
    "type": "transfer",
    "status": "pending",
    "tx_hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "block_number": 12345678,
    "block_timestamp": 1758466153,
    "block_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "nonce": 33,
    "gas": 0.000000000000021000,
    "gas_price": 0.000000000020000000,
    "gas_used": 0.000000000000021000,
    "cumulative_gas_used": 0.000000000000021000,
    "receipt_status": true,
    "created_at": "2024-01-01 00:00:00",
    "updated_at": "2024-01-01 00:00:00"
  }
}

Example Request

curl -X POST \
     -H "Authorization: Bearer {token}" \
     -H "Content-Type: application/json" \
     -d '{"amount":0.1,"token":"ETH","address":"0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6"}' \
     https://zafira-app.vratts.com/api/wallet/1/transaction/create

Get Transaction Details

Retrieves details for a specific transaction.

Endpoint

GET /api/wallet/{wallet}/transaction/show/{transaction}

Parameters

• wallet (integer): Wallet ID
• transaction (integer): Transaction ID

Response

{
  "status": "success",
  "message": "Wallet transaction fetched successfully",
  "data": {
    "id": 1,
    "amount": "0.100000000000000000",
    "type": "transfer",
    "status": "confirmed",
    "tx_hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "block_number": 12345678,
    "block_timestamp": "2024-01-01 00:00:00",
    "block_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "nonce": 1,
    "gas": "0.000000000000021000",
    "gas_price": "0.0000000020000000000",
    "gas_used": "0.000000000000021000",
    "cumulative_gas_used": "0.000000000000021000",
    "receipt_status": true,
    "wallet_token": {
      "id": 1,
      "name": "Ethereum",
      "symbol": "ETH",
      "decimals": 18,
      "is_native": true,
      "is_active": true,
      "is_testnet": false,
      "contract": "0x0000000000000000000000000000000000000000"
    },
    "created_at": "2024-01-01 00:00:00",
    "updated_at": "2024-01-01 00:00:00"
  }
}

Example Request

curl -H "Authorization: Bearer {token}" \
     https://zafira-app.vratts.com/api/wallet/1/transaction/show/1

Transaction Model Details

Fields

• id (integer): Unique transaction identifier
• amount (decimal): Transaction amount (18 decimal places)
• type (string): Transaction type (e.g., "transfer", "receipt")
• status (string): Transaction status ("pending", "confirmed", "failed")
• tx_hash (string): Blockchain transaction hash
• block_number (integer): Block number where transaction was mined
• block_timestamp (datetime): Block timestamp
• block_hash (string): Block hash
• nonce (integer): Transaction nonce
• gas (decimal): Gas limit (18 decimal places)
• gas_price (decimal): Gas price (18 decimal places)
• gas_used (decimal): Actual gas used (18 decimal places)
• cumulative_gas_used (decimal): Cumulative gas used (18 decimal places)
• receipt_status (boolean): Transaction receipt status
• created_at (datetime): Creation timestamp
• updated_at (datetime): Last update timestamp

Hidden Fields (for security)

• wallet_id: Associated wallet ID
• token_id: Associated token ID
• input: Transaction input data
• info: Additional transaction information

Transaction Status Values

• pending: Transaction submitted but not yet confirmed
• confirmed: Transaction confirmed on blockchain
• failed: Transaction failed or reverted

Transaction Types

• transfer: Standard token transfer
• receipt: Incoming transaction
• contract: Smart contract interaction

Error Handling

Common Errors

Transaction Not Found (404)

{
  "status": "error",
  "message": "Transaction not found",
  "data": null
}

Invalid Amount (422)

{
  "status": "error",
  "message": "The amount field is required",
  "data": {
    "amount": ["The amount field is required."]
  }
}

Invalid Address (422)

{
  "status": "error",
  "message": "The address field is required",
  "data": {
    "address": ["The address field is required."]
  }
}

Insufficient Balance (400)

{
  "status": "error",
  "message": "Insufficient balance for transaction",
  "data": null
}

Gas Management

Gas Calculation

The API automatically calculates gas requirements for transactions:

• Gas Limit: Estimated gas needed for transaction execution
• Gas Price: Current network gas price
• Gas Used: Actual gas consumed (available after confirmation)

Gas Optimization

• Gas prices are fetched from the network in real-time
• Transactions use optimal gas settings for faster confirmation
• Failed transactions are automatically retried with adjusted gas prices

Transaction Monitoring

Real-time Updates

• Transaction status is updated automatically as blockchain confirmation occurs
• Webhook notifications can be configured for transaction status changes
• Balance updates are triggered automatically upon transaction confirmation

Block Explorer Integration

Each transaction includes:

• Direct links to block explorer for verification
• Block number and timestamp for blockchain confirmation
• Transaction hash for tracking across different explorers

Next Steps

• Charge Management - Create payment charges
• Webhook Management - Set up transaction notifications
• API Examples - Practical usage examples