> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ramphub.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Buy order

> Create a routed buy order.

Create buy orders with `POST /api/developer/orders`.

> **How to read this page**\
> This is the point where a quote becomes a real transaction. Keep the quote response nearby while you create the order.

When you create a buy order, RampHub also creates the matching order intent automatically. If you need to show the active payment window or let support extend it, see [Order intent](order-intent).

If the same customer, token, and network already has an active order window, RampHub returns a structured `PAYCHAIN_ACTIVE_INTENT_CONFLICT` response. Your app can use the [Order intent](order-intent) endpoint to show the current window first, or resend the order with `overrideActiveIntent: true` if the customer wants to replace it.

## Request body

### Required on every order

* `side`
* `amount`
* `fiatCurrency`
* `asset`
* `chain`

### Buy orders

For buys, `amount` is the crypto amount and `fiatAmount` is required. You also need a destination wallet address.

Required:

* `fiatAmount`
* `walletAddress`

Optional but useful:

* `email`
* `externalCustomerId`
* `developerFeePercent`
* `overrideActiveIntent`

```bash theme={null}
curl -X POST "https://api.ramphub.io/api/developer/orders" \
  -H "x-api-key: rh_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "side": "buy",
    "amount": 3,
    "fiatAmount": 15000,
    "fiatCurrency": "NGN",
    "asset": "USDT",
    "chain": "base",
    "walletAddress": "0xRecipientWalletAddress",
    "email": "user@example.com",
    "externalCustomerId": "cust_7f3b8a2d",
    "developerFeePercent": 2.5
  }'
```

## Business fees

RampHub lets businesses attach a developer fee percent to the same order request.

RampHub accrues the fee internally, so you only need the percentage:

```bash theme={null}
curl -X POST "https://api.ramphub.io/api/developer/orders" \
  -H "x-api-key: rh_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "side": "buy",
    "amount": 3,
    "fiatAmount": 15000,
    "fiatCurrency": "NGN",
    "asset": "USDT",
    "chain": "base",
    "walletAddress": "0xRecipientWalletAddress",
    "developerFeePercent": 0.5
  }'
```

Rules:

* `developerFeePercent` can be `0` or a small percentage like `0.5`.
* `overrideActiveIntent` can be set to `true` when the customer wants to replace an existing active order window.

## Response shape

The response includes the tracked RampHub transaction id, the selected provider, and the next-step details you need to show the user.

Common fields:

* `transactionId`
* `requestReference`
* `side`
* `asset`
* `chain`
* `selectedProvider`
* `bestRateUsed`
* `providerDetails`
* `ourCryptoAddress`
* `environment`
* `sandbox`
* `trackable`

```json theme={null}
{
  "transactionId": "0d4b7fb0-66f7-4a52-9183-7c3fe44f0db2",
  "requestReference": "RH-TX-AB12CD34",
  "side": "buy",
  "asset": "USDT",
  "chain": "base",
  "selectedProvider": "UseBread",
  "bestRateUsed": 1397.17,
  "providerDetails": {
    "status": "AWAITING_DEPOSIT"
  },
  "ourCryptoAddress": null,
  "environment": "live",
  "sandbox": false,
  "trackable": true
}
```

## Rules

* Save `transactionId` right away.
* Use `providerDetails` for the next step.
* Use `ourCryptoAddress` when it is present.