Onchain Transactions API

Execute and manage direct blockchain transactions across multiple EVM chains (Sepolia, Amoy, Neon). Support for native tokens and USDC transfers with automated logging, fee management, and transaction history tracking.

Execute Transaction

POST/api/onchain/execute

Execute Transaction

Execute an onchain transaction using backend wallet management with encrypted private keys. Looks up bw_id from wallet_address internally via blockchain_wallet_addresses table. Supports native tokens (ETH, POL, NEON) and ERC20 tokens. Automatically logs to blockchain_tx_logs table.

Parameters

wallet_addressstringrequired

User's wallet address (looked up to get bw_id from blockchain_wallet_addresses table)

chain_idstringrequired

Chain ID (sepolia, amoy, neon)

token_symbolstringrequired

Token symbol (ETH, POL, NEON, USDC)

token_contractstringrequired

Contract address for ERC20 tokens or 'native' for native tokens

to_addressstringrequired

Recipient wallet address (validated as 40-char hex)

amountstringrequired

Transaction amount in token units

decimalsnumber

Token decimals (default: 18, USDC uses 6)

Request Body

{
  "wallet_address": "USER_WALLET_ADDRESS",
  "chain_id": "sepolia",
  "token_symbol": "USDC",
  "token_contract": "USDC_CONTRACT_ADDRESS",
  "to_address": "RECIPIENT_ADDRESS",
  "amount": "10.50",
  "decimals": 6
}

Response

201Transaction executed and logged successfully

{
  "success": true,
  "message": "Onchain transaction executed successfully",
  "data": {
    "transaction": {
      "tx_hash": "TRANSACTION_HASH",
      "block_number": 1234567,
      "gas_used": "21000",
      "gas_price": "20000000000",
      "gas_fee": 0.00042,
      "platform_fee": 0.105,
      "status": "CONFIRMED",
      "explorer_url": "https://sepolia.etherscan.io/tx/TRANSACTION_HASH"
    },
    "log_id": 12345
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

400Validation error or insufficient funds

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Insufficient balance for transaction",
    "details": "Required: 10.50, Available: 5.25"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

404Wallet not found or access denied

{
  "success": false,
  "error": {
    "code": "WALLET_NOT_FOUND",
    "message": "Wallet not found or access denied",
    "details": "Wallet not found or not owned by user on chain sepolia"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

curl -X POST https://api.brdz.link/api/onchain/execute \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
  "wallet_address": "USER_WALLET_ADDRESS",
  "chain_id": "sepolia",
  "token_symbol": "USDC",
  "token_contract": "USDC_CONTRACT_ADDRESS",
  "to_address": "RECIPIENT_ADDRESS",
  "amount": "10.50",
  "decimals": 6
}'

Log Transaction

POST/api/onchain/log

Log Transaction

Log a confirmed onchain transaction that was executed from frontend/external wallet. Records to blockchain_tx_logs table with wallet ownership verification. Transaction type set as 'ONCHAIN_SEND' with 'CONFIRMED' status and 'OUT' flow.

Parameters

bw_idnumberrequired

Blockchain wallet ID (from blockchain_wallets table)

tx_hashstringrequired

Transaction hash (must be 64-char hex starting with 0x)

amountstringrequired

Transaction amount (positive number)

to_addressstringrequired

Recipient address (40-char hex starting with 0x)

token_symbolstringrequired

Token symbol (ETH, POL, NEON, USDC)

chain_idstringrequired

Chain ID (sepolia, amoy, neon)

token_contractstringrequired

Contract address or 'native' for native tokens

gas_feenumberrequired

Gas fee paid for the transaction

platform_feenumberrequired

Platform fee charged

Request Body

{
  "bw_id": 123,
  "tx_hash": "TRANSACTION_HASH",
  "amount": "10.50",
  "to_address": "RECIPIENT_ADDRESS",
  "token_symbol": "USDC",
  "chain_id": "sepolia",
  "token_contract": "USDC_CONTRACT_ADDRESS",
  "gas_fee": 0.00042,
  "platform_fee": 0.1
}

Response

201Transaction logged successfully

{
  "success": true,
  "message": "Onchain transaction logged successfully",
  "data": {
    "transaction_log": {
      "id": 12345,
      "tx_hash": "TRANSACTION_HASH",
      "amount": "10.50",
      "token_symbol": "USDC",
      "chain_id": "sepolia",
      "status": "CONFIRMED",
      "created_at": "2024-01-15T10:30:00Z",
      "explorer_url": "https://sepolia.etherscan.io/tx/TRANSACTION_HASH"
    }
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

400Validation error

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid transaction data",
    "details": [
      "tx_hash must be a valid transaction hash",
      "amount must be a positive number"
    ]
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

403Wallet access denied

{
  "success": false,
  "error": {
    "code": "WALLET_ACCESS_DENIED",
    "message": "Wallet not found or access denied",
    "details": "Wallet 123 not found or not owned by user 456"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

curl -X POST https://api.brdz.link/api/onchain/log \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
  "bw_id": 123,
  "tx_hash": "TRANSACTION_HASH",
  "amount": "10.50",
  "to_address": "RECIPIENT_ADDRESS",
  "token_symbol": "USDC",
  "chain_id": "sepolia",
  "token_contract": "USDC_CONTRACT_ADDRESS",
  "gas_fee": 0.00042,
  "platform_fee": 0.10
}'

Get Transaction History

GET/api/onchain/history/{user_id}

Get Transaction History

Get user's onchain transaction history from blockchain_tx_logs table with JOIN to blockchain_wallets. Filters by tx_type = 'ONCHAIN_SEND'. Access control: users can only access own data, admins can access any user. Includes explorer URLs generated via getBlockExplorerUrl function.

Parameters

user_idnumberrequired

User ID to get transaction history for (path parameter)

limitnumber

Maximum records to return (1-100, default: 50)

offsetnumber

Records to skip for pagination (default: 0)

chain_idstring

Filter by specific chain (sepolia, amoy, neon)

token_symbolstring

Filter by token symbol (ETH, POL, NEON, USDC)

Response

200Transaction history retrieved successfully

{
  "success": true,
  "message": "Transaction history retrieved successfully",
  "data": {
    "user_id": 123,
    "transactions": [
      {
        "id": 12345,
        "bw_id": 456,
        "tx_type": "ONCHAIN_SEND",
        "amount": "10.50",
        "tx_hash": "TRANSACTION_HASH",
        "status": "CONFIRMED",
        "destination_wallet": "RECIPIENT_ADDRESS",
        "tx_flow": "OUT",
        "token_symbol": "USDC",
        "chain_id": "sepolia",
        "token_contract": "USDC_CONTRACT_ADDRESS",
        "gas_fee": "0.00042",
        "platform_fee": "0.10",
        "created_at": "2024-01-15T10:30:00Z",
        "wallet_name": "Trading Wallet",
        "wallet_label": "Primary",
        "explorer_url": "https://sepolia.etherscan.io/tx/TRANSACTION_HASH"
      }
    ],
    "pagination": {
      "total": 25,
      "limit": 50,
      "offset": 0,
      "has_more": false
    },
    "filters_applied": {
      "chain_id": "sepolia",
      "token_symbol": null
    }
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

400Invalid pagination parameters

{
  "success": false,
  "error": {
    "code": "INVALID_PAGINATION",
    "message": "Limit must be between 1 and 100",
    "details": "Provided limit: 150"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

403Access denied

{
  "success": false,
  "error": {
    "code": "ACCESS_DENIED",
    "message": "You can only access your own transaction history",
    "details": "Insufficient permissions"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

curl -X GET "https://api.brdz.link/api/onchain/history/123?limit=10&chain_id=sepolia&token_symbol=USDC" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY"

Get Transaction Details

GET/api/onchain/details/{tx_hash}

Get Transaction Details

Get detailed information about a specific transaction by hash from blockchain_tx_logs with wallet JOIN. Validates tx_hash format as 64-char hex. Access control: users can only access own transactions, admins can access any transaction.

Parameters

tx_hashstringrequired

Transaction hash to retrieve details for (path parameter, validated as 64-char hex)

Response

200Transaction details retrieved successfully

{
  "success": true,
  "message": "Transaction details retrieved successfully",
  "data": {
    "transaction": {
      "id": 12345,
      "bw_id": 456,
      "tx_type": "ONCHAIN_SEND",
      "amount": "10.50",
      "tx_hash": "TRANSACTION_HASH",
      "status": "CONFIRMED",
      "destination_wallet": "RECIPIENT_ADDRESS",
      "tx_flow": "OUT",
      "token_symbol": "USDC",
      "chain_id": "sepolia",
      "token_contract": "USDC_CONTRACT_ADDRESS",
      "gas_fee": "0.00042",
      "platform_fee": "0.10",
      "created_at": "2024-01-15T10:30:00Z",
      "wallet_name": "Trading Wallet",
      "wallet_label": "Primary",
      "user_id": 123,
      "explorer_url": "https://sepolia.etherscan.io/tx/TRANSACTION_HASH"
    },
    "requested_by": 123,
    "access_level": "user"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

400Invalid transaction hash format

{
  "success": false,
  "error": {
    "code": "INVALID_TX_HASH",
    "message": "Invalid transaction hash format",
    "details": "Transaction hash must be a valid 64-character hex string starting with 0x"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

404Transaction not found or access denied

{
  "success": false,
  "error": {
    "code": "TRANSACTION_NOT_FOUND",
    "message": "Transaction not found or access denied",
    "details": "Transaction may not exist or you may not have permission to view it"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

curl -X GET https://api.brdz.link/api/onchain/details/TRANSACTION_HASH \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY"

Get Platform Fee Settings

GET/api/onchain/admin/fee-settings

Get Platform Fee Settings

Get current platform fee configuration from platform_fee_settings table where is_active = true. Returns default values if no settings configured. Admin access required.

Response

200Platform fee settings retrieved successfully

{
  "success": true,
  "message": "Platform fee settings retrieved successfully",
  "data": {
    "platform_fee_settings": {
      "platform_fee_percentage": 0.5,
      "minimum_platform_fee_usd": 0.1,
      "gas_price_multiplier": 1.2,
      "updated_at": "2024-01-15T10:30:00Z",
      "created_at": "2024-01-15T10:30:00Z"
    },
    "is_default": false
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

200_defaultDefault settings returned (no settings configured)

{
  "success": true,
  "message": "Platform fee settings retrieved successfully",
  "data": {
    "platform_fee_settings": {
      "platform_fee_percentage": 0.5,
      "minimum_platform_fee_usd": 0.1,
      "gas_price_multiplier": 1.2,
      "is_default": true,
      "updated_at": "2024-01-15T10:30:00Z"
    },
    "is_default": true
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

curl -X GET https://api.brdz.link/api/onchain/admin/fee-settings \
-H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY"

Update Platform Fee Settings

PUT/api/onchain/admin/fee-settings

Update Platform Fee Settings

Update platform fee configuration. Deactivates existing settings and creates new active record in platform_fee_settings table. Admin access required. Validates percentage (0-10), minimum fee (positive), and gas multiplier (1.0-3.0).

Parameters

platform_fee_percentagenumberrequired

Platform fee as percentage (0-10)

minimum_platform_fee_usdnumberrequired

Minimum fee in USD (positive number)

gas_price_multipliernumberrequired

Gas price safety multiplier (1.0-3.0)

Request Body

{
  "platform_fee_percentage": 0.5,
  "minimum_platform_fee_usd": 0.1,
  "gas_price_multiplier": 1.2
}

Response

200Platform fee settings updated successfully

{
  "success": true,
  "message": "Platform fee settings updated successfully",
  "data": {
    "updated_settings": {
      "id": 789,
      "platform_fee_percentage": 0.5,
      "minimum_platform_fee_usd": 0.1,
      "gas_price_multiplier": 1.2,
      "updated_by_admin_id": 456,
      "is_active": true,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    "updated_by": 456,
    "previous_settings_deactivated": true
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

400Validation error

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input parameters",
    "details": [
      "platform_fee_percentage must be a number between 0 and 10",
      "gas_price_multiplier must be between 1.0 and 3.0"
    ]
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

curl -X PUT https://api.brdz.link/api/onchain/admin/fee-settings \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
  "platform_fee_percentage": 0.5,
  "minimum_platform_fee_usd": 0.10,
  "gas_price_multiplier": 1.2
}'

Supported Chains & Configuration

Blockchain Networks

Based on getChainConfig function in service:

Chain ID	Network	Native Token	RPC Source	Block Explorer
`sepolia`	Sepolia Testnet	ETH	SEPOLIA_RPC_URL env	https://sepolia.etherscan.io/tx/
`amoy`	Polygon Amoy	POL	AMOY_RPC_URL env	https://amoy.polygonscan.com/tx/
`neon`	Neon EVM	NEON	NEON_RPC_URL env	https://neon-devnet.blockscout.com/tx/

Database Tables Used

Based on service implementation:

blockchain_tx_logs: Transaction logging (tx_type: 'ONCHAIN_SEND', status: 'CONFIRMED', tx_flow: 'OUT')
blockchain_wallets: Wallet ownership verification
blockchain_wallet_addresses: Address lookup for bw_id
wallet_secrets: Encrypted private key storage
platform_fee_settings: Fee configuration (is_active filtering)

Transaction Validation

From validateTransactionData and validateExecuteTransactionData functions:

tx_hash: 64-character hex string starting with 0x
to_address: 40-character hex string starting with 0x
amount: Positive number
chain_id: Must be sepolia, amoy, or neon
wallet_address: Looked up in blockchain_wallet_addresses table

Access Control

From controller implementation:

Execute/Log: User can only access own wallets
History/Details: Users can only access own data, admins can access any user
Fee Settings: Admin role required (updatePlatformFeeSettings/getPlatformFeeSettings)

Authentication Required

All endpoints require valid JWT token + API key. Execute and Log operations verify wallet ownership through database lookups.

Error Response Format

All errors follow standard format with success: false, error object containing code/message/details, and timestamp.

Fee Calculation

Platform fees calculated as max(amount * percentage / 100, minimum_fee_usd). Gas prices multiplied by gas_price_multiplier for safety buffer.

Execute Transaction​

Execute Transaction

Parameters

Request Body

Response

Log Transaction​

Log Transaction

Parameters

Request Body

Response

Get Transaction History​

Get Transaction History

Parameters

Response

Get Transaction Details​

Get Transaction Details

Parameters

Response

Get Platform Fee Settings​

Get Platform Fee Settings

Response

Update Platform Fee Settings​

Update Platform Fee Settings

Parameters

Request Body

Response

Supported Chains & Configuration​

Blockchain Networks​

Database Tables Used​

Transaction Validation​

Access Control​

Execute Transaction

Log Transaction

Get Transaction History

Get Transaction Details

Get Platform Fee Settings

Update Platform Fee Settings

Supported Chains & Configuration

Blockchain Networks

Database Tables Used

Transaction Validation

Access Control