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

# Conversion Transaction

> This guide shows how to create your first conversion transaction on Conduit using the Transaction API.

## Pre-requisites

* Active Conduit account with API access.
* API credentials (API Key and Secret).
* A customer created as described in the [Create Your First Customer](/guides/customer/onboarding-customer) guide.
* Familiarity with the following core concepts:
  * [Quotes](/core-concepts/quotes)
  * [Transactions](/core-concepts/transactions)
  * [Payment Methods](/core-concepts/payment-methods)

In this guide, you’ll create your first conversion transaction — converting cryptocurrency to fiat currency. For example, we’ll convert 1000 USDC on Ethereum to USDT on Tron.

## Crypto-to-Crypto Conversions

<Steps>
  <Step title="Create a quote">
    To create a quote, call the `/quotes` endpoint. This provides the current conversion rate for the given source and destination assets.

    ### Request Example

    ```bash theme={null}
    curl --request POST \
      --url https://api.conduit.financial/quotes \
      --header "X-API-Key: your_api_key" \
      --header "X-API-Secret: your_api_secret" \
      --header "Content-Type: application/json" \
      --header "Api-Version: 2024-12-01" \
      --data '{
        "source": {
          "asset": "USDC",
          "network": "ethereum",
          "amount": "1000.00"
        },
        "target": {
          "asset": "USDT",
          "network": "tron"
        }
      }'

    ```

    ### Response Example

    ```json { theme={null}
      "id": "quote_2nqjHpNLK6wSNlFyMvZgX8SYeAO",
      "source": {
        "asset": "USDC",
        "network": "ethereum",
        "amount": "1000.000000"
      },
      "target": {
        "asset": "USDT",
        "network": "tron",
        "amount": "998.500000"
      },
      "createdAt": "2024-10-26T02:21:03.742Z",
      "expiresAt": "2024-10-26T02:24:03.742Z"
    }
    ```

    <Note>
      Save this quote ID - you'll need it for the conversion transaction.
    </Note>
  </Step>

  <Step title="Create a conversion transaction">
    To execute the conversion, call the `/transactions` endpoint with your quote ID. This creates a **conversion transaction** between your Conduit custody accounts.

    <Note>
      Conversion transactions are used to convert assets or networks within your own Conduit custody — not to send funds to external wallets or third parties.
    </Note>

    ### Source Types

    The `source` field can be either:

    * **Account ID** (`acct_...`) - For USD balance conversions (fiat-to-fiat only). Funds are already in the system, so no external pay-in is required. Processing is faster and skips compliance screening. **Note:** If both source and destination are account IDs, the system automatically routes to `BALANCE_CONVERSION` transaction type (crypto-to-crypto).
    * **Bank Account ID** (`bank_...`) - For external bank account conversions (fiat-to-fiat). Requires external pay-in from the bank account before conversion can proceed.

    ### Destination Types

    The `destination` field must be a **Bank Account ID** (`bank_...`) for CONVERSION transactions. **Note:** If both source and destination are account IDs, the system automatically routes to `BALANCE_CONVERSION` transaction type (crypto-to-crypto), not CONVERSION.

    ### Request Examples

    #### Crypto-to-Crypto Conversion (Account IDs)

    ```bash theme={null}
    curl --request POST \
      --url https://api.conduit.financial/transactions \
      --header "X-API-Key: your_api_key" \
      --header "X-API-Secret: your_api_secret" \
      --header "Content-Type: application/json" \
      --header "Api-Version: 2024-12-01" \
      --data '{
        "type": "conversion",
        "quote": "quote_2nqjHpNLK6wSNlFyMvZgX8SYeAO",
        "source": "acct_3wghbZOojOc7MggcwSXlYl1193K",
        "destination": "acct_3wghbZOojOc7MggcwSXlYl1193K",
        "documents": ["doc_2nqjHpNLK6wSNlFyMvZgX8SYeAO"],
        "purpose": "Other",
        "reference": "TRX#09123A"
      }'
    ```

    ### Response Example

    ```json theme={null}
    {
      "type": "conversion",
      "id": "trxn_2abc...",
      "quote": "quote_2nqjHpNLK6wSNlFyMvZgX8SYeAO",
      "source": {
        "id": "acct_3wghbZOojOc7MggcwSXlYl1193K",
        "asset": "USDC",
        "network": "ethereum",
        "amount": "1000.00"
      },
      "destination": {
        "id": "acct_3wghbZOojOc7MggcwSXlYl1193K",
        "asset": "USDT",
        "network": "tron",
        "amount": "998.50"
      },
      "status": "created",
      "createdAt": "2024-10-26T02:21:03.742Z"
    }
    ```
  </Step>
</Steps>

## Fiat-to-Fiat Conversions

<Steps>
  <Step title="Create a quote">
    To create a quote, call the `/quotes` endpoint. This provides the current conversion rate for the given source and destination currencies.

    ### Request Example

    ```bash theme={null}
    curl --request POST \
      --url https://api.conduit.financial/quotes \
      --header "X-API-Key: your_api_key" \
      --header "X-API-Secret: your_api_secret" \
      --header "Content-Type: application/json" \
      --header "Api-Version: 2024-12-01" \
      --data '{
        "source": {
          "asset": "USD",
          "amount": "1000.00"
        },
        "target": {
          "asset": "EUR"
        }
      }'
    ```

    ### Response Example

    ```json theme={null}
    {
      "id": "quote_2nqjHpNLK6wSNlFyMvZgX8SYeAO",
      "source": {
        "asset": "USD",
        "amount": "1000.00"
      },
      "target": {
        "asset": "EUR",
        "amount": "915.00"
      }
    }
    ```

    <Note>
      Save this quote ID - you'll need it for the conversion transaction.
    </Note>
  </Step>

  <Step title="Create a conversion transaction">
    To execute the conversion, call the `/transactions` endpoint with your quote ID. This creates a **conversion transaction** between your Conduit custody accounts.

    ### Source Types

    The `source` field can be either:

    * **Account ID** (`acct_...`) - For USD balance conversions (fiat-to-fiat only). Funds are already in the system, so no external pay-in is required. Processing is faster and skips compliance screening. **Note:** If both source and destination are account IDs, the system automatically routes to `BALANCE_CONVERSION` transaction type (crypto-to-crypto).
    * **Bank Account ID** (`bank_...`) - For external bank account conversions (fiat-to-fiat). Requires external pay-in from the bank account before conversion can proceed.

    ### Request Examples

    #### Fiat-to-Fiat Conversion (External Bank Account)

    ```bash theme={null}
    curl --request POST \
      --url https://api.conduit.financial/transactions \
      --header "X-API-Key: your_api_key" \
      --header "X-API-Secret: your_api_secret" \
      --header "Content-Type: application/json" \
      --header "Api-Version: 2024-12-01" \
      --data '{
        "type": "conversion",
        "quote": "quote_2nqjHpNLK6wSNlFyMvZgX8SYeAO",
        "source": "bank_3wghbZOojOc7MggcwSXlYl1193K",
        "destination": "bank_3wghbZOojOc7MggcwSXlYl1193K",
        "documents": ["doc_2nqjHpNLK6wSNlFyMvZgX8SYeAO"],
        "purpose": "Other",
        "reference": "TRX#09123A"
      }'
    ```

    #### Fiat-to-Fiat Conversion (USD Balance)

    For conversions from USD balances, use an account ID as the source:

    ```bash theme={null}
    curl --request POST \
      --url https://api.conduit.financial/transactions \
      --header "X-API-Key: your_api_key" \
      --header "X-API-Secret: your_api_secret" \
      --header "Content-Type: application/json" \
      --header "Api-Version: 2024-12-01" \
      --data '{
        "type": "conversion",
        "quote": "quote_2nqjHpNLK6wSNlFyMvZgX8SYeAO",
        "source": "acct_3wghbZOojOc7MggcwSXlYl1193K",
        "destination": "bank_3wghbZOojOc7MggcwSXlYl1193K",
        "purpose": "Other",
        "reference": "TRX#09123A"
      }'
    ```

    ### Response Example

    ```json theme={null}
    {
      "type": "conversion",
      "id": "trxn_2abc...",
      "quote": "quote_2nqjHpNLK6wSNlFyMvZgX8SYeAO",
      "source": {
        "id": "bank_3wghbZOojOc7MggcwSXlYl1193K",
        "asset": "USD",
        "amount": "1000.00"
      },
      "destination": {
        "id": "bank_3wghbZOojOc7MggcwSXlYl1193K",
        "asset": "EUR",
        "amount": "915.00"
      },
      "status": "created",
      "createdAt": "2024-10-26T02:21:03.742Z"
    }
    ```
  </Step>
</Steps>

### Monitor Transaction Status

After creating the transaction, you can track its progress using the **Transaction Status** field.\
You can listen to [webhook](/developer-sections/webhooks) events to stay updated as the transaction moves through each stage of processing.

| Status                    | Description                          |
| :------------------------ | :----------------------------------- |
| **initializing**          | Transaction is being set up          |
| **created**               | Transaction created successfully     |
| **processing conversion** | Converting assets between networks   |
| **completed**             | USDT delivered to your Tron wallet ✅ |

## Summary

Once the status is`completed`, your conversion is finalized.

**What just happened:**

* USDC or USD was withdrawn from your Conduit custody account.
* Conduit converted it to USDT or EUR at the quoted rate.
* USDT or EUR was deposited into your Conduit custody account or bank account.
* All applicable network fees were included in the quote.

## Troubleshooting

Use this section to quickly diagnose and resolve common conversion errors.

### Quick checklist

* Use appropriate IDs for `source`:
  * Account ID (`acct_...`) for USD balance conversions (funds already in system)
  * Bank account ID (`bank_...`) for external bank account conversions (requires external pay-in)
* Use bank account ID (`bank_...`) or Account ID (`acct_...`) for `destination`
* Use a valid, unexpired [quote](/core-concepts/quotes) (valid for 3 minutes)
* Ensure sufficient balance in the source account (for USD balance conversions) or arrange external pay-in (for external bank account conversions)
* Verify the conversion pair is supported (networks and assets)

### Common errors

#### Invalid source or destination ID

Incorrect: using wallet IDs

**Request example**

```json theme={null}
{
  "source": "wlt_2kezVryAA3Uw9LJYBiXUV7Pj6gu",
  "destination": "wlt_2nqjHpNLK6wSNlFyMvZgX8SYeAO"
}
```

**Response example**

```json theme={null}
{
"errors": [{
"details": "source: Invalid id format. Expected format: ^acct_[a-zA-Z0-9]{27}$"
}]
}
```

**Solution:**

* For `source`: Use account IDs (`acct_...`) for USD balance conversions, or bank account IDs (`bank_...`) for external bank account conversions. Do not use wallet IDs (`wlt_...`).
* For `destination`: Use account IDs (`acct_...`) or bank account IDs (`bank_...`). Do not use wallet IDs (`wlt_...`).

**Correct:** using account IDs (custody accounts)

**Request example**

```json theme={null}
{
  "source": "acct_2kezVryAA3Uw9LJYBiXUV7Pj6gu",
  "destination": "acct_2nqjHpNLK6wSNlFyMvZgX8SYeAO"
}
```

#### Invalid or expired quote

**Request example**

```json theme={null}
{
  "quote": "quote_2nqjHpNLK6wSNlFyMvZgX8SYeAO"
}
```

**Response example**

```json theme={null}
{
  "errors": [{
    "detail": "Quote has expired or is invalid",
    "code": "INVALID_QUOTE"
  }]
}
```

**Solution:** Generate a new quote and retry. Quotes expire after 3 minutes.

#### Insufficient funds

**Response example**

```json theme={null}
{
  "errors": [{
    "detail": "Insufficient balance in source wallet",
    "code": "INSUFFICIENT_FUNDS"
  }]
}
```

**Solution:** Check your source custody account balance. Ensure you have enough to cover both the conversion amount and network fees.

#### Incompatible networks

**Response example**

```json theme={null}
{
  "errors": [{
    "detail": "Conversion not supported between these networks",
    "code": "UNSUPPORTED_CONVERSION"
  }]
}
```

**Solution:** Verify that both networks are supported. Check the quote response for available conversion pairs.

## What's next?

* Set up webhooks to receive transaction status updates: [Configuring Your First Webhook](/guides/webhooks/first-webhook).
* Review [Transactions](/core-concepts/transactions) Core Concepts.

## API Reference

Also check our [API Reference](/api-reference/transactions/create-a-transaction) to learn how to create conversion transactions using our API.

## Support

Reach out to our [support team](https://support.conduitpay.com/) to get help and share your feedback.