> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yativo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<ParamField body="chainType" type="string" required>
  The blockchain to estimate fees for (e.g. `"ethereum"`, `"solana"`, `"polygon"`).
</ParamField>

<ParamField body="priority" type="string">
  Fee priority: `"low"`, `"medium"`, or `"high"`. Defaults to `"low"`.
</ParamField>

<ParamField body="amount_usd" type="string">
  Estimated transaction value in USD. Used to calculate proportional fees on some chains.
</ParamField>

<ParamField body="asset_id" type="string">
  Asset ObjectId for context-aware fee estimation.
</ParamField>

<ParamField body="token_symbol" type="string">
  Token symbol for context-aware fee estimation (e.g. `"USDC"`).
</ParamField>

```bash cURL theme={null}
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"
  }'
```

```json Response theme={null}
{
  "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.

<ParamField body="account" type="string" required>
  The MongoDB ObjectId of the **account** that owns the source asset.
</ParamField>

<ParamField body="assets" type="string" required>
  The MongoDB ObjectId of the **asset** (wallet) to send from.
</ParamField>

<ParamField body="receiving_address" type="string" required>
  The recipient's blockchain address.
</ParamField>

<ParamField body="amount" type="number" required>
  Amount to send, in the token's native units (e.g. `100` for 100 USDC).
</ParamField>

<ParamField body="type" type="string" required>
  Token ticker / short name (e.g. `"ETH"`, `"USDC"`, `"SOL"`). Must match the asset record.
</ParamField>

<ParamField body="chain" type="string" required>
  Blockchain network (e.g. `"ethereum"`, `"solana"`, `"polygon"`).
</ParamField>

<ParamField body="category" type="string" required>
  Transaction category: `"personal"`, `"business"`, `"payment"`, `"auto-forward"`, `"other"`, etc.
</ParamField>

<ParamField body="priority" type="string">
  Gas priority: `"low"`, `"medium"`, `"high"`. Defaults to `"medium"`.
</ParamField>

<ParamField body="description" type="string">
  Optional human-readable note.
</ParamField>

<ParamField body="use_self_funding" type="boolean">
  Pay gas from the wallet's own native balance. Only for native token assets. Defaults to `false`.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

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

  ```python Python theme={null}
  tx = client.transactions.send_funds(
      account='64b1f9e2a3c4d5e6f7a8b9c0',
      assets='64b1f9e2a3c4d5e6f7a8b9d1',
      receiving_address='0x9F8b3A2c1E4D7F6B5A4C3D2E1F0A9B8C7D6E5F4',
      amount=100,
      type='USDC',
      chain='ethereum',
      category='payment',
      priority='medium',
  )
  ```
</CodeGroup>

```json Response theme={null}
{
  "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.

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

***

## 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.

<ParamField body="search" type="string">
  Search by `transaction_id` or `transaction_hash` (case-insensitive substring match).
</ParamField>

<ParamField body="status_filter" type="string">
  Filter by status: `pending`, `completed`, `failed`.
</ParamField>

<ParamField body="assets_filter" type="string">
  Filter by asset ObjectId or asset name substring.
</ParamField>

<ParamField body="method_filter" type="string">
  Filter by transaction `type` field (e.g. `"USDC"`, `"ETH"`).
</ParamField>

<ParamField body="chain_filter" type="string">
  Filter by blockchain (e.g. `"ethereum"`, `"solana"`).
</ParamField>

```bash cURL theme={null}
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"
  }'
```

```json Response theme={null}
{
  "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.

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

<Tip>
  Use webhooks to track transaction status changes in real time instead of polling. See [Webhooks](/yativo-crypto/webhooks) for the `transaction.{type}.completed` and `transaction.failed` event payloads.
</Tip>