---
title: "Get order"
description: "Retrieves a single order by its `order_id`."
protocol: rest
method: GET
endpoint: "/v1/fx/orders/{order_id}"
baseUrl: "https://api.gravv.xyz"
group: "Fx"
auth:
  label: "Api-Key"
  name: "Api-Key"
  in: header
---

# Get order

<Endpoint method="GET" path="/v1/fx/orders/{order_id}" />

Retrieves a single order by its `order_id`.

## Path Parameters

<ParamField name="order_id" path="order_id" type="string" required>
  The order reference returned when the order was created.
</ParamField>

## Responses

| Status | Description |
| --- | --- |
| `200` | Order details |
| `400` | Order not found |
| `401` | Missing or invalid API key |
| `500` | Internal server error |

### 200 response

<ResponseField name="data" type="object">

  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Internal UUID of the order.
    </ResponseField>

    <ResponseField name="order_id" type="string">
      Human-readable order reference. Use this value as the `order_id` path parameter in the order endpoints.
    </ResponseField>

    <ResponseField name="order_type" type="string">

      Possible values: `market`, `limit`
    </ResponseField>

    <ResponseField name="side" type="string">

      Possible values: `buy`, `sell`
    </ResponseField>

    <ResponseField name="pair" type="object">

      <Expandable title="properties">
        <ResponseField name="base" type="string" required>
          Base currency code (ISO 4217 or crypto ticker).
        </ResponseField>

        <ResponseField name="quote" type="string" required>
          Quote currency code (ISO 4217 or crypto ticker).
        </ResponseField>

      </Expandable>
    </ResponseField>

    <ResponseField name="amount" type="string">
      Amount of the base currency to exchange.
    </ResponseField>

    <ResponseField name="amount_currency" type="string">
    </ResponseField>

    <ResponseField name="converted_amount" type="string">
      Proceeds in the quote currency.
    </ResponseField>

    <ResponseField name="converted_currency" type="string">
    </ResponseField>

    <ResponseField name="rate" type="string">
      Rate applied to the order.
    </ResponseField>

    <ResponseField name="target_rate" type="string,null">
      Target rate for `limit` orders. Returns `null` for market orders.
    </ResponseField>

    <ResponseField name="fee" type="string,null">
      Fee charged for the order, if any.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current order status: * `waiting_approval`: created and waiting for a second user to approve or reject * `pending`: approved; the funds are charged and the order is executing * `rejected`: a reviewer rejected the order * `cancelled`: cancelled before execution * `expired`: not approved before it expired
    </ResponseField>

    <ResponseField name="customer_id" type="string">
      ID of the customer the order was created for.
    </ResponseField>

    <ResponseField name="tenant_id" type="string">
      ID of the tenant that owns the order.
    </ResponseField>

    <ResponseField name="source_type" type="string,null">
      Where the funds come from (`account` or `wallet`).
    </ResponseField>

    <ResponseField name="source_id" type="string,null">
      ID of the source account or wallet.
    </ResponseField>

    <ResponseField name="destination_type" type="string,null">
      Where the proceeds settle (`account`, `wallet`, or `ssi`).
    </ResponseField>

    <ResponseField name="destination_id" type="string,null">
      ID of the destination account, wallet, or settlement instruction.
    </ResponseField>

    <ResponseField name="created_by_user_id" type="string">
      ID of the user who created the order.
    </ResponseField>

    <ResponseField name="created_by_role" type="string">
      Role of the user who created the order.
    </ResponseField>

    <ResponseField name="approved_by_user_id" type="string,null">
      ID of the user who approved the order. `null` until approved.
    </ResponseField>

    <ResponseField name="approved_at" type="string,null">
      When the order was approved. `null` until approved.
    </ResponseField>

    <ResponseField name="rejected_by_user_id" type="string,null">
      ID of the user who rejected the order. `null` unless rejected.
    </ResponseField>

    <ResponseField name="rejected_at" type="string,null">
      When the order was rejected. `null` unless rejected.
    </ResponseField>

    <ResponseField name="rejection_reason" type="string,null">
      Reason given when the order was rejected. `null` unless rejected.
    </ResponseField>

    <ResponseField name="executed_at" type="string,null">
      When the order executed. `null` until executed.
    </ResponseField>

    <ResponseField name="settled_at" type="string,null">
      When the proceeds settled. `null` until settled.
    </ResponseField>

    <ResponseField name="expires_at" type="string,null">
      When the order expires if it isn't approved. `null` when the order doesn't expire.
    </ResponseField>

    <ResponseField name="created_at" type="string">
    </ResponseField>

    <ResponseField name="updated_at" type="string,null">
      When the order was last updated. `null` if never updated.
    </ResponseField>

  </Expandable>
</ResponseField>

<ResponseField name="error" type="string,null">
</ResponseField>

<ResponseExample>

```json title="Response"
{
  "data": {
    "id": "4994339f-4a19-47ef-a86b-1005eff0a4d0",
    "order_id": "OTC-0VA89I",
    "order_type": "market",
    "side": "sell",
    "pair": {
      "base": "USD",
      "quote": "ZAR"
    },
    "amount": "1000.00000000",
    "amount_currency": "USD",
    "converted_amount": "16242.50000000",
    "converted_currency": "ZAR",
    "rate": "16.24250000",
    "target_rate": null,
    "fee": null,
    "status": "waiting_approval",
    "customer_id": "85034797-3ea1-4ad8-a952-becd67d74acc",
    "tenant_id": "dfa96ede-fc13-43cf-8328-8b910d1cd1d2",
    "source_type": "account",
    "source_id": "74653c7b-ae84-45ab-8085-2d2493f86d81",
    "destination_type": "ssi",
    "destination_id": "b23ffd0e-d0fc-432e-acc9-c396194121b3",
    "created_by_user_id": "804201c6-2760-4da1-9c5e-0ff09ebc3b5e",
    "created_by_role": "developer",
    "approved_by_user_id": null,
    "approved_at": null,
    "rejected_by_user_id": null,
    "rejected_at": null,
    "rejection_reason": null,
    "executed_at": null,
    "settled_at": null,
    "expires_at": null,
    "created_at": "2026-07-03T15:32:37.878676Z",
    "updated_at": null
  },
  "error": null
}
```

</ResponseExample>

### 400 response

<ResponseField name="data" type="null">
  Always null for error responses.
</ResponseField>

<ResponseField name="error" type="string">
  Human-readable error message.
</ResponseField>

<ResponseExample>

```json title="OrderNotFound"
{
  "data": null,
  "error": "order not found"
}
```

</ResponseExample>

### 401 response

<ResponseField name="data" type="null">
  Always null for error responses.
</ResponseField>

<ResponseField name="error" type="string">
  Human-readable error message.
</ResponseField>

<ResponseExample>

```json title="MissingApiKey"
{
  "data": null,
  "error": "Invalid or missing Api-Key header. Api-Key is required!"
}
```

```json title="InvalidApiKey"
{
  "data": null,
  "error": "Invalid token!"
}
```

</ResponseExample>

### 500 response

<ResponseField name="data" type="null">
  Always null for error responses.
</ResponseField>

<ResponseField name="error" type="string">
  Human-readable error message.
</ResponseField>

<ResponseExample>

```json title="Response"
{
  "data": null,
  "error": "Internal server error"
}
```

</ResponseExample>

## Authorization

- **ApiKeyAuth**