swap.v1.SwapService
CreateSwap
CreateSwap creates the Swap for idempotency_key and executes it at once. It re-prices the terms against current depth first: the Swap is created only while the quote is unexpired and min_amount_out_e18 is achievable. It is idempotent per caller and key: a repeated or concurrent request with the same body returns the same Swap, so every unknown outcome is resolved by repeating the request unchanged. Errors: - INVALID_ARGUMENT: malformed request, AMOUNT_OUT_OF_RANGE or INVALID_SUBACCOUNT_ID. - FAILED_PRECONDITION: ROUTE_UNSUPPORTED, DIRECTION_UNSUPPORTED, PROTECTION_UNACHIEVABLE, QUOTE_EXPIRED or SUBACCOUNT_INACTIVE; nothing is created. - ALREADY_EXISTS: IDEMPOTENCY_CONFLICT; the original Swap stands. - NOT_FOUND: SUBACCOUNT_NOT_FOUND. - PERMISSION_DENIED: SWAP_NOT_PERMITTED. - UNAVAILABLE, DEADLINE_EXCEEDED: QUOTE_UNAVAILABLE, SERVICE_UNAVAILABLE or an unknown outcome; retry the same request. - UNAUTHENTICATED: missing or invalid credentials.
Request
curl --request POST \ \
--url 'https://api.testnet.polyester.com/swap.v1.SwapService/CreateSwap' \
--header 'Content-Type: application/json' \
--header 'Connect-Protocol-Version: 1' \
--data '{
"idempotencyKey": "idem_01J5EXAMPLE0000000000000",
"minAmountOutE18": {
"hi": "1",
"lo": "1"
},
"quoteExpiresAt": "2025-01-01T00:00:00Z",
"terms": {
"amountE18": {
"hi": "1",
"lo": "1"
},
"destinationAssetId": 100,
"sourceAssetId": 100,
"subaccountId": "6789012345678"
}
}'Responses
{
"swap": {
"amountE18": {
"hi": "1",
"lo": "1"
},
"createdAt": "2025-01-01T00:00:00Z",
"destinationAssetId": 100,
"executedAmountE18": {
"hi": "1",
"lo": "1"
},
"feeE18": {
"hi": "1",
"lo": "1"
},
"idempotencyKey": "idem_01J5EXAMPLE0000000000000",
"isTerminal": false,
"minAmountOutE18": {
"hi": "1",
"lo": "1"
},
"orders": [
{
"feeE18": {
"hi": "1",
"lo": "1"
},
"leg": 1,
"limitPriceTicks": "61000250000000",
"orderId": "9876543210123",
"receivedE18": {
"hi": "1",
"lo": "1"
},
"side": "BUY",
"spentE18": {
"hi": "1",
"lo": "1"
},
"status": "PLACING",
"symbolId": 1
}
],
"reason": "INSUFFICIENT_BALANCE",
"receivedAmountE18": {
"hi": "1",
"lo": "1"
},
"sourceAssetId": 100,
"status": "EXECUTING",
"subaccountId": "6789012345678",
"swapId": "1",
"unspentAmountE18": {
"hi": "1",
"lo": "1"
}
}
}swap.v1.CreateSwapRequestswap.v1.CreateSwapResponseClient-chosen key, unique per caller, that makes creation idempotent: the same key and request return the same Swap; another request with the same key is IDEMPOTENCY_CONFLICT.
Optional sub-account public ID whose Trading balance funds the Swap. When omitted, the caller's root account funds it, or the sub-account an API key is bound to.
Asset spent: a unified asset ID, as used for balances and internal transfers.
Asset received: a unified asset ID.
Most significant 64 bits.
Least significant 64 bits.
Most significant 64 bits.
Least significant 64 bits.
The accepted quote's expires_at. The Swap is refused with QUOTE_EXPIRED once it has passed.
Swap ID.
Idempotency key the Swap was created with.
Sub-account public ID funding the Swap; 0 for the root account.
Asset spent.
Asset received.
Most significant 64 bits.
Least significant 64 bits.
Most significant 64 bits.
Least significant 64 bits.
Current status.
Why the Swap did not trade its whole amount; set with PARTIALLY_COMPLETED and FAILED.
True once the status is final: COMPLETED, PARTIALLY_COMPLETED or FAILED.
Most significant 64 bits.
Least significant 64 bits.
Most significant 64 bits.
Least significant 64 bits.
Most significant 64 bits.
Least significant 64 bits.
Most significant 64 bits.
Least significant 64 bits.
Spot order ID, once the market accepted the order; 0 before.
Stable numeric pair ID from GetSpotConfig.
Side of the order.
Zero-based position of the order's market in the Swap's route.
State of the order.
Limit price in quote-asset price ticks (1e-9 quote units per base unit): the worst price at which the order nets the Swap's minimum rate after fees.
Most significant 64 bits.
Least significant 64 bits.
Most significant 64 bits.
Least significant 64 bits.
Most significant 64 bits.
Least significant 64 bits.
When the Swap was created.
| Key | HTTP status | Connect code | Error | When |
|---|---|---|---|---|
| unauthenticated | 401 | unauthenticated | Unauthenticated | Authentication required. |
| permission-denied | 403 | permission_denied | Permission Denied | Permission denied. |
| invalid-argument | 400 | invalid_argument | Invalid Argument | Invalid argument. |
| not-found | 404 | not_found | Not Found | Not found. |
| unavailable | 503 | unavailable | Unavailable | Service unavailable. |