Create conversion

Creates a new conversion request to exchange one asset for another. The conversion will be processed asynchronously.

POST /trade/v1/conversions

Create conversion

cURL

curl --request POST \
  --url https://api.staging.layer1.com/trade/v1/conversions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reference": "my-conversion-ref-123",
  "from": {
    "asset": "BTC",
    "amount": "0.1"
  },
  "to": {
    "asset": "USD"
  }
}
'

202

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "reference": "my-conversion-ref-123",
  "status": "PENDING",
  "from": {
    "asset": "BTC",
    "amount": "0.1"
  },
  "to": {
    "asset": "USD"
  },
  "executor": "TAKER",
  "createdAt": "2023-10-01T12:00:00Z"
}

Body

application/json

Conversion request containing source asset, destination asset, and amount details

reference · string

Client supplied unique identifier for the conversion. This reference can be used to uniquely identify this request. Useful for idempotency and traceability

Example:

"myUniqueRef333"

from · object

From amount

Show child attributes

Example:

{ "asset": "USD", "amount": 100 }

to · object

To amount

Show child attributes

Example:

{ "asset": "EUR" }

executor · enum<string>

Execution strategy

Available options: MAKER, TAKER, MAKER_TAKER, MARKET, TWAP

metadata · object

Client supplied metadata about the request

Show child attributes

Example:

{ "customer": "BigBlue", "id": "12345" }

venues · string[]

A set of venue identifiers to restrict where the order may be executed. Only the specified venues will be considered for execution. Leave empty or null to allow execution on any available venue

Example:

["kraken", "binance"]

venueAccounts · string[]

A set of venue account identifiers where the order may be executed. Only the specified venues will be considered for execution. Leave empty or null to allow execution on any available venue accounts

Example:

["kraken-favorite", "binance-123"]

expiresAt · string<date-time>

Timestamp before which the conversion must be executed. If the conversion is not executed before this time, it will stop processing and marked as expired

Example:

"2024-01-01T00:00:00Z"

Response

202

application/json

Conversion request accepted and will be processed asynchronously

id · string<uuid>

system generated id for conversion

Example:

"d43af94c-4d70-4917-aa05-22014c2c6079"

reference · string

client supplied unique identifier for the conversion. This reference can be used to uniquely identify this request. Useful for idempotency and traceability

Example:

"myUniqueRef333"

status · enum<string>

Conversion status

Available options: SIMULATED, PENDING, PROCESSING, PENDING_CANCEL, CANCELLED, COMPLETED, FAILED

from · object

From amount

Show child attributes

Example:

{ "asset": "USD", "amount": 100 }

to · object

To amount

Show child attributes

Example:

{ "asset": "EUR", "amount": 89.58 }

orders · object[]

Show child attributes

executor · enum<string>

Execution strategy

Available options: MAKER, TAKER, MAKER_TAKER, MARKET, TWAP

movements · object[]

Net change in asset based on executed orders

Show child attributes

Example:

[
  { "asset": "USD", "amount": -100 },
  { "asset": "EUR", "amount": 90.01 }
]

createdAt · string<date-time>

Timestamp at which conversion was created

Example:

"2024-01-01T00:00:00Z"

metadata · object

Client supplied metadata about the request

Show child attributes

Example:

{ "customer": "BigBlue", "id": "12345" }

venues · object[]

A set of venue identifiers to restrict where the order may be executed. Only the specified venues will be considered for execution. Leave empty or null to allow execution on any available venue

Show child attributes

Example:

["kraken", "binance"]

venueAccounts · string[]

A set of venue account identifiers where the order may be executed. Only the specified venues will be considered for execution. Leave empty or null to allow execution on any available venue accounts

Example:

["kraken-favorite", "binance-123"]

expiresAt · string<date-time>

Timestamp before which the conversion must be executed. If the conversion is not executed before this time, it will stop processing and marked as expired

Example:

"2024-01-01T00:00:00Z"

direction · enum<string>

Direction of conversion indicating whether from amount or to amount was supplied in conversion request

Available options: FIXED_FROM_AMOUNT, FIXED_TO_AMOUNT

failureMessage · string