0
# Convert API
1

2
Asset conversion functionality for instant and limit conversions between cryptocurrencies. Provides quote-based conversions, limit order conversions, and comprehensive conversion history tracking across spot, margin, and futures accounts.
3

4
## Capabilities
5

6
### Instant Convert Operations
7

8
Get quotes and execute instant conversions between supported assets.
9

10
```python { .api }
11
def convert_request_quote(self, **params): ...
12
def convert_accept_quote(self, **params): ...
13
def get_convert_trade_history(self, **params): ...
14
```
15

16
#### Usage Examples
17

18
```python
19
# Request a conversion quote
20
quote = client.convert_request_quote(
21
    fromAsset='BTC',
22
    toAsset='USDT',
23
    fromAmount=0.1  # Convert 0.1 BTC to USDT
24
)
25

26
print(f"Quote ID: {quote['quoteId']}")
27
print(f"Rate: {quote['ratio']}")
28
print(f"From amount: {quote['fromAmount']} {quote['fromAsset']}")
29
print f"To amount: {quote['toAmount']} {quote['toAsset']}")
30
print(f"Valid until: {quote['validTimestamp']}")
31

32
# Accept the quote to execute conversion
33
conversion = client.convert_accept_quote(
34
    quoteId=quote['quoteId']
35
)
36

37
print(f"Conversion status: {conversion['status']}")
38
print(f"Transaction ID: {conversion['orderId']}")
39

40
# Alternative: Convert by specifying target amount
41
quote_target = client.convert_request_quote(
42
    fromAsset='USDT',
43
    toAsset='BTC',
44
    toAmount=0.05  # Get 0.05 BTC
45
)
46

47
# Get conversion history
48
history = client.get_convert_trade_history(
49
    startTime=int(time.time() * 1000) - (7 * 24 * 60 * 60 * 1000),  # 7 days ago
50
    endTime=int(time.time() * 1000),
51
    limit=100
52
)
53

54
for trade in history['list']:
55
    print(f"Order ID: {trade['orderId']}")
56
    print(f"From: {trade['fromAmount']} {trade['fromAsset']}")
57
    print(f"To: {trade['toAmount']} {trade['toAsset']}")
58
    print(f"Price: {trade['price']}")
59
    print(f"Status: {trade['orderStatus']}")
60
    print(f"Create time: {trade['createTime']}")
61
```
62

63
### Margin Convert Operations
64

65
Convert API functionality specific to margin accounts with limit orders and exchange information.
66

67
```python { .api }
68
def margin_v1_get_convert_exchange_info(self, **params): ...
69
def margin_v1_get_convert_asset_info(self, **params): ...
70
def margin_v1_post_convert_limit_place_order(self, **params): ...
71
def margin_v1_get_convert_limit_query_open_orders(self, **params): ...
72
def margin_v1_post_convert_limit_cancel_order(self, **params): ...
73
def margin_v1_get_convert_order_status(self, **params): ...
74
```
75

76
#### Usage Examples
77

78
```python
79
# Get margin convert exchange information
80
margin_convert_info = client.margin_v1_get_convert_exchange_info()
81
for asset_pair in margin_convert_info['assetPairs']:
82
    print(f"Pair: {asset_pair['fromAsset']} -> {asset_pair['toAsset']}")
83
    print(f"Min from amount: {asset_pair['minFromAmount']}")
84
    print(f"Max from amount: {asset_pair['maxFromAmount']}")
85

86
# Get convert asset information
87
asset_info = client.margin_v1_get_convert_asset_info(asset='BTC')
88
print(f"BTC convertible: {asset_info['convertible']}")
89
print(f"Precision: {asset_info['precision']}")
90

91
# Place margin limit convert order
92
limit_order = client.margin_v1_post_convert_limit_place_order(
93
    fromAsset='BTC',
94
    toAsset='USDT',
95
    fromAmount=0.1,
96
    price=50000  # Target conversion rate
97
)
98

99
print(f"Order ID: {limit_order['orderId']}")
100
print(f"Status: {limit_order['status']}")
101

102
# Check open limit convert orders
103
open_orders = client.margin_v1_get_convert_limit_query_open_orders()
104
for order in open_orders['orders']:
105
    print(f"Order ID: {order['orderId']}")
106
    print(f"From: {order['fromAmount']} {order['fromAsset']}")
107
    print(f"To: {order['toAsset']}")
108
    print(f"Price: {order['price']}")
109
    print(f"Status: {order['status']}")
110

111
# Cancel limit convert order
112
cancel_result = client.margin_v1_post_convert_limit_cancel_order(
113
    orderId=limit_order['orderId']
114
)
115

116
# Get specific order status
117
order_status = client.margin_v1_get_convert_order_status(
118
    orderId=limit_order['orderId']
119
)
120
```
121

122
### Futures Convert Operations
123

124
Convert API functionality for futures accounts.
125

126
```python { .api }
127
def futures_v1_get_convert_exchange_info(self, **params): ...
128
def futures_v1_post_convert_get_quote(self, **params): ...
129
def futures_v1_post_convert_accept_quote(self, **params): ...
130
def futures_v1_get_convert_order_status(self, **params): ...
131
```
132

133
#### Usage Examples
134

135
```python
136
# Get futures convert exchange information
137
futures_convert_info = client.futures_v1_get_convert_exchange_info()
138
print(f"Supported conversions: {futures_convert_info['assetPairs']}")
139

140
# Get futures conversion quote
141
futures_quote = client.futures_v1_post_convert_get_quote(
142
    fromAsset='BTC',
143
    toAsset='USDT',
144
    fromAmount=0.1
145
)
146

147
print(f"Quote ID: {futures_quote['quoteId']}")
148
print(f"Conversion rate: {futures_quote['price']}")
149
print(f"Valid until: {futures_quote['expiredTimestamp']}")
150

151
# Accept futures conversion quote
152
futures_conversion = client.futures_v1_post_convert_accept_quote(
153
    quoteId=futures_quote['quoteId']
154
)
155

156
print(f"Order ID: {futures_conversion['orderId']}")
157
print(f"Status: {futures_conversion['status']}")
158

159
# Check futures conversion order status
160
futures_status = client.futures_v1_get_convert_order_status(
161
    orderId=futures_conversion['orderId']
162
)
163
```
164

165
### Asset Transfer Conversions
166

167
Convert assets during transfers between different account types.
168

169
```python { .api }
170
def margin_v1_post_asset_convert_transfer(self, **params): ...
171
def margin_v1_post_asset_convert_transfer_query_by_page(self, **params): ...
172
```
173

174
#### Usage Examples
175

176
```python
177
# Convert asset during transfer
178
convert_transfer = client.margin_v1_post_asset_convert_transfer(
179
    clientTranId='unique_transfer_id_123',
180
    asset='BTC',
181
    amount=0.1,
182
    targetAsset='USDT',
183
    accountType='SPOT'  # Target account type
184
)
185

186
print(f"Transfer ID: {convert_transfer['tranId']}")
187
print(f"Status: {convert_transfer['status']}")
188

189
# Query convert transfer history
190
transfer_history = client.margin_v1_post_asset_convert_transfer_query_by_page(
191
    startTime=int(time.time() * 1000) - (30 * 24 * 60 * 60 * 1000),  # 30 days ago
192
    endTime=int(time.time() * 1000),
193
    current=1,  # Page number
194
    size=20     # Page size
195
)
196

197
for transfer in transfer_history['rows']:
198
    print(f"Transfer ID: {transfer['tranId']}")
199
    print(f"From: {transfer['amount']} {transfer['asset']}")
200
    print(f"To: {transfer['targetAmount']} {transfer['targetAsset']}")
201
    print(f"Status: {transfer['status']}")
202
    print(f"Create time: {transfer['createTime']}")
203
```
204

205
### Convertible Coins Management
206

207
Manage convertible coin contracts and balances.
208

209
```python { .api }
210
def margin_v1_get_capital_contract_convertible_coins(self, **params): ...
211
def margin_v1_post_capital_contract_convertible_coins(self, **params): ...
212
```
213

214
#### Usage Examples
215

216
```python
217
# Get convertible coins information
218
convertible_coins = client.margin_v1_get_capital_contract_convertible_coins()
219

220
for coin in convertible_coins['convertibleCoins']:
221
    print(f"Coin: {coin['coin']}")
222
    print(f"Convertible amount: {coin['convertibleAmount']}")
223
    print(f"Convertible: {coin['convertible']}")
224
    print(f"Exchange rate: {coin['exchangeRate']}")
225

226
# Execute convertible coin conversion
227
conversion_result = client.margin_v1_post_capital_contract_convertible_coins(
228
    coin='USDC',
229
    amount=100,
230
    targetCoin='USDT'
231
)
232

233
print(f"Conversion ID: {conversion_result['convertId']}")
234
print(f"Status: {conversion_result['status']}")
235
```
236

237
## Convert Order Status Values
238

239
```python { .api }
240
# Convert order status constants
241
CONVERT_ORDER_STATUS_PROCESSING = "PROCESSING"
242
CONVERT_ORDER_STATUS_SUCCESS = "SUCCESS"
243
CONVERT_ORDER_STATUS_CONVERT_SUCCESS = "CONVERT_SUCCESS" 
244
CONVERT_ORDER_STATUS_PROCESS_FAIL = "PROCESS_FAIL"
245
CONVERT_ORDER_STATUS_ACCEPTED = "ACCEPTED"
246
```
247

248
## Error Handling
249

250
```python
251
from binance import BinanceAPIException
252

253
try:
254
    quote = client.convert_request_quote(
255
        fromAsset='BTC',
256
        toAsset='USDT', 
257
        fromAmount=0.1
258
    )
259
    
260
    conversion = client.convert_accept_quote(quoteId=quote['quoteId'])
261
    
262
except BinanceAPIException as e:
263
    if e.code == -1200:
264
        print("Invalid conversion parameters")
265
    elif e.code == -1201:
266
        print("Quote expired or invalid")
267
    elif e.code == -1202:
268
        print("Insufficient balance for conversion")
269
    else:
270
        print(f"Conversion error: {e.message}")
271
```
272

273
## Rate Limiting
274

275
Convert API operations are subject to rate limits:
276

277
- Quote requests: 100 requests per 10 seconds
278
- Accept quote: 5 requests per 1 second  
279
- History queries: 3000 requests per 5 minutes
280

281
The Convert API provides comprehensive asset conversion capabilities across all Binance account types with both instant and limit order functionality, extensive history tracking, and advanced transfer conversion features.