# 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"
    }
  ]
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.betaramps.com/documentation-beta-ramps/exchange-crypto-to-fiat/buy-sell-orders.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.