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

# Send Funds

> Send cryptocurrency from a wallet asset to an external address or another account

<ParamField header="Authorization" type="string" required>
  Bearer token: `Bearer YOUR_ACCESS_TOKEN`
</ParamField>

<ParamField header="Idempotency-Key" type="string">
  Unique key to prevent duplicate transactions. Strongly recommended — if omitted, no deduplication is applied. Re-submit the same key to safely retry without double-spending. Keys expire after 24 hours.
</ParamField>

<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. Returned when you [list account assets](/api-reference/assets/list).
</ParamField>

<ParamField body="receiving_address" type="string" required>
  The destination blockchain address. Must be a valid address on the target chain.
</ParamField>

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

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

<ParamField body="chain" type="string" required>
  The blockchain network (e.g. `"ethereum"`, `"solana"`, `"polygon"`). Must match the asset's chain.
</ParamField>

<ParamField body="category" type="string" required>
  Transaction category for reporting and compliance. Common values: `"personal"`, `"business"`, `"payment"`, `"auto-forward"`, `"other"`.
</ParamField>

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

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

<ParamField body="use_self_funding" type="boolean">
  When `true`, gas fees are paid from the sending wallet's own native token balance instead of a configured Gas Station. Only valid for native token assets (ETH, SOL, etc.). Defaults to `false`.
</ParamField>

<RequestExample>
  ```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' \
    -H 'Idempotency-Key: idem_01HX9KZMB3F7VNQP8R2WDGT4E5' \
    -d '{
      "account": "64b1f9e2a3c4d5e6f7a8b9c0",
      "assets": "64b1f9e2a3c4d5e6f7a8b9d1",
      "receiving_address": "9xZ7Y4mQkLpR3sVwC8tF2bG6hJ5nM1yK",
      "amount": 100,
      "type": "USDC",
      "chain": "solana",
      "category": "payment",
      "priority": "medium",
      "description": "Invoice #1042 settlement"
    }'
  ```

  ```typescript TypeScript theme={null}
  const tx = await client.transactions.sendFunds({
    account: '64b1f9e2a3c4d5e6f7a8b9c0',
    assets: '64b1f9e2a3c4d5e6f7a8b9d1',
    receiving_address: '9xZ7Y4mQkLpR3sVwC8tF2bG6hJ5nM1yK',
    amount: 100,
    type: 'USDC',
    chain: 'solana',
    category: 'payment',
    priority: 'medium',
    description: 'Invoice #1042 settlement',
  });
  ```

  ```python Python theme={null}
  tx = client.transactions.send_funds(
      account='64b1f9e2a3c4d5e6f7a8b9c0',
      assets='64b1f9e2a3c4d5e6f7a8b9d1',
      receiving_address='9xZ7Y4mQkLpR3sVwC8tF2bG6hJ5nM1yK',
      amount=100,
      type='USDC',
      chain='solana',
      category='payment',
      priority='medium',
      description='Invoice #1042 settlement',
  )
  ```
</RequestExample>

<ResponseExample>
  ```json 200 — Success theme={null}
  {
    "status": true,
    "message": "Transaction Created Successfully",
    "data": {
      "transaction_id": "txn_01HX9KZMB3F7VNQP8R2WDGT4E5",
      "transaction_hash": "5KtMKNmZtEbXq3RrsPkjDqNJVA5rtzEPvR8WBa7kLnZm",
      "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"
    }
  }
  ```

  ```json 400 — Validation error theme={null}
  {
    "status": false,
    "message": "Withdrawal amount must be greater than total fees. Amount: 0.5, Platform fee: 0.5, Gas funding fee: 0.12"
  }
  ```

  ```json 400 — Self-funding on token theme={null}
  {
    "status": false,
    "message": "Self funding is only available for native token transactions. For USDC transactions on polygon, you need approximately 0.002 POL"
  }
  ```

  ```json 403 — Account suspended theme={null}
  {
    "status": false,
    "message": "Account is suspended from withdrawals",
    "suspension": {
      "type": "withdrawal",
      "reason": "Compliance review",
      "expires_at": null
    }
  }
  ```

  ```json 409 — Duplicate in-progress (idempotency) theme={null}
  {
    "success": false,
    "message": "Request is already being processed",
    "error": "DUPLICATE_REQUEST_IN_PROGRESS",
    "idempotencyKey": "payout_ORD-9821"
  }
  ```

  ```json 500 — Transaction blocked (high-risk address) theme={null}
  {
    "status": false,
    "message": "Transaction blocked due to high-risk receiving address"
  }
  ```
</ResponseExample>

## Gas Funding

When sending **token** assets (USDC, USDT, etc.) the platform automatically funds native gas from a configured Gas Station. A 20% service markup on the gas cost is deducted from your withdrawal amount as `gas_funding_markup`.

| Scenario                                      | Behaviour                                                            |
| --------------------------------------------- | -------------------------------------------------------------------- |
| Gas Station configured by user                | Gas funded from user's gas station — `gas_funding_markup` applied    |
| No user Gas Station                           | Platform Gas Station used as fallback — `gas_funding_markup` applied |
| `use_self_funding: true` (native tokens only) | Gas deducted from the wallet's own native balance — no markup        |
| `use_self_funding: true` on a token asset     | Returns `400` — self-funding is not available for token transactions |

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

## Idempotency

Supply an `Idempotency-Key` header to enable safe retries. If the same key is submitted again for the same user, the original response is returned instead of creating a duplicate transaction. Without a key, no deduplication is applied.

**Best practices:**

* Derive the key from your internal record ID: `payout_${orderId}`
* Keys must be unique per operation — reusing a key for a different transfer returns the original transaction
* Keys expire after 24 hours

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