Skip to main content

Transactions

Send native token transfers, monitor transaction status, and retrieve transaction history.

Sending Transactions​

Programmatic​

// Send native ETH
const tx = await app.onchain.transactions.send({
  to: "0xrecipient...5678",
  value: "0.1",              // In ETH
  chain: "ethereum",
  walletId: "65a1b2c3...",   // Wallet to sign with
});

console.log(tx.hash);       // "0xabc123..."
console.log(tx.status);     // "pending"

REST API​

curl -X POST http://localhost:3000/onchain/transactions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGci..." \
  -d '{
    "to": "0xrecipient...5678",
    "value": "0.1",
    "chain": "ethereum",
    "walletId": "65a1b2c3d4e5f6a7b8c9d0e1"
  }'

Response (200):

{
  "_id": "65a1b2c3d4e5f6a7b8c9d0e1",
  "hash": "0xabc123...",
  "from": "0xsender...1234",
  "to": "0xrecipient...5678",
  "value": "100000000000000000",
  "chain": "ethereum",
  "status": "pending",
  "createdAt": "2025-01-15T10:30:00.000Z"
}

Checking Transaction Status​

Programmatic​

const tx = await app.onchain.transactions.get("0xabc123...", "ethereum");

console.log(tx.status);        // "confirmed" | "pending" | "failed"
console.log(tx.confirmations); // 12
console.log(tx.blockNumber);   // 19000000
console.log(tx.gasUsed);       // "21000"

REST API​

curl "http://localhost:3000/onchain/transactions/0xabc123...?chain=ethereum" \
  -H "Authorization: Bearer eyJhbGci..."

Response (200):

{
  "hash": "0xabc123...",
  "from": "0xsender...1234",
  "to": "0xrecipient...5678",
  "value": "100000000000000000",
  "status": "confirmed",
  "blockNumber": 19000000,
  "confirmations": 12,
  "gasUsed": "21000",
  "gasPrice": "30000000000",
  "chain": "ethereum"
}

Transaction History​

const history = await app.onchain.transactions.list({
  walletId: "65a1b2c3...",
  chain: "ethereum",
  limit: 20,
});
curl "http://localhost:3000/onchain/transactions?walletId=65a1b2c3...&chain=ethereum&limit=20" \
  -H "Authorization: Bearer eyJhbGci..."

Response (200):

{
  "transactions": [
    {
      "_id": "...",
      "hash": "0xabc123...",
      "from": "0xsender...",
      "to": "0xrecipient...",
      "value": "100000000000000000",
      "status": "confirmed",
      "chain": "ethereum",
      "createdAt": "2025-01-15T10:30:00.000Z"
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

Waiting for Confirmation​

// Wait for a transaction to be confirmed
const receipt = await app.onchain.transactions.wait("0xabc123...", {
  chain: "ethereum",
  confirmations: 3,    // Wait for 3 confirmations
  timeout: 120_000,    // Timeout after 2 minutes
});

if (receipt.status === "confirmed") {
  console.log("Transaction confirmed!");
} else {
  console.log("Transaction failed:", receipt.error);
}

Transaction Data Model​

interface Transaction {
  _id: ObjectId;
  hash: string;
  from: string;
  to: string;
  value: string;          // In wei
  data?: string;          // Calldata
  chain: string;
  status: "pending" | "confirmed" | "failed";
  blockNumber?: number;
  gasUsed?: string;
  gasPrice?: string;
  walletId: ObjectId;
  metadata?: Record<string, unknown>;
  createdAt: Date;
  updatedAt: Date;
}