Transactions

Send crypto, check gas prices, and track transaction status

The Transactions API handles all outbound fund movements. You can estimate fees before sending, initiate transfers, and track status through to on-chain confirmation.

---

Get Gas Price Estimate

POST /transactions/get-gas-price

Returns an estimated network fee for a transaction before committing to it.

chainType · string · required

The blockchain to estimate fees for (e.g. "ethereum", "solana", "polygon").

priority · string

Fee priority: "low", "medium", or "high". Defaults to "low".

amount_usd · string

Estimated transaction value in USD. Used to calculate proportional fees on some chains.

asset_id · string

Asset ObjectId for context-aware fee estimation.

token_symbol · string

Token symbol for context-aware fee estimation (e.g. "USDC").

cURL

curl -X POST https://crypto-api.yativo.com/api/v1/transactions/get-gas-price \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chainType": "ethereum",
    "priority": "medium",
    "amount_usd": "500"
  }'

Response

{
  "success": true,
  "data": {
    "estimatedFee": 0.00127,
    "gasFee": 0.00127,
    "platformFees": 0,
    "estimatedFeeUSD": 3.18,
    "nativeToken": "ETH",
    "chain": "ETH",
    "inputChain": "ETHEREUM",
    "priority": "medium",
    "breakdown": {
      "gas_cost_usd": "3.18000000",
      "platform_fees_usd": "0.00000000",
      "total_cost_usd": "3.18000000",
      "platform_fee_details": []
    }
  }
}

---

Send Funds

POST /transactions/send-funds

Initiates an outbound crypto transfer. An idempotency key is automatically generated to prevent duplicate transactions.

account · string · required

The MongoDB ObjectId of the account that owns the source asset.

assets · string · required

The MongoDB ObjectId of the asset (wallet) to send from.

receiving_address · string · required

The recipient’s blockchain address.

amount · number · required

Amount to send, in the token’s native units (e.g. 100 for 100 USDC).

type · string · required

Token ticker / short name (e.g. "ETH", "USDC", "SOL"). Must match the asset record.

chain · string · required

Blockchain network (e.g. "ethereum", "solana", "polygon").

category · string · required

Transaction category: "personal", "business", "payment", "auto-forward", "other", etc.

priority · string

Gas priority: "low", "medium", "high". Defaults to "medium".

description · string

Optional human-readable note.

use_self_funding · boolean

Pay gas from the wallet’s own native balance. Only for native token assets. Defaults to false.

cURL

curl -X POST https://crypto-api.yativo.com/api/v1/transactions/send-funds \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "64b1f9e2a3c4d5e6f7a8b9c0",
    "assets": "64b1f9e2a3c4d5e6f7a8b9d1",
    "receiving_address": "0x9F8b3A2c1E4D7F6B5A4C3D2E1F0A9B8C7D6E5F4",
    "amount": 100,
    "type": "USDC",
    "chain": "ethereum",
    "category": "payment",
    "priority": "medium"
  }'

const tx = await client.transactions.sendFunds({
  account: '64b1f9e2a3c4d5e6f7a8b9c0',
  assets: '64b1f9e2a3c4d5e6f7a8b9d1',
  receiving_address: '0x9F8b3A2c1E4D7F6B5A4C3D2E1F0A9B8C7D6E5F4',
  amount: 100,
  type: 'USDC',
  chain: 'ethereum',
  category: 'payment',
  priority: 'medium',
});

tx = client.transactions.send_funds(
    account='64b1f9e2a3c4d5e6f7a8b9c0',
    assets='64b1f9e2a3c4d5e6f7a8b9d1',
    receiving_address='0x9F8b3A2c1E4D7F6B5A4C3D2E1F0A9B8C7D6E5F4',
    amount=100,
    type='USDC',
    chain='ethereum',
    category='payment',
    priority='medium',
)

Response

{
  "status": true,
  "message": "Transaction Created Successfully",
  "data": {
    "transaction_id": "txn_01HX9KZMB3F7VNQP8R2WDGT4E5",
    "transaction_hash": "0x9f3e2d1c4b7a5e8f2c9b3d6a1e4c7f2b5d8e1c4a",
    "gas_tx_hash": null,
    "platform_fee_tx_hash": null,
    "gas_amount": "0",
    "platform_fee": "0.50000000",
    "gas_funding_markup": "0.12000000",
    "total_fee": "0.62000000",
    "fee_breakdown": "N/A"
  }
}

Idempotency

Supply an Idempotency-Key header to prevent duplicate transactions on retry. If the same key is submitted again by the same user, the original response is returned instead of creating a new transaction. Without a key, no deduplication is applied. Keys expire after 24 hours.

Double-check receiving_address before sending. Blockchain transactions are irreversible — funds sent to the wrong address cannot be recovered.

---

List Transactions

POST /transactions/get-transactions

Returns up to 100 transactions for the authenticated user, sorted by most recent. Use the filter parameters to narrow results.

search · string

Search by transaction_id or transaction_hash (case-insensitive substring match).

status_filter · string

Filter by status: pending, completed, failed.

assets_filter · string

Filter by asset ObjectId or asset name substring.

method_filter · string

Filter by transaction type field (e.g. "USDC", "ETH").

chain_filter · string

Filter by blockchain (e.g. "ethereum", "solana").

cURL

curl -X POST https://crypto-api.yativo.com/api/v1/transactions/get-transactions \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status_filter": "completed",
    "chain_filter": "ethereum"
  }'

Response

{
  "status": true,
  "message": "Transactions fetched successfully",
  "data": [
    {
      "_id": "64b1f9e2a3c4d5e6f7a8b9e0",
      "transaction_id": "txn_01HX9KZMB3F7VNQP8R2WDGT4E5",
      "transaction_hash": "0x9f3e2d1c4b7a5e8f2c9b3d6a1e4c7f2b5d8e1c4a",
      "receiving_address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
      "amount": "100",
      "type": "USDC",
      "chain": "ethereum",
      "status": "completed",
      "blockchain_status": "confirmed",
      "confirmations": 12,
      "block_number": 19847345,
      "fee_paid": "0.62000000",
      "fee_currency": "USDC",
      "platform_fee_tx_hash": null,
      "category": "payment",
      "description": "Payout for order #ORD-9821",
      "is_autoforward": false,
      "createdAt": "2026-03-26T10:06:00.000Z"
    }
  ]
}

---

Transaction Statuses

Status	Description
pending	Transaction created, waiting to be broadcast to the network
completed	Confirmed on-chain with sufficient block confirmations
failed	Transaction failed (insufficient funds, invalid address, network error)

The blockchain_status field tracks on-chain state separately:

blockchain_status	Description
pending	Not yet broadcast
confirmed	Included in a block with enough confirmations

Priority Levels

Priority	Speed	Fee
slow	Slower confirmation, may take several minutes	Lowest
medium	Standard confirmation time	Standard
fast	Prioritized for faster inclusion	Highest

Gas Funding for Token Withdrawals

When withdrawing token assets (USDC, USDT, etc.) the sending wallet needs native currency for gas. Yativo handles this automatically:

• User Gas Station configured — gas is funded from the user’s own gas station wallet
• No user Gas Station — the platform Gas Station is used as a fallback
• use_self_funding: true — only valid for native token assets (ETH, SOL, etc.); gas is deducted from the wallet’s own balance without a markup

In both gas station cases, a 20% service markup on the estimated gas cost is deducted from your withdrawal amount and returned as gas_funding_markup in the response.

Ensure amount is larger than platform_fee + gas_funding_markup. The API returns a 400 if the amount cannot cover total fees.

Use webhooks to track transaction status changes in real time instead of polling. See Webhooks for the transaction.{type}.completed and transaction.failed event payloads.