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

# API Integration

> Build your own crypto onramp experience by integrating directly with our REST API.

### Integration Flow:

1. Fetch available assets (fiat, crypto, and payment methods).
2. Use those to fetch real-time quotes. Include the destination wallet when requesting a Binance BUY quote.
3. Create a transaction using the selected provider. Supply `wallet_address` to lock the BUY destination with the providers listed below; Binance BUY transactions require it.
4. Redirect users to the checkout URL.
5. Handle asynchronous transaction updates through webhooks. Use the transaction retrieval endpoints for fallback reconciliation when needed.

> [!NOTE]
>
> Authenticate API requests with your partner API key in the `X-ORKI-API-KEY` header.

## Base URLs

| Environment | Base URL |
| - | - |
| Production | `https://api.money.orki.io` |
| Sandbox | `https://sandbox.money.orki.io` |

All endpoints in this guide use the `/api/v1/partner` base path. Use the same paths with the base URL for your intended environment.

> [!NOTE]
>
> Use an API key created in the sandbox Terminal with the sandbox base URL. Sandbox integrations use the provider's test environment where one is available, so lifecycle coverage varies by provider. Stripe supports a complete sandbox lifecycle, including checkout completion, provider status callbacks, Orki transaction updates, and outgoing partner webhook delivery without moving real funds. See [Sandbox testing](https://docs.money.orki.io/getting-started/sandbox.md) for the complete setup and test flow.

### End-to-end sandbox testing

Stripe supports the complete sandbox path from quote and checkout through transaction completion and outgoing webhook delivery. A known test route is:

| Field | Value |
| - | - |
| Fiat currency | `EUR` |
| Cryptocurrency | `USDC` |
| Network | `ethereum` |
| Payment method | `credit_debit_card` |
| Transaction type | `BUY` |

> [!WARNING]
>
> For an end-to-end sandbox test, explicitly create the transaction with `provider: "stripe"`, even when another returned quote has `is_best: true`. The `is_best` flag identifies the best-priced quote in that response; it does not indicate that the provider supports checkout completion and callbacks in its sandbox environment.

Other providers may support only part of the sandbox lifecycle, such as quote discovery or checkout-session creation. If a provider does not issue sandbox completion callbacks, its transaction cannot progress through the remaining webhook lifecycle in Orki sandbox.

## API request logs

Authenticated requests to `/api/v1/partner` endpoints are recorded in the API Logs view in the Terminal after the API key and account's Partner API access have been validated.

Each entry contains the request path, HTTP method, response status code, success or failure state, and timestamp. Request parameters, request bodies, response bodies, and API key values are not included in these log entries.

Logs are environment-specific: sandbox requests appear only in the sandbox account data, while production requests appear only in production. API logging does not change an endpoint's request or response structure.

## Destination wallets for BUY transactions

Set `wallet_address` when creating a `BUY` transaction to use your chosen destination wallet. For the following providers, Orki automatically locks that address so the buyer cannot change it during checkout:

| Provider | Provider ID |
| - | - |
| Transak | `transak` |
| Stripe | `stripe` |
| Unlimit | `unlimit` |
| Yellow Card | `yellowcard` |
| Fonbnk | `fonbnk` |
| TransFi | `transfi` |
| Alchemy Pay | `alchemypay` |

The same locking behavior applies in **sandbox and production**. No additional lock parameter or setting is required from your integration.

Include `wallet_address` in the `POST /api/v1/partner/transactions` request, even if you already supplied it when requesting quotes. A quote request alone does not set the destination for a later transaction.

Coinify and Wert are not included in this confirmed list. We will inform integrators in writing when their wallet locking has been verified and is ready to use.

For other providers, a supplied wallet may prefill checkout; the buyer may still need to enter or confirm it. For Binance BUY transactions, `wallet_address` remains required during both quote discovery and transaction creation.

Orki does not configure a partner-level destination wallet or custody the purchased crypto. The selected provider sends it directly to the destination for that transaction.

### Recipient address in transaction results

For new BUY transactions created with `wallet_address`, `recipient_address` remains populated on success. A nonblank destination reported by the provider takes precedence. If the provider omits the address or returns it as `null`, empty, or whitespace, Orki preserves the wallet submitted for that transaction.

This applies to transaction retrieval and outgoing webhooks in both environments. Transactions created without a wallet, including older records that did not save one, may still have a `null` recipient address when the provider omits it.

Creating an Orki transaction only creates a tracking record and checkout link. No purchase or crypto delivery occurs until the buyer completes the provider's payment and KYC flow.

***

## 1. Get Supported Crypto Currencies

**Endpoint:** `GET /api/v1/partner/crypto-currencies`

**Description:** Returns the cryptocurrencies and networks supported for the requested transaction type.

Pass `type=BUY` for assets available to purchase or `type=SELL` for assets available to sell. If omitted, `type` defaults to `BUY`. Quote discovery remains the authoritative check for a complete route because availability can also depend on fiat currency, payment method, amount, location, and provider status.

**Example Request:**

```bash theme={null}
curl -X GET "https://api.money.orki.io/api/v1/partner/crypto-currencies?type=BUY" \
  -H "X-ORKI-API-KEY: YOUR_API_KEY"
```

**Response Example:**

```json theme={null}
{
  "msg": "Success",
  "data": [
    {
        "code": "eth",
        "network": "ethereum",
        "name": "Ethereum",
        "crypto_icon": "https://asset-url.com"
    },
    {
        "code": "btc",
        "network": "mainnet",
        "name": "Bitcoin",
        "crypto_icon": "https://asset-url.com"
    }
  ],
  "success": true,
  "code": 200
}
```

***

## 2. Get Supported Fiat Currencies

**Endpoint:** `GET /api/v1/partner/fiat-currencies`

**Description:** Lists our supported fiat currencies for transactions.

Each currency includes Orki's broad supported range for the selected transaction type. `min_amount` is the minimum supported amount and `max_amount` is the maximum. The `providers` object contains the available amount bounds for each provider.

Orki rejects amounts outside the aggregate range before requesting provider quotes. A payment method, asset, network, customer location, or selected provider can impose a narrower range, so quote discovery remains authoritative for the complete route.

**Optional Query Parameters:**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `type` | string | `BUY` | Transaction type: `BUY` or `SELL`. The returned currencies are filtered for the selected direction. |

**Example Request:**

```bash theme={null}
curl -X GET "https://api.money.orki.io/api/v1/partner/fiat-currencies?type=BUY" \
  -H "X-ORKI-API-KEY: YOUR_API_KEY"
```

**Response Example:**

```json theme={null}
{
  "msg": "Success",
  "data": [
     {
        "code": "EUR",
        "name": "Euro",
        "logo_symbol": "EU",
        "fiat_icon": "<svg>…</svg>",
        "min_amount": 1,
        "max_amount": 30000,
        "providers": {
          "example_provider": {
            "min_amount": 1,
            "max_amount": 30000
          }
        }
    }
  ],
  "success": true,
  "code": 200
}
```

***

## 3. Get Payment Methods

**Endpoint:** `GET /api/v1/partner/payment-methods`

**Description:** Returns all supported payment methods for buying or selling crypto.

**Required Query Parameters:**

| Parameter | Type | Example | Description |
| - | - | - | - |
| `fiat` | string | `"USD"` | Fiat currency used to determine available payment methods. |
| `type` | string | `"BUY"` | Transaction type: `BUY` or `SELL`. |

**Response Example:**

```json theme={null}
{
  "msg": "Success",
  "data": {
    "payment_methods": [
      {
          "orki_id": "sepa_bank_transfer",
          "logo": "https://d31sk3i6y53c7h.cloudfront.net/assets/payment-methods/sepa_instant.svg",
          "name": "SEPA Bank Transfer",
          "tagline": "European Bank Transfers"
      },
      {
          "orki_id": "credit_debit_card",
          "logo": "https://d31sk3i6y53c7h.cloudfront.net/assets/payment-methods/card.svg",
          "name": "Card Payment",
          "tagline": "Visa, MasterCard, etc."
      }
    ],
    "recommended": "credit_debit_card"
  },
  "success": true,
  "code": 200
}
```

***

## 4. Get Quotes

**Endpoint:** `GET /api/v1/partner/quotes`

**Description:** Fetches exchange rate quotes from all supported providers.

Amounts below the fiat currency's `min_amount` or above its `max_amount` are rejected before quote discovery. Requests within those broad bounds can still be unavailable when the selected payment method, asset, network, location, or provider has a stricter limit.

**Required Query Parameters:**

| Parameter | Type | Example | Description |
| - | - | - | - |
| `fiat_currency` | string | `"USD"` | The fiat currency to use. |
| `crypto_currency` | string | `"BTC"` | The crypto currency to buy/sell. |
| `payment_method` | string | `"credit_debit_card"` | Chosen payment method. |
| `network` | string | `"mainnet"` | Blockchain network for crypto. |
| `amount` | number | `900` | Fiat amount for the transaction. |
| `type` | string | `"BUY"` | Transaction type — `BUY` or `SELL`. |

**Optional Query Parameters:**

| Parameter | Type | Example | Description |
| - | - | - | - |
| `wallet_address` | string | `"YOUR_BTC_WALLET_ADDRESS"` | Destination wallet for a BUY transaction. Required for Binance BUY quote eligibility; optional for other providers. Supply it again when creating the transaction to apply wallet locking. |

**Example Request:**

```bash theme={null}
curl -X GET "https://api.money.orki.io/api/v1/partner/quotes?fiat_currency=USD&crypto_currency=BTC&payment_method=credit_debit_card&network=mainnet&amount=900&type=BUY&wallet_address=YOUR_BTC_WALLET_ADDRESS" \
  -H "X-ORKI-API-KEY: YOUR_API_KEY"
```

**Example Response:**

```json theme={null}
{
  "msg": "Success",
  "data": [
    {
      "provider": {
        "name": "Moon Pay",
        "identifier": "moonpay",
        "icon": "https://.../moonpay.svg"
      },
      "exchange_rate": 2256201.94,
      "is_best": true,
      "crypto_amount": 0.0004,
      "fiat_amount": 900,
      "quote_amount": 0.0004,
      "percentage_diff": 0
    },
    {
      "provider": {
        "name": "Transak",
        "identifier": "transak",
        "icon": "https://.../transak.svg"
      },
      "exchange_rate": 2124319.04,
      "is_best": false,
      "crypto_amount": 0.00038746,
      "fiat_amount": 900,
      "quote_amount": 0.00038746,
      "percentage_diff": 3.14
    }
  ],
  "success": true,
  "code": 200
}
```

***

## 5. Create Transaction

**Endpoint:** `POST /api/v1/partner/transactions`

**Description:** Creates a new transaction and returns a checkout URL for the user to complete payment.

**JSON Body:**

| Parameter | Type | Required | Example | Description |
| - | - | - | - | - |
| `fiat_currency` | string | Yes | `"USD"` | Fiat currency code. |
| `crypto_currency` | string | Yes | `"BTC"` | Crypto currency code. |
| `payment_method` | string | Yes | `"credit_debit_card"` | Payment method identifier. |
| `network` | string | Yes | `"mainnet"` | Crypto network. |
| `amount` | number | Yes | `900` | Fiat amount. |
| `type` | string | Yes | `"BUY"` | Transaction type (`BUY` or `SELL`). |
| `provider` | string | Yes | `"guardarian"` | Provider selected from the quote response. |
| `wallet_address` | string | Binance BUY only | `"YOUR_BTC_WALLET_ADDRESS"` | Per-transaction destination wallet. Automatically locked for the seven providers listed in [Destination wallets for BUY transactions](#destination-wallets-for-buy-transactions). Optional for other providers. |
| `partner_context` | string | No | `"abcd"` | Your reconciliation identifier, returned in transaction webhooks. |
| `redirect_url` | string | No | `"https://website.com/success"` | URL used after the provider checkout. |

**Example Request:**

```bash theme={null}
curl -X POST "https://api.money.orki.io/api/v1/partner/transactions" \
  -H "X-ORKI-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fiat_currency": "USD",
    "crypto_currency": "BTC",
    "payment_method": "credit_debit_card",
    "network": "mainnet",
    "amount": 900,
    "type": "BUY",
    "provider": "guardarian",
    "wallet_address": "YOUR_BTC_WALLET_ADDRESS",
    "partner_context": "abcd",
    "redirect_url": "https://website.com/success"
  }'
```

**Example Response:**

```json theme={null}
{
  "msg": "Success",
  "data": {
    "transaction_id": "01k8qrw1j0f2mvd99x33ep160s",
    "provider": {
      "name": "Guardarian",
      "identifier": "guardarian",
      "icon": "https://d31sk3i6y53c7h.cloudfront.net/assets/providers/guardarian.svg"
    },
    "exchange_rate": 93023.26,
    "is_best": true,
    "fiat_amount": 350,
    "crypto_amount": 0.0037606,
    "quote_amount": 0.0037606,
    "link": "https://provider.example/checkout"
  },
  "success": true,
  "code": 200
}
```

***

## 6. Handle Webhooks

**Description:** Receive updates for transaction status changes.

**Sample Payload:**

```json theme={null}
{
  "meta": {
    "version": "1.0",
    "server_time": 1735303290,
    "event": "transaction.success"
  },
  "data": {
    "id": "12345",
    "provider_transaction_id": "abc-789",
    "partner_context": "abcd",
    "type": "BUY",
    "sender_address": null,
    "recipient_address": "0x456...",
    "exchange_rate": "1.05",
    "transaction_hash": "0xdeadbeef...",
    "provider_fee": "2.50",
    "provider_fee_currency": "USD",
    "client_fee": "0.25",
    "client_fee_currency": "USD",
    "orki_fee": "0.50",
    "orki_fee_currency": "USD",
    "network_fee": "0.20",
    "network_fee_currency": "USD",
    "fiat_amount": "100.00",
    "crypto_amount": "0.0023",
    "fiat_currency": "USD",
    "crypto_currency": "ETH",
    "network": "ETHEREUM",
    "payment_method": "credit_debit_card",
    "status": "success",
    "provider": "stripe",
    "created_at": "2025-08-26T10:00:00Z"
  }
}
```

Each fee amount has a companion currency field. `client_fee` is the partner fee and `orki_fee` is Orki's platform fee; both are denominated in USD. Provider and network fee denominations vary by provider and route, so use the corresponding currency field rather than inferring a fee denomination from the transaction currencies.

`fiat_amount` is the provider-reported base fiat transaction amount before separately itemized fees. Fees are not subtracted from this field. For example, a `100.00 EUR` transaction with a `2.50 EUR` provider fee returns `fiat_amount: "100.00"` and `provider_fee: "2.50"`.

REST transaction responses and webhook payloads use `provider_transaction_id` for the provider's transaction identifier.

`recipient_address` is always included in webhook data. For a new BUY transaction created with `wallet_address`, it contains the nonblank provider-reported destination, or preserves the submitted wallet when the provider omits it or returns it blank. It is `null` when no blockchain recipient applies, such as a fiat payout, or when neither the provider nor the transaction supplies an address.

**Events:**

* `transaction.success`
* `transaction.failed`

***

✅ **When to Use**

* You want full control of UX and transaction logic.
* You’re integrating crypto buy/sell within your product flow.
* You need flexibility in pricing, routing, or KYC handling.

***

🚀 **Next Steps**

* Obtain your API key from the Partner Dashboard.
* Review the [OpenAPI Reference](https://docs.money.orki.io/api-reference/assets/crypto.md) for detailed request/response models.
* Review [Errors](https://docs.money.orki.io/api-reference/errors.md) and [Rate limits](https://docs.money.orki.io/api-reference/rate-limits.md) before implementing retries.
* Set up [Webhooks](https://docs.money.orki.io/webhooks/webhooks.md) to monitor transaction lifecycle.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.