> For the complete documentation index, see [llms.txt](https://docs.betaramps.com/documentation-beta-ramps/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.betaramps.com/documentation-beta-ramps/exchange-crypto-to-fiat/buy-sell-orders.md).

# Buy/Sell Orders

{% hint style="success" %}
If you are a neobank or fintech app, reach out to our team to activate the **`pool_balance`** features.
{% endhint %}

## Create a New Order

<mark style="color:green;">`POST`</mark> `https://live.betaapp.com/v1/order/exchange`

Beta will freeze the quote for this order for 20 minutes.

\
If the User deposits a different amount/asset than requested or after this timeframe, our platform will automatically trigger workflows for the payer to top-up the remaining amount or receive a refund for its deposit.

#### Headers

| Name                                               | Type   | Description            |
| -------------------------------------------------- | ------ | ---------------------- |
| Authorization<mark style="color:red;">\*</mark>    | String | Bearer {access\_token} |
| x-sub-account-id<mark style="color:red;">\*</mark> | String | subaccount ID          |
| accept<mark style="color:red;">\*</mark>           | String | application/json       |

#### Request Body

| Name                                            | Type    | Description                                                                            |
| ----------------------------------------------- | ------- | -------------------------------------------------------------------------------------- |
| source\_asset<mark style="color:red;">\*</mark> | String  | *Asset that user wants to provide in the transaction. It could be any Fiat or Crypto.* |
| target\_asset<mark style="color:red;">\*</mark> | String  | *Asset that user wants to receive in the transaction. It could be any Fiat or Crypto.* |
| network                                         | String  | Crypto network                                                                         |
| source\_amount                                  | String  | Amount that payer wants to deposit                                                     |
| pool\_balance                                   | Boolean | True or False.                                                                         |
| target\_amount                                  | String  | Amount that payer wants to receive                                                     |

{% tabs %}
{% tab title="200: OK Sucess" %}

```json
{
  "amount": 0,
  "asset": {
    "large_image_url": "string",
    "medium_image_url": "string",
    "name": "string",
    "small_image_url": "string",
    "symbol": "string",
    "type": "string"
  },
  "date_time": "string",
  "deposit": true,
  "exp_time": 0,
  "message": "string",
  "network": "string",
  "tag": "string",
  "wallet_address": "string"
}
```

{% endtab %}

{% tab title="400: Bad Request Error message " %}

```json
{
  "message": "string"
}
```

{% endtab %}
{% endtabs %}

{% hint style="success" %}
If Target Asset is a FIAT currency, it means the subaccount is selling crypto. However, if it is a CRYPTO asset, it means the subaccount is purchasing crypto.
{% endhint %}

**Request Example:**

```json
curl -X 'POST' \
  'https://live.betaapp.com/v1/order/exchange' \
  -H 'accept: application/json' \
  -H 'X-sub-account-id: 22376b76-fe59-4f91-bce3-4cef3543083b' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InJlaEF1NURPY...ctfx2I4g' \
  -H 'Content-Type: application/json' \
  -d '{
  "network": "bitcoin",
  "pool_balance": true,
  "source_amount": 12000,
  "source_asset": "MXN",
  "target_amount": 0,
  "target_asset": "BTC"
}'
```

**Response Example:**

{% code overflow="wrap" %}

```json
{
  "asset": {
    "name": "Mexican Peso",
    "type": "",
    "small_image_url": "https://storage.googleapis.com/cryptoassets_images/20px/MXN-20.png",
    "medium_image_url": "https://storage.googleapis.com/cryptoassets_images/35px/MXN-35.png",
    "large_image_url": "https://storage.googleapis.com/cryptoassets_images/69px/MXN-69.png"
  },
  "amount": 0.017672,
  "network": "bitcoin",
  "exp_time": 1200,
  "deposit": false,
  "date_time": "2023-11-22T13:09:33.079445313Z"
}
```

{% endcode %}

**Here is an example of how the New Order Response could be displayed on the Front-End.**&#x20;

<figure><img src="/files/9MZfl38EC7Kmf26yWyTd" alt=""><figcaption><p>Wallet address displayed on the Checkout</p></figcaption></figure>

## Retrieve Order List

<mark style="color:blue;">`GET`</mark> `https://live.betaapp.com/v1/order`

This endpoint retrieves the Order List of a specific `subaccount_id`.

#### Query Parameters

| Name                                   | Type    | Description                                                        |
| -------------------------------------- | ------- | ------------------------------------------------------------------ |
| status                                 | String  | *Parameters: open, pending, confirmed, canceled.*                  |
| search                                 | String  | could be the e-mail or order description                           |
| order\_by                              | String  | Parameters: id, recipient\_email, description, created\_at, status |
| page<mark style="color:red;">\*</mark> | Integer | Page number for this query                                         |
| size<mark style="color:red;">\*</mark> | integer | Number of items per page for this query                            |

#### Headers

| Name                                            | Type   | Description            |
| ----------------------------------------------- | ------ | ---------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer {access\_token} |
| x-sub-account-id                                | String | Subaccount ID          |
| accept<mark style="color:red;">\*</mark>        | String | application/json       |

{% tabs %}
{% tab title="200: OK Sucess" %}

```json
{
  "message": "string",
  "orders": [
    {
      "account_id": "string",
      "created_at": "string",
      "description": "string",
      "id": "string",
      "recipient_email": "string",
      "status": "string",
      "target_amount": 0,
      "target_asset": "string",
      "valid_until": "string"
    }
  ]
}
```

{% endtab %}

{% tab title="400: Bad Request Error message " %}

```json
{
  "message": "string"
}
```

{% endtab %}
{% endtabs %}

**Request Example:**

{% code overflow="wrap" %}

```json
  curl -X 'GET' \
  'https://live.betaapp.com/v1/order?page=10&size=2' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InJlaEF1NURPY...ctfx2I4g'
```

{% endcode %}

**Response Example:**

```json
{
  "orders": [
    {
      "id": "dd299198-f1b4-4b82-8daa-9c16b1da7fb1",
      "account_id": "39b745ba...847f49",
      "sub_account_id": "94850a8c...881047",
      "recipient_email": "testing@betaapp.com",
      "description": "",
      "status": "confirmed",
      "source_asset": "XOF",
      "source_amount": 1000000,
      "target_asset": "BTC",
      "target_amount": 0.039094,
      "valid_until": "2023-11-14T14:56:43.615066Z",
      "created_at": "2023-11-13T14:56:43.615066Z"
    },
    {
      "id": "3e9bb519-58a4-454f-8474-c3ca4cf9c3d8",
      "account_id": "39b745ba...847f49",
      "sub_account_id": "94850a8c...881047",
      "recipient_email": "testing@betaapp.com",
      "description": "",
      "status": "confirmed",
      "source_asset": "XOF",
      "source_amount": 1000000,
      "target_asset": "BTC",
      "target_amount": 0.039193,
      "valid_until": "2023-11-14T14:47:08.137369Z",
      "created_at": "2023-11-13T14:47:08.137369Z"
    }
  ],
  "page": 10,
  "size": 2,
  "total_page": 12,
  "total_row": 23
}
```

## Retrieve Order Details

<mark style="color:blue;">`GET`</mark> `https://live.betaapp.com/v1/orders/details/{id}`

This endpoint provides the details of a specific payment.

#### Query Parameters

| Name                                 | Type   | Description |
| ------------------------------------ | ------ | ----------- |
| id<mark style="color:red;">\*</mark> | String | Order ID    |

#### Headers

| Name                                               | Type   | Description                |
| -------------------------------------------------- | ------ | -------------------------- |
| Authorization<mark style="color:red;">\*</mark>    | String | Bearer {access\_token}     |
| x-sub-account-id<mark style="color:red;">\*</mark> | String | Your user's subaccount\_id |
| accept<mark style="color:red;">\*</mark>           | String | application/json           |

{% tabs %}
{% tab title="200: OK Sucess" %}

```json
{
  "created_at": "string",
  "description": "string",
  "id": "string",
  "message": "string",
  "recipient_email": "string",
  "status": "string",
  "target_amount": 0,
  "target_asset": "string",
  "timelines": [
    {
      "comments": "string",
      "executed": true,
      "executed_at": "string",
      "order_step": "string"
    }
  ]
}
```

{% endtab %}

{% tab title="400: Bad Request Error message " %}

```json
{
  "message": "string"
}
```

{% endtab %}
{% endtabs %}

**Request Example:**

{% code overflow="wrap" %}

```json
curl -X 'GET' \
  'https://live.betaapp.com/v1/order/details/e6282263-f947-48c8-9c25-334696a4940e' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InJlaEF1NURPY...ctfx2I4g'
```

{% endcode %}

**Response Example:**

```json
{
  "id": "e6282263-f947-48c8-9c25-334696a4940e",
  "source_asset": "XRP",
  "source_amount": 64.76,
  "target_asset": "BRL",
  "target_amount": 200,
  "description": "Testing Order",
  "recipient_email": "testing@betaapp.com",
  "status": "canceled",
  "settlement_status": "",
  "created_at": "2023-11-13T15:14:46.847698Z",
  "timelines": [
    {
      "order_step": "Order Created",
      "executed": true,
      "comments": "",
      "executed_at": "2023-11-13T15:14:46.847698Z"
    },
    {
      "order_step": "Payment Link Opened",
      "executed": true,
      "comments": "",
      "executed_at": "2023-11-13T15:14:49.078719Z"
    },
    {
      "order_step": "Deposit Initiated",
      "executed": true,
      "comments": "",
      "executed_at": "2023-11-13T15:14:51.371398Z"
    },
    {
      "order_step": "Paid",
      "executed": false,
      "comments": "",
      "executed_at": "0001-01-01T00:00:00Z"
    },
    {
      "order_step": "Settlement",
      "executed": false,
      "comments": "",
      "executed_at": "0001-01-01T00:00:00Z"
    }
  ]
}
```