API Integration

Integration Flow:

Fetch available assets (fiat, crypto, and payment methods).
Use those to fetch real-time quotes. Include the destination wallet when requesting a Binance BUY quote.
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.
Redirect users to the checkout URL.
Handle asynchronous transaction updates through webhooks. Use the transaction retrieval endpoints for fallback reconciliation when needed.

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.

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 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`

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:

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:

{
  "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:

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:

{
  "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:

{
  "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:

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:

{
  "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. 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:

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:

{
  "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:

{
  "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 for detailed request/response models.
Review Errors and Rate limits before implementing retries.
Set up Webhooks to monitor transaction lifecycle.

Getting started

Authentication

Integration Guide

Widget Integration

Ramp Providers

Supported Assets

Webhooks

API Integration

Integration Flow:

Base URLs

End-to-end sandbox testing

API request logs

Destination wallets for BUY transactions

Recipient address in transaction results

1. Get Supported Crypto Currencies

2. Get Supported Fiat Currencies

3. Get Payment Methods

4. Get Quotes

5. Create Transaction

6. Handle Webhooks

​Integration Flow:

​Base URLs

​End-to-end sandbox testing

​API request logs

​Destination wallets for BUY transactions

​Recipient address in transaction results

​1. Get Supported Crypto Currencies

​2. Get Supported Fiat Currencies

​3. Get Payment Methods

​4. Get Quotes

​5. Create Transaction

​6. Handle Webhooks

Integration Flow:

Base URLs

End-to-end sandbox testing

API request logs

Destination wallets for BUY transactions

Recipient address in transaction results

1. Get Supported Crypto Currencies

2. Get Supported Fiat Currencies

3. Get Payment Methods

4. Get Quotes

5. Create Transaction

6. Handle Webhooks