Conversion Transaction

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 guide.
Familiarity with the following core concepts:

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

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

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

  "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"
}

Save this quote ID - you’ll need it for the conversion transaction.

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.

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

Source Types

The source field can be either:

Account ID (acct_... or 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_... or id:bank-account:...) - 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_... or id:bank-account:...) 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)

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

{
  "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"
}

Fiat-to-Fiat Conversions

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

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

{
  "id": "quote_2nqjHpNLK6wSNlFyMvZgX8SYeAO",
  "source": {
    "asset": "USD",
    "amount": "1000.00"
  },
  "target": {
    "asset": "EUR",
    "amount": "915.00"
  }
}

Save this quote ID - you’ll need it for the conversion transaction.

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_... or 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_... or id:bank-account:...) - 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)

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:

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

{
  "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"
}

Monitor Transaction Status

After creating the transaction, you can track its progress using the Transaction Status field.
You can listen to webhook 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 iscompleted, 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_... or id:acct:...) for USD balance conversions (funds already in system)
- Bank account ID (bank_... or id:bank-account:...) 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 (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

{
  "source": "wlt_2kezVryAA3Uw9LJYBiXUV7Pj6gu",
  "destination": "wlt_2nqjHpNLK6wSNlFyMvZgX8SYeAO"
}

Response example

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

Solution:

For source: Use account IDs (acct_... or id:acct:...) for USD balance conversions, or bank account IDs (bank_... or id:bank-account:...) 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

{
  "source": "acct_2kezVryAA3Uw9LJYBiXUV7Pj6gu",
  "destination": "acct_2nqjHpNLK6wSNlFyMvZgX8SYeAO"
}

Invalid or expired quote

Request example

{
  "quote": "quote_2nqjHpNLK6wSNlFyMvZgX8SYeAO"
}

Response example

{
  "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

{
  "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

{
  "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.
Review Transactions Core Concepts.

API Reference

Also check our API Reference to learn how to create conversion transactions using our API.

Support

Reach out to our support team to get help and share your feedback.

Getting started

Guides

Developer Tools

Pre-requisites

Crypto-to-Crypto Conversions

Request Example

Response Example

Source Types

Destination Types

Request Examples

Crypto-to-Crypto Conversion (Account IDs)

Response Example

Fiat-to-Fiat Conversions

Request Example

Response Example

Source Types

Request Examples

Fiat-to-Fiat Conversion (External Bank Account)

Fiat-to-Fiat Conversion (USD Balance)

Response Example

Monitor Transaction Status

Summary

Troubleshooting

Quick checklist

Common errors

Invalid source or destination ID

Invalid or expired quote

Insufficient funds

Incompatible networks

What’s next?

API Reference

Support

Getting started

Guides

Developer Tools

​Pre-requisites

​Crypto-to-Crypto Conversions

​Request Example

​Response Example

​Source Types

​Destination Types

​Request Examples

​Crypto-to-Crypto Conversion (Account IDs)

​Response Example

​Fiat-to-Fiat Conversions

​Request Example

​Response Example

​Source Types

​Request Examples

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

​Fiat-to-Fiat Conversion (USD Balance)

​Response Example

​Monitor Transaction Status

​Summary

​Troubleshooting

​Quick checklist

​Common errors

​Invalid source or destination ID

​Invalid or expired quote

​Insufficient funds

​Incompatible networks

​What’s next?

​API Reference

​Support

Pre-requisites

Crypto-to-Crypto Conversions

Request Example

Response Example

Source Types

Destination Types

Request Examples

Crypto-to-Crypto Conversion (Account IDs)

Response Example

Fiat-to-Fiat Conversions

Request Example

Response Example

Source Types

Request Examples

Fiat-to-Fiat Conversion (External Bank Account)

Fiat-to-Fiat Conversion (USD Balance)

Response Example

Monitor Transaction Status

Summary

Troubleshooting

Quick checklist

Common errors

Invalid source or destination ID

Invalid or expired quote

Insufficient funds

Incompatible networks

What’s next?

API Reference

Support