# Create Deposit Address
Source: https://developer.obiex.finance/api-reference/addresses/create-deposit-address

/api-reference/openapi.json post /addresses/broker



# Get Deposit Addresses
Source: https://developer.obiex.finance/api-reference/addresses/get-deposit-addresses

/api-reference/openapi.json get /addresses/me/broker



# Authentication
Source: https://developer.obiex.finance/api-reference/authentication

Learn how to authenticate your API requests

Most API calls on Obiex are authenticated. API requests made without authorization will fail with status code `401: Unauthorized`.

## Getting Your API Credentials

1. Create an [Obiex Staging account](https://staging.app.obiex.finance/auth/signup)
2. Log in to your [Obiex Staging dashboard](https://staging.app.obiex.finance/auth/login)
3. Navigate to **Settings** > **Developers** > **API Keys**
4. Click **Create API Keys** to generate your keys

### Your Keys

| Key            | Description                                           |
| -------------- | ----------------------------------------------------- |
| **API Key**    | Used in request headers to authenticate your requests |
| **Secret Key** | Used to sign your requests; never expose publicly     |

<Warning>
  If you think your keys may have been compromised, immediately generate new ones from your dashboard: **Settings** > **API Keys** > **Generate new keys**
</Warning>

## Authorizing API Calls

To authorize API calls, include these headers:

| Header            | Description                             |
| ----------------- | --------------------------------------- |
| `X-API-KEY`       | Your API key                            |
| `X-API-TIMESTAMP` | Number of milliseconds since Unix epoch |
| `X-API-SIGNATURE` | SHA256 HMAC signature of the request    |

### Signature Generation

The signature is generated by creating an HMAC SHA256 of the following concatenated string:

```
{http_method}{request_path}{request_timestamp}
```

<Note>
  The `request_path` must include the full path including `/v1`. For example: `/v1/addresses/me/broker`
</Note>

**Example in Node.js:**

```typescript theme={null}
import { createHmac } from 'crypto';

function signRequest(method: string, url: string, apiSecret: string) {
  const timestamp = Date.now();
  const path = url.startsWith('/') ? url : `/${url}`;
  const content = `${method.toUpperCase()}${path}${timestamp}`;
  
  const signature = createHmac('sha256', apiSecret)
    .update(content)
    .digest('hex');
    
  return { timestamp, signature };
}
```

### Complete Example

```typescript theme={null}
import axios from 'axios';
import { createHmac } from 'crypto';

const apiKey = 'YOUR_API_KEY';
const apiSecret = 'YOUR_SECRET_KEY';

const client = axios.create({
  baseURL: 'https://staging.api.obiex.finance',
});

client.interceptors.request.use((config) => {
  const timestamp = Date.now();
  const path = config.url || '';
  const content = `${config.method?.toUpperCase()}${path}${timestamp}`;
  
  const signature = createHmac('sha256', apiSecret)
    .update(content)
    .digest('hex');
    
  config.headers['X-API-KEY'] = apiKey;
  config.headers['X-API-TIMESTAMP'] = timestamp.toString();
  config.headers['X-API-SIGNATURE'] = signature;
  
  return config;
});

// Make authenticated request
const response = await client.get('/v1/addresses/me/broker');
```

## Security Best Practices

* **Never** commit your API keys to Git
* **Never** expose keys in client-side JavaScript
* Store keys as environment variables
* Rotate keys immediately if compromised


# Get Active Networks
Source: https://developer.obiex.finance/api-reference/currencies/get-active-networks

/api-reference/openapi.json get /currencies/networks/active



# Get Tradable Currencies
Source: https://developer.obiex.finance/api-reference/currencies/get-tradable-currencies

/api-reference/openapi.json get /currencies/tradeable



# Get Withdrawal Currency Networks
Source: https://developer.obiex.finance/api-reference/currencies/get-withdrawal-currency-networks

/api-reference/openapi.json get /currencies/{id}/networks



# Errors
Source: https://developer.obiex.finance/api-reference/errors

Understanding API error responses

When an API request fails, Obiex returns a standard error response with relevant information about what went wrong.

## Error Response Format

```json theme={null}
{
  "message": "Error description",
  "errors": [
    {
      "message": "Account has been disabled. Try again in 15 minutes"
    }
  ]
}
```

## Common Error Codes

| Code                  | HTTP Status | Description                       |
| --------------------- | ----------- | --------------------------------- |
| UNAUTHORIZED          | 401         | Invalid or missing authentication |
| FORBIDDEN             | 403         | Insufficient permissions          |
| NOT\_FOUND            | 404         | Resource not found                |
| VALIDATION\_ERROR     | 422         | Invalid request parameters        |
| RATE\_LIMIT\_EXCEEDED | 429         | Too many requests                 |
| INTERNAL\_ERROR       | 500         | Server error                      |

## HTTP Status Codes

| Status | Meaning               |
| ------ | --------------------- |
| 200    | Success               |
| 201    | Created               |
| 400    | Bad Request           |
| 401    | Unauthorized          |
| 403    | Forbidden             |
| 404    | Not Found             |
| 422    | Validation Error      |
| 429    | Too Many Requests     |
| 500    | Internal Server Error |

## Handling Errors

```javascript theme={null}
try {
  const response = await fetch('https://api.obiex.finance/addresses/me/broker', {
    headers: {
      'Authorization': 'YOUR_API_KEY'
    }
  });
  
  if (!response.ok) {
    const error = await response.json();
    console.error('API Error:', error.message);
    return;
  }
  
  const data = await response.json();
} catch (err) {
  console.error('Network error:', err);
}
```


# Introduction
Source: https://developer.obiex.finance/api-reference/introduction

Welcome to the Obiex API Documentation

Welcome to the Obiex API Documentation, your guide to building amazing payment experiences with our powerful APIs.

Start by reviewing the overview of each section to understand how the APIs function and interact. This will help you get the most out of our platform and easily integrate its features into your applications.

<Tip>
  Building in Node.js or TypeScript? The [official SDK](/sdks/node) wraps these endpoints in a typed client and handles request signing for you.
</Tip>

## Base URLs

Obiex provides two environments for your integration:

| Environment | Base URL                                |
| ----------- | --------------------------------------- |
| Staging     | `https://staging.api.obiex.finance/v1/` |
| Production  | `https://api.obiex.finance/v1/`         |

## Environments

### Staging

No real crypto is involved. We'll still send webhooks and email notifications, and most of the APIs function the same. We recommend that you do all your testing in this mode.

To create a staging account, use: [https://staging.app.obiex.finance/auth/signup](https://staging.app.obiex.finance/auth/signup)

### Production

Real crypto, real transactions, real effects. Only switch to this after you've tested your integration thoroughly.

To create a live account, use: [https://obiex.finance](https://obiex.finance)

## Rate Limits

All API requests are subject to rate limiting. The current limit is **200 requests per minute** per API key.

Rate limit headers are included in every response:

* `x-ratelimit-limit`: Maximum requests per minute
* `x-ratelimit-remaining`: Remaining requests in current window
* `x-ratelimit-reset`: Unix timestamp when the rate limit resets

### Endpoint-specific limits

Some endpoints have stricter limits than the default:

| Endpoint                            | Limit                 |
| ----------------------------------- | --------------------- |
| `POST /trades/quote` (Create Quote) | 100 requests per hour |


# Create invoice
Source: https://developer.obiex.finance/api-reference/invoice-settlement/create-invoice

/api-reference/openapi.json post /invoices
Create an invoice for USD settlement. Requires a `fundingSource` of either `DEPOSIT` or `WALLET`.

- **DEPOSIT** (NGNX only): Returns a virtual NGN bank account to pay into, along with the exact NGN amount. The virtual account is valid for 30 minutes. Invoice status starts as `PENDING`.
- **WALLET** (NGNX, USDC, USDT): Debits the required amount from your wallet immediately. No virtual account is created. Invoice status is set to `APPROVED` instantly.



# Get invoice
Source: https://developer.obiex.finance/api-reference/invoice-settlement/get-invoice

/api-reference/openapi.json get /invoices/{invoiceId}
Retrieve a single invoice by its ID.



# List my invoices
Source: https://developer.obiex.finance/api-reference/invoice-settlement/list-my-invoices

/api-reference/openapi.json get /invoices/me
Returns a paginated list of invoices.



# Upload invoice document
Source: https://developer.obiex.finance/api-reference/invoice-settlement/upload-invoice-document

/api-reference/openapi.json post /uploads/invoices
Upload an invoice document (image or PDF, max 1 MB). Returns a URL to include in the Create Invoice request.



# Get Banks for GHS Withdrawal
Source: https://developer.obiex.finance/api-reference/payouts/get-banks-for-ghs-withdrawal

/api-reference/openapi.json get /ghs-payments/banks



# Get Banks for Naira Withdrawal
Source: https://developer.obiex.finance/api-reference/payouts/get-banks-for-naira-withdrawal

/api-reference/openapi.json get /ngn-payments/banks



# Get Mobile Networks for GHS Withdrawal
Source: https://developer.obiex.finance/api-reference/payouts/get-mobile-networks-for-ghs-withdrawal

/api-reference/openapi.json get /ghs-payments/mobile/networks



# Get Wallet Balance
Source: https://developer.obiex.finance/api-reference/payouts/get-wallet-balance

/api-reference/openapi.json get /wallets/USDT



# Request Bank Account Withdrawal
Source: https://developer.obiex.finance/api-reference/payouts/request-bank-account-withdrawal

/api-reference/openapi.json post /wallets/ext/debit/fiat



# Request Crypto Withdrawal
Source: https://developer.obiex.finance/api-reference/payouts/request-crypto-withdrawal

/api-reference/openapi.json post /wallets/ext/debit/crypto



# Resolve GHS Bank Account
Source: https://developer.obiex.finance/api-reference/payouts/resolve-ghs-bank-account

/api-reference/openapi.json get /ghs-payments/accounts/resolve



# Resolve Naira Bank Account
Source: https://developer.obiex.finance/api-reference/payouts/resolve-naira-bank-account

/api-reference/openapi.json get /ngn-payments/accounts/resolve



# Accept Quote
Source: https://developer.obiex.finance/api-reference/trades/accept-quote

/api-reference/openapi.json post /trades/quote/{quoteId}



# Create Quote
Source: https://developer.obiex.finance/api-reference/trades/create-quote

/api-reference/openapi.json post /trades/quote
Creates a quote for a trade you intend to execute. Do not use this endpoint to check prices or tickers. Limited to 100 requests per hour per API key.



# Get Pairs
Source: https://developer.obiex.finance/api-reference/trades/get-pairs

/api-reference/openapi.json get /trades/pairs



# Get Single Trade Pair
Source: https://developer.obiex.finance/api-reference/trades/get-single-trade-pair

/api-reference/openapi.json get /trades/pairs/{sourceCode}/{targetCode}



# Get User Trades Summary
Source: https://developer.obiex.finance/api-reference/trades/get-user-trades-summary

/api-reference/openapi.json get /trades/summary/me



# Instant Swap
Source: https://developer.obiex.finance/api-reference/trades/instant-swap

/api-reference/openapi.json post /trades/swap
Create a quote and execute the trade in a single request — no need to call `Create Quote` then `Accept Quote` separately. The swap is executed at the best available rate at the time of the request. Provide either `amount` (the amount you are selling) or `amountToReceive` (the amount you want to receive), but not both.



# Get Deposit Transactions
Source: https://developer.obiex.finance/api-reference/transactions/get-deposit-transactions

/api-reference/openapi.json get /transactions/deposits/me



# Get Payout Transactions
Source: https://developer.obiex.finance/api-reference/transactions/get-payout-transactions

/api-reference/openapi.json get /transactions/withdrawals/me



# Get Transaction By Id
Source: https://developer.obiex.finance/api-reference/transactions/get-transaction-by-id

/api-reference/openapi.json get /transactions/{transactionId}



# Get User Transactions
Source: https://developer.obiex.finance/api-reference/transactions/get-user-transactions

/api-reference/openapi.json get /transactions/me



# Resend Webhook(single transaction)
Source: https://developer.obiex.finance/api-reference/transactions/resend-webhooksingle-transaction

/api-reference/openapi.json post /transactions/{id}/resendWebhook



# Resend Webhooks(multiple transactions)
Source: https://developer.obiex.finance/api-reference/transactions/resend-webhooksmultiple-transactions

/api-reference/openapi.json post /transactions/resendWebhooks



# Webhooks
Source: https://developer.obiex.finance/api-reference/webhooks

Listen to real-time events and verify webhook requests from Obiex

Webhooks allow you to listen to real-time events on your Obiex account. When an event occurs (e.g., a withdrawal is successful or pending), Obiex sends a POST request with a JSON payload to your server.
It also includes a security header so you can verify the request came from Obiex.

## Setting Up Webhooks

1. Log in to your [Obiex dashboard](https://staging.app.obiex.finance/auth/login)
2. Navigate to **Settings** > **Developers** > **Webhook Url**
3. Add your webhook endpoint URL
4. Copy your **Signature Secret**

## Event Payload and Structure

Obiex webhook events contain a JSON payload with the details of the event. We send webhooks for both withdrawal and deposit events. Below are examples of webhook payloads you might receive.

### Withdrawals

When a withdrawal is initiated or completed, we send a webhook event.

<CodeGroup>
  ```json Pending Withdrawal theme={null}
  {
    "type": "WITHDRAWAL",
    "currency": "USDT",
    "amount": 10,
    "status": "PENDING",
    "reference": "eba50518-58bf-430b-b603-d52f9794a8ee",
    "transactionId": "d1ef5d75-0883-4183-9367-3d0417781fff",
    "createdAt": "2026-03-26T09:10:50.611Z",
    "lastUpdated": "2026-03-26T09:10:50.611Z",
    "hash": null,
    "network": "BSC",
    "address": "0x1FFE2134c82D07227715af2A12D1406165A305BF"
  }
  ```

  ```json Successful Withdrawal theme={null}
  {
    "type": "WITHDRAWAL",
    "currency": "USDT",
    "amount": 10,
    "status": "SUCCESSFUL",
    "reference": "6698fa68-9d39-40c5-87aa-c72b706437ae",
    "transactionId": "b1ce4f58-3141-4449-938f-8329511497ec",
    "createdAt": "2026-03-26T09:29:39.420Z",
    "lastUpdated": "2026-03-26T09:29:39.420Z",
    "hash": "adfb8a07-7193-4b19-8bcd-88e60d1c03d1",
    "network": "BSC",
    "address": "0x1FFE2134c82D07227715af2A12D1406165A305BF"
  }
  ```
</CodeGroup>

### Deposits

We also send webhook event on deposit action.

<CodeGroup>
  ```json Confirmed Deposit theme={null}
  {
    "hash": "0xe62236173d7427b73782c4d09863f01de418b7a2029841bcabfb35870c8d4f6c",
    "type": "DEPOSIT",
    "currency": "BNB",
    "address": "0x6f44D28c9aD050a101020a34B874Fd1B9Ed56Cdd",
    "amount": 0.3,
    "status": "CONFIRMED",
    "reference": "cbbf9e70-6e79-4513-905c-8dc584fbfee2",
    "transactionId": "8e91df33-077d-4702-9097-25051f21fb74",
    "createdAt": "2024-06-06T12:56:32.076Z",
    "lastUpdated": "2024-06-06T12:56:32.076Z"
  }
  ```
</CodeGroup>

<br />

## Signature Verification

All webhook requests include the header:

```
x-obiex-signature: <HMAC-SHA512 hex digest>
```

This signature is generated using your **Signature Secret** as a HMAC SHA512 of the raw request body.

### Verifying the Signature

1. Read the **raw request body** as a string (do not parse first).
2. Read the `x-obiex-signature` header.
3. Compute HMAC SHA512 of the raw body using your Signature Secret.
4. Hex-encode the result.
5. Compare with the received signature.

### Example: Node.js (Express)

```typescript theme={null}
import crypto from 'crypto';
import express from 'express';

const app = express();
const signatureSecret = process.env.OBIEX_SIGNATURE_SECRET!;

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const receivedSignature = req.headers['x-obiex-signature'] as string;
  const body = req.body.toString();
  
  const computedSignature = crypto
    .createHmac('sha512', signatureSecret)
    .update(body)
    .digest('hex');
  
  if (computedSignature !== receivedSignature) {
    return res.status(401).send('Invalid signature');
  }
  
  // Signature is valid - process webhook
  const webhookEvent = JSON.parse(body);
  console.log('Received webhook:', webhookEvent);
  
  res.status(200).send('Received');
});

app.listen(3000, () => {
  console.log('Listening for webhooks on port 3000');
});
```

<Note>
  Always verify the signature before processing any webhook event to ensure it was sent by Obiex.
</Note>


# Collections
Source: https://developer.obiex.finance/features/collections

Generate unique wallet addresses for your users to receive funds

With our deposit system, you can generate unique wallet addresses for your users to receive funds. These addresses can be used for cryptocurrency deposits, and once a deposit is received, you'll be notified via webhook with transaction details to allow for further processing on your end.

## Key Features

### Generate Wallet Addresses

You can generate unique wallet addresses for your users using the **Create Deposit Address** endpoint. These addresses allow users to receive cryptocurrency deposits from other addresses.

To ensure a new address is created, the **uniqueUserIdentifier** in the request payload must be unique per customer. If the same **uniqueUserIdentifier** is used as in a previous request, the existing wallet address associated with that purpose will be returned instead of creating a new one.

<Note>
  If you're generating multiple addresses for a customer, **purpose** should be the same regardless of what currency/network you're generating the address for.
</Note>

You can use the **Get Active Networks** endpoint to see the list of networks associated with the currencies we support along with other information like withdrawal and deposit fees.

<Warning>
  We've changed the property name from **`purpose`** to **`uniqueUserIdentifier`** to highlight its requirement for uniqueness among users. If your current integration uses **`purpose`**, you don't need to make any changes - it is fully backward compatible and will continue to work.
</Warning>

### List Deposit Addresses

Use the **Get Deposit Addresses** endpoint to retrieve a list of deposit addresses you have generated.

### Receive Deposits

Once funds are sent to a wallet address, we'll notify you via a webhook with transaction details, enabling you to process the deposit accordingly.

### Sample Deposit Webhook

```json theme={null}
{
  "hash": "0xe62236173d7427b73782c4d09863f01de418b7a2029841bcabfb35870c8d4f6c",
  "type": "DEPOSIT",
  "currency": "BNB",
  "address": "0x6f44D28c9aD050a101020a34B874Fd1B9Ed56Cdd",
  "amount": 0.3,
  "status": "CONFIRMED",
  "reference": "cbbf9e70-6e79-4513-905c-8dc584fbfee2",
  "transactionId": "8e91df33-077d-4702-9097-25051f21fb74",
  "createdAt": "2024-06-06T12:56:32.076Z",
  "lastUpdated": "2024-06-06T12:56:32.076Z"
}
```

<Warning>
  Only process deposits with a **CONFIRMED** status.
</Warning>

## Key Endpoints

| Method | Endpoint                      | Description                                                  |
| ------ | ----------------------------- | ------------------------------------------------------------ |
| POST   | `/addresses/broker`           | Create a deposit request by generating a new wallet address  |
| GET    | `/addresses/me/broker`        | List all deposit addresses associated with your business     |
| GET    | `/currencies/networks/active` | Lists supported networks and currencies with fee information |

## Fees

We do not charge a fee for generating wallets or on deposits.


# Invoice settlement
Source: https://developer.obiex.finance/features/invoice-settlement

Settle international invoices in USD using NGN, USDC, or USDT

Invoice settlement lets your business pay international invoices in USD using Nigerian Naira (NGNX), USDC, or USDT. You provide the invoice details and beneficiary bank account, and Obiex handles the conversion and cross-border transfer.

## Funding source

Every invoice requires a `fundingSource` — either `DEPOSIT` or `WALLET`. This determines both how the payment is collected and which source currencies are accepted. If omitted, it defaults to `DEPOSIT`.

| `fundingSource` | Accepted source currencies | How it works                                                                                        |
| --------------- | -------------------------- | --------------------------------------------------------------------------------------------------- |
| `DEPOSIT`       | NGNX                       | Obiex provides a virtual NGN bank account. You transfer the required amount within 30 minutes.      |
| `WALLET`        | NGNX, USDC, USDT           | Obiex debits the required amount from your wallet immediately. Invoice goes straight to `APPROVED`. |

## How it works

<Tabs>
  <Tab title="DEPOSIT (NGNX)">
    <Steps>
      <Step title="Upload your invoice document">
        Upload the invoice file (image or PDF) via the document upload endpoint. You'll receive a URL to include when creating the invoice.
      </Step>

      <Step title="Create the invoice">
        Submit the invoice with `fundingSource: "DEPOSIT"`, `source: "NGNX"`, the target USD amount, beneficiary bank details, and the document URL. Obiex returns a virtual NGN bank account and the exact NGN amount to deposit.
      </Step>

      <Step title="Deposit NGN">
        Transfer the exact NGN amount to the virtual account provided. The account is valid for **30 minutes**. The invoice expires if no deposit is received within that window.
      </Step>

      <Step title="Settlement">
        Once the deposit is confirmed, the invoice moves to `APPROVED` and Obiex processes the USD payout to the beneficiary account.
      </Step>
    </Steps>

    <Warning>
      The virtual account expires 30 minutes after the invoice is created. If payment is received after expiry, the invoice is marked `EXPIRED` and the NGN is credited back to your wallet.
    </Warning>
  </Tab>

  <Tab title="WALLET (NGNX, USDC, USDT)">
    <Steps>
      <Step title="Upload your invoice document">
        Upload the invoice file (image or PDF) via the document upload endpoint. You'll receive a URL to include when creating the invoice.
      </Step>

      <Step title="Create the invoice">
        Submit the invoice with `fundingSource: "WALLET"`, the source currency (`NGNX`, `USDC`, or `USDT`), the target USD amount, beneficiary bank details, and the document URL. Obiex immediately debits the required amount from your wallet and sets the invoice to `APPROVED`. No virtual account is generated.
      </Step>

      <Step title="Settlement">
        Obiex processes the USD payout to the beneficiary account. You can track progress via the invoice status or webhook notifications.
      </Step>
    </Steps>

    <Info>
      Your wallet must have sufficient balance in the chosen source currency at the time of creation. If the balance is insufficient, the request is rejected and nothing is debited.
    </Info>
  </Tab>
</Tabs>

## Invoice status lifecycle

| Status       | Description                                                                 |
| ------------ | --------------------------------------------------------------------------- |
| `PENDING`    | Invoice created, awaiting NGN deposit (`DEPOSIT` funding only)              |
| `APPROVED`   | Deposit confirmed (`DEPOSIT`) or wallet debited (`WALLET`) — payout pending |
| `PROCESSING` | USD payout is being processed                                               |
| `COMPLETED`  | Payout completed. A `trackingId` is attached                                |
| `FAILED`     | Payout failed                                                               |
| `EXPIRED`    | Virtual account expired before deposit was received (`DEPOSIT` only)        |
| `REFUNDED`   | Funds returned to your account                                              |

## Webhook notifications

Obiex sends a webhook to your callback URL on every status change. For `DEPOSIT` invoices, the payload includes virtual account fields. For `WALLET` invoices, those fields are `null`.

<CodeGroup>
  ```json DEPOSIT invoice (NGNX) theme={null}
  {
    "type": "INVOICE",
    "invoiceId": "a3f1c2d4-8b0e-4f3a-9c7d-1e2b3a4c5d6e",
    "reference": "INV-2026-001",
    "status": "COMPLETED",
    "sourceCurrency": "NGNX",
    "sourceAmount": 1625000,
    "targetCurrency": "USD",
    "targetAmount": 1000,
    "rate": 1625,
    "beneficiaryAccountNumber": "12345678901",
    "beneficiaryAccountName": "Acme Corp",
    "beneficiaryBankName": "First International Bank",
    "swiftCode": "FIBKUS33XXX",
    "virtualAccountNumber": "9012345678",
    "virtualAccountName": "Obiex / Acme Corp",
    "virtualBankName": "Providus Bank",
    "accountExpiresAt": "2026-06-10T11:30:00.000Z",
    "createdAt": "2026-06-10T11:00:00.000Z",
    "lastUpdated": "2026-06-10T12:45:00.000Z",
    "trackingId": "TRK-20260610-001"
  }
  ```

  ```json WALLET invoice (USDC) theme={null}
  {
    "type": "INVOICE",
    "invoiceId": "b7e2d1c3-9a0f-4e2b-8d6c-2f3a4b5c6d7e",
    "reference": null,
    "status": "COMPLETED",
    "sourceCurrency": "USDC",
    "sourceAmount": 1000,
    "targetCurrency": "USD",
    "targetAmount": 1000,
    "rate": 1,
    "beneficiaryAccountNumber": "12345678901",
    "beneficiaryAccountName": "Acme Corp",
    "beneficiaryBankName": "First International Bank",
    "swiftCode": "FIBKUS33XXX",
    "virtualAccountNumber": null,
    "virtualAccountName": null,
    "virtualBankName": null,
    "accountExpiresAt": null,
    "createdAt": "2026-06-10T11:00:00.000Z",
    "lastUpdated": "2026-06-10T12:45:00.000Z",
    "trackingId": "TRK-20260610-002"
  }
  ```
</CodeGroup>

## Key endpoints

| Method | Endpoint                | Description                               |
| ------ | ----------------------- | ----------------------------------------- |
| POST   | `/uploads/invoices`     | Upload an invoice document (image or PDF) |
| POST   | `/invoices`             | Create an invoice                         |
| GET    | `/invoices/me`          | List all invoices for your account        |
| GET    | `/invoices/{invoiceId}` | Get a single invoice by ID                |


# Payouts
Source: https://developer.obiex.finance/features/payouts

Withdraw funds to cryptocurrency wallets or bank accounts

Users can withdraw funds from their wallet to either another cryptocurrency wallet or a bank account. During crypto withdrawals, it's important to ensure that the destination address matches the correct network, as sending funds to an incompatible network could result in the loss of funds. Additionally, bank account withdrawals involve converting crypto to fiat, which is then sent to the provided bank account.

## Withdrawal Status Lifecycle

When a withdrawal is initiated, its initial status can be either:

* **PENDING** – The withdrawal is awaiting approval. This is uncommon and typically occurs in edge cases.
* **APPROVED** – The withdrawal is approved and ready for processing.
* **SUCCESSFUL** – If the withdrawal address is issued by Obiex (e.g., the destination is another Obiex user), the transaction may be processed instantly and marked as **SUCCESSFUL** immediately.

As the withdrawal progresses, it transitions through the following statuses:

* **PROCESSING** – The withdrawal has begun processing.
* **SUCCESSFUL** – The payout was completed successfully.
* **FAILED** – The payout failed and the funds have been refunded to your balance. You can safely issue a refund to the user at this point.
* **REJECTED** – The payout was rejected and will be reversed to your balance within a few minutes.

When the withdrawal reaches a final state, the status will either be SUCCESSFUL or FAILED.

## Key Features

### Cryptocurrency Withdrawals

Ensure the destination address is on the same network as the sending wallet. For example, if sending USDT on the TRC20 network, the destination must also be a USDT TRC20 address; otherwise, the funds will be lost.

For crypto withdrawals, use the **Get Withdrawal Currency Networks** endpoint to see networks available for withdrawal for a currency.

### Fiat Withdrawals

To withdraw to a bank account, users must provide valid bank account details. The system will convert the cryptocurrency to fiat and transfer it to the provided account.

### Notifications

Similar to deposits, once a withdrawal is initiated, you'll receive a webhook notification to track the status and process the transaction.

### Sample Withdrawal Webhook

```json theme={null}
{
  "type": "WITHDRAWAL",
  "currency": "USDT",
  "amount": 10,
  "status": "SUCCESSFUL",
  "reference": "6698fa68-9d39-40c5-87aa-c72b706437ae",
  "transactionId": "b1ce4f58-3141-4449-938f-8329511497ec",
  "createdAt": "2026-03-26T09:29:39.420Z",
  "lastUpdated": "2026-03-26T09:29:39.420Z",
  "hash": "adfb8a07-7193-4b19-8bcd-88e60d1c03d1",
  "network": "BSC",
  "address": "0x1FFE2134c82D07227715af2A12D1406165A305BF"
}
```

<Warning>
  We charge a fee for withdrawals to wallet addresses not generated on our platform (that is, external withdrawal). This fee varies based on the currency and network.
</Warning>

## Key Endpoints

| Method | Endpoint                    | Description                                       |
| ------ | --------------------------- | ------------------------------------------------- |
| POST   | `/wallets/ext/debit/fiat`   | Initiate a fiat withdrawal to a bank account      |
| POST   | `/wallets/ext/debit/crypto` | Initiate a crypto withdrawal to a wallet address  |
| GET    | `/currencies/{id}/networks` | List available withdrawal networks for a currency |


# Trading
Source: https://developer.obiex.finance/features/trading

Swap between supported currencies using our RFQ system or instant swap

Our platform supports trading between a variety of currencies. You can either use the **RFQ (Request for Quote)** system — where you lock in a rate before confirming — or the **Instant Swap** endpoint, which creates and executes the trade in a single request.

## Key Features

### Currency Availability

Use the **Get Tradable Currencies** endpoint to display the list of tradable currencies supported by the platform. These are the only currencies allowed for swaps.

### Trading Pairs

Use the **Get Pairs** endpoint to retrieve the supported currency pairs for trading. For example, a supported trade pair might be BTC-USDT.

### Instant Swap

The simplest way to execute a trade. A single request to `/trades/swap` creates a quote and executes the trade immediately at the best available rate — no need to call create-quote and accept-quote separately.

Provide either `amount` (how much of the source currency you are selling) or `amountToReceive` (the exact amount of the target currency you want), but not both.

```json theme={null}
{
  "sourceId": "USDT",
  "targetId": "NGNX",
  "amount": 10,
  "side": "SELL"
}
```

<Note>
  There are no extra charges for this service.
</Note>

### RFQ System

Use the two-step RFQ flow when you want to show users a confirmed rate before committing to the trade.

1. **Create Quote**: Obtain a quote by specifying source currency, target currency, amount, and side (BUY/SELL). The response includes the swap rate, the amount you'll receive, and a validity window in seconds.

   For example, if you're swapping 1,000 USDT to BTC, the quote will include the current rate (e.g., 67,648.9154 USDT per BTC) and show the amount you'll receive in BTC (0.0478218 BTC).

2. **Validity Window**: The quote must be accepted within this time window. If it expires, request a new quote.

3. **Accept Quote**: Pass the `quoteId` from the Create Quote response to confirm the swap. Funds are deducted from your source wallet and credited to your target wallet.

<Warning>
  The Create Quote endpoint is meant for trades you intend to execute, not for checking current prices or tickers. It is limited to **100 requests per hour** per API key.
</Warning>

### Transaction History

To review swap transactions, use the **Get User Trades** endpoint. You can filter by side (buy/sell), currency ID, and date.

## Key Endpoints

| Method | Endpoint                  | Description                                             |
| ------ | ------------------------- | ------------------------------------------------------- |
| GET    | `/currencies/tradeable`   | List of tradable currencies on our platform             |
| GET    | `/trades/pairs`           | Retrieve supported currency pairs                       |
| POST   | `/trades/swap`            | Create and execute a swap in one request (instant swap) |
| POST   | `/trades/quote`           | Create a quote (RFQ flow)                               |
| POST   | `/trades/quote/{quoteId}` | Accept a quote to complete the swap (RFQ flow)          |
| GET    | `/trades/summary/me`      | Review transaction history                              |

## Flow

**Instant swap** (recommended for most integrations):

1. Fetch tradable currencies and pairs
2. Call `/trades/swap` with the source, target, and amount

**RFQ flow** (use when you want to display a locked-in rate to the user):

1. Fetch tradable currencies and pairs
2. Call `/trades/quote` to get a rate and quote ID
3. Call `/trades/quote/{quoteId}` within the validity window to confirm


# Transactions
Source: https://developer.obiex.finance/features/transactions

Track wallet balances and view transaction records

These endpoints allow you to track your wallet balances and view detailed records of all transactions, whether deposits, withdrawals, or swaps on your master wallet and associated wallet addresses.

## Key Endpoints

### Get Wallet Balance

Use this endpoint to retrieve the current balance of a user's wallet. This includes balances for all supported currencies within the account. It's useful for displaying the available funds before initiating deposits, withdrawals, or swaps.

* **Endpoint**: `GET /wallets/{currencyCode}` (e.g., `/wallets/USDT`)

### Get User Transactions

This endpoint retrieves a list of transactions performed by the user. The results can be filtered by several parameters such as currency, category, type, and date range to narrow down specific transactions. The response can also be paginated to handle large data sets.

* **Endpoint**: `GET /transactions/me`

**Filters:**

| Parameter  | Description                                                                                          |
| ---------- | ---------------------------------------------------------------------------------------------------- |
| Currency   | Filter by specific currency (e.g., BTC, USDT)                                                        |
| Category   | Specify the category (e.g., deposits, withdrawals, swaps)                                            |
| Type       | Filter by transaction type (e.g., buy, sell)                                                         |
| Date Range | Filter by start and end date to view transactions within a specific time period                      |
| Pagination | Supports pagination with parameters like `page` and `limit` for managing large transaction histories |

### Get Transaction by ID

Use this endpoint to retrieve detailed information about a specific transaction by providing its unique ID. The response includes full details of the transaction, such as the amount, status, currency, and timestamps.

* **Endpoint**: `GET /transactions/{id}`


# Introduction
Source: https://developer.obiex.finance/index

Welcome to the Obiex API documentation, your guide to building amazing experiences with our powerful crypto APIs.

## Features

Explore our key features to integrate payments into your application.

<Columns>
  <Card icon="wallet" href="/features/collections" title="Collections">
    Generate unique wallet addresses for your users to receive crypto deposits.
  </Card>

  <Card icon="repeat" href="/features/trading" title="Trading">
    Swap between supported currencies using our RFQ system.
  </Card>

  <Card icon="coins" href="/features/payouts" title="Payouts">
    Withdraw funds to cryptocurrency wallets or bank accounts.
  </Card>

  <Card icon="history" href="/features/transactions" title="Transactions">
    Track wallet balances and view transaction records.
  </Card>
</Columns>

## API Reference

Explore our API endpoints.

<Card icon="square-terminal" href="/api-reference/introduction" title="API Documentation">
  View our API reference documentation.
</Card>


# Node.js SDK
Source: https://developer.obiex.finance/sdks/node

Use the official Obiex Node.js client to integrate from any JavaScript or TypeScript project

The Obiex Node.js SDK is a thin, typed wrapper around the [REST API](/api-reference/introduction). It handles request signing (HMAC SHA-256), base URL selection, and response typing so you can focus on your integration rather than on the transport.

## Requirements

* Node.js **20+**
* An Obiex API key and secret. Generate them under **Settings → Developers → API Keys** in your account dashboard.

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install obiex-api
  ```

  ```bash yarn theme={null}
  yarn add obiex-api
  ```

  ```bash pnpm theme={null}
  pnpm add obiex-api
  ```
</CodeGroup>

## Quickstart

Instantiate `ObiexClient` once and reuse it across your application. The client signs every outbound request with your secret — you never have to compute the HMAC yourself.

```typescript theme={null}
import { ObiexClient } from 'obiex-api';

const client = new ObiexClient({
  apiKey: process.env.OBIEX_API_KEY!,
  apiSecret: process.env.OBIEX_API_SECRET!,
  sandboxMode: true, // false in production
});

// Your first call: fetch the currencies you can trade
const currencies = await client.getTradableCurrencies();

console.log(currencies.map(c => c.code));
```

<Note>
  All testing should be done with `sandboxMode: true`. No real funds move in the staging environment.
</Note>

## Configuration

The constructor accepts a single `Options` object:

| Option        | Type      | Required | Description                                               |
| ------------- | --------- | -------- | --------------------------------------------------------- |
| `apiKey`      | `string`  | Yes      | Your API key from the dashboard.                          |
| `apiSecret`   | `string`  | Yes      | The matching secret. Never expose this client-side.       |
| `sandboxMode` | `boolean` | No       | When `true`, requests go to staging. Defaults to `false`. |

The client picks the correct base URL automatically:

| Environment | `sandboxMode` | Base URL                            |
| ----------- | ------------- | ----------------------------------- |
| Staging     | `true`        | `https://staging.api.obiex.finance` |
| Production  | `false`       | `https://api.obiex.finance`         |

## Error handling

Failed requests throw a `ServerError` carrying the HTTP status and the API's error payload. Catch and inspect it like any other typed error:

```typescript theme={null}
import { ObiexClient, ServerError } from 'obiex-api';

try {
  await client.withdrawCrypto('BTC', 999_999, {
    address: 'bc1q...',
    network: 'BTC',
  });
} catch (err) {
  if (err instanceof ServerError) {
    console.error('status:', err.statusCode); // e.g. 400
    console.error('payload:', err.data);      // structured API error
    return;
  }
  throw err;
}
```

Validation failures (4xx) and server errors (5xx) both surface as `ServerError` — branch on `err.statusCode` if you need to react differently.

## What's next

The SDK mirrors every domain in the API Reference. Pair the guides on the left with the matching client methods:

<CardGroup>
  <Card title="Collections (deposit addresses)" icon="wallet" href="/features/collections">
    `getDepositAddress`, `getDepositAddresses`
  </Card>

  <Card title="Trading" icon="repeat" href="/features/trading">
    `createQuote`, `acceptQuote`, `trade`, `getTradePairs`
  </Card>

  <Card title="Payouts" icon="paper-plane" href="/features/payouts">
    `withdrawCrypto`, `withdrawNaira`, `getBanks`
  </Card>

  <Card title="Invoice settlement" icon="file-invoice" href="/features/invoice-settlement">
    `uploadInvoiceDocument`, `createInvoice`, `getInvoices`
  </Card>
</CardGroup>

For the full method reference and the latest changelog, see the [SDK on GitHub](https://github.com/obiexhq/obiex-api-javascript).

## Without the SDK

You can call the API directly with any HTTP client — the SDK exists for convenience, not as a requirement. If you'd rather hand-roll the request signing (or you're on a runtime the SDK doesn't target), the [Authentication](/api-reference/authentication) page walks through the HMAC scheme step by step.


# Hedging
Source: https://developer.obiex.finance/use-cases/hedging

Protect your holdings from crypto volatility using instant swaps

Crypto assets can move significantly in value within short periods. Hedging lets you manage that exposure by swapping volatile assets into stable currencies (and back) using Obiex's RFQ trading system. This is useful for businesses that hold crypto treasury, platforms processing payments in volatile currencies, or any integration where price risk needs to be controlled.

## Common scenarios

* **Locking in value after a deposit**: A user deposits BTC. You immediately swap it to USDT to avoid exposure to BTC price movements while the funds are held.
* **Timing a payout**: You hold USDT and want to convert to NGN right before settling a payout, minimising the time your funds sit in a volatile position.
* **Rebalancing treasury**: You hold a mix of assets and want to rebalance into stablecoins at the end of each day.

## How it works

<Steps>
  <Step title="Get a quote">
    Call the Create quote endpoint with your source currency, target currency, amount, and side (BUY or SELL). The response includes the current rate and the exact amount you'll receive, along with a validity window in seconds.
  </Step>

  <Step title="Review and accept">
    If the rate is acceptable, accept the quote within the validity window using the returned `quoteId`. Obiex executes the swap instantly at the quoted rate.
  </Step>

  <Step title="Confirm the new balance">
    After the swap, your source wallet is debited and your target wallet is credited. You can verify the updated balance via the wallet endpoint.
  </Step>
</Steps>

<Warning>
  Quotes expire quickly, typically within 30 seconds. Always check `expiresIn` and accept before the window closes. If the quote expires, request a new one.
</Warning>

<Note>
  There are no extra charges for trading. Obiex does not add fees on top of the quoted rate.
</Note>

## Supported pairs

Use the `/trades/pairs` endpoint to see all available trading pairs. Common pairs include:

* BTC / USDT
* ETH / USDT
* BNB / USDT
* USDT / NGNX

You can also query a specific pair to get current rate information before requesting a formal quote.

<Warning>
  Use the Create Quote endpoint only when you intend to trade, not to check tickers or poll prices. It is limited to **100 requests per hour** per API key.
</Warning>

## Key endpoints

| Method | Endpoint                                  | Description                         |
| ------ | ----------------------------------------- | ----------------------------------- |
| GET    | `/trades/pairs`                           | List all supported trading pairs    |
| GET    | `/trades/pairs/{sourceCode}/{targetCode}` | Get rate info for a specific pair   |
| POST   | `/trades/quote`                           | Request a swap quote                |
| POST   | `/trades/quote/{quoteId}`                 | Accept a quote and execute the swap |
| GET    | `/wallets/{currencyCode}`                 | Verify updated balance after a swap |
| GET    | `/trades/summary/me`                      | Review swap history                 |


# Off-ramping
Source: https://developer.obiex.finance/use-cases/off-ramping

Convert cryptocurrency to fiat and pay out to bank accounts

Off-ramping lets you convert crypto held in your Obiex wallet into local fiat currency and send it directly to a bank account. This is useful for businesses that collect crypto payments and need to settle in local currency, or platforms that offer crypto-to-cash withdrawals for their users.

## How it works

<Steps>
  <Step title="Check your wallet balance">
    Use the wallet balance endpoint to confirm you have sufficient funds before initiating a withdrawal.
  </Step>

  <Step title="Swap to a fiat-pegged currency (optional)">
    If your wallet holds a volatile asset like BTC, you can use the RFQ trading system to swap it to a stable currency like USDT before withdrawing.
  </Step>

  <Step title="Initiate a fiat withdrawal">
    Make a request to the fiat withdrawal endpoint with the destination bank account details and amount. Obiex handles the conversion and bank transfer.
  </Step>

  <Step title="Track the withdrawal">
    Monitor the withdrawal status via the transactions endpoint or listen for webhook events. Once the withdrawal reaches `SUCCESSFUL`, the funds have been sent to the bank account.
  </Step>
</Steps>

## Key endpoints

| Method | Endpoint                         | Description                                   |
| ------ | -------------------------------- | --------------------------------------------- |
| GET    | `/wallets/{currencyCode}`        | Check wallet balance before withdrawing       |
| GET    | `/ngn-payments/banks`            | List supported Nigerian banks and their codes |
| GET    | `/ngn-payments/accounts/resolve` | Verify a bank account before sending          |
| POST   | `/wallets/ext/debit/fiat`        | Initiate a fiat withdrawal to a bank account  |
| GET    | `/transactions/{transactionId}`  | Check withdrawal status                       |


# On-ramping
Source: https://developer.obiex.finance/use-cases/on-ramping

Accept fiat or crypto deposits and credit user wallets

On-ramping is the process of converting fiat or external crypto into a usable balance on your platform. With Obiex, you can generate unique deposit addresses for your users, accept crypto from any external wallet, and get notified the moment funds arrive. No polling required.

## How it works

<Steps>
  <Step title="Generate a deposit address">
    Call the deposit address endpoint with a unique identifier for your user. Obiex returns a wallet address tied to that user for a specific currency and network. If you call the endpoint again with the same identifier, the same address is returned.
  </Step>

  <Step title="Share the address with your user">
    Display the deposit address and network to your user so they can send funds from an external wallet or exchange.
  </Step>

  <Step title="Receive the deposit webhook">
    When the deposit is confirmed on-chain, Obiex sends a webhook to your webhook callback URL with the transaction details.
  </Step>

  <Step title="Optionally swap to another currency">
    If your platform operates in a specific currency (e.g. USDT) but a user deposited BTC, use the RFQ trading system to swap the received amount automatically.
  </Step>
</Steps>

<Note>
  Deposit addresses are reusable. The same address will receive multiple deposits over time, so you do not need to generate a new address per transaction.
</Note>

## Key endpoints

| Method | Endpoint                      | Description                                         |
| ------ | ----------------------------- | --------------------------------------------------- |
| POST   | `/addresses/broker`           | Generate a deposit address for a user               |
| GET    | `/addresses/me/broker`        | List all deposit addresses you have generated       |
| GET    | `/currencies/networks/active` | List supported networks and deposit fee information |
| GET    | `/wallets/{currencyCode}`     | Check your master wallet balance                    |