# Welcome

### Understanding orda <a href="#understanding-orda" id="understanding-orda"></a>

Developers use orda to submit an intent (e.g., “swap 1,000 USDC → BRZ”) and the network finds the best execution through competing solvers.

The orda network is the coordination layer that makes global value movement efficient:

* **Intents:** Developers define *what* they want.
* **Solvers:** Competing participants fulfill those intents at the best price.

### Why orda exists

Moving value today is fragmented. The same value can cost anywhere between **0–300 bps** to transfer, depending on who you are and how you connect:

| Market Segment     | Typical Fees | Access Mechanism           | Settlement Time |
| ------------------ | ------------ | -------------------------- | --------------- |
| Tier 1 Interbank   | 0–8 bps      | Bilateral                  | T+0             |
| Institutional      | 12–18 bps    | Prime Broker               | T+0 – T+1       |
| Corporate Treasury | 16–50 bps    | Bank Desk Markup           | T+0 – T+2       |
| Processors         | 25–70 bps    | Aggregator RFQ             | T+1 – T+3       |
| Retail / SME       | 100–300+ bps | Card Networks & Bank Rails | Instant – T+3   |

Different participants pay radically different spreads for the *same movement of value*, because of float fragmentation and layers of intermediaries.

### How orda changes it

orda collapses this complexity by acting as a **coordination layer**:

* **Unified access:** One integration to reach banks, blockchains, and stablecoin systems.
* **Solver competition:** Multiple counterparties compete to fulfill each intent, compressing spreads toward interbank levels.
* **Vaults:** Shared liquidity replaces pre-funding, making float productive and settlement faster.

Instead of multiple pricing tiers, developers get **a single fair price,** all from **a single interface**.

{% hint style="info" %}
Whether you’re building an exchange, wallet or payments app, orda abstracts the mess of FX and liquidity into a single priced, programmable layer.
{% endhint %}

### Use Cases

{% tabs %}
{% tab title="🌍 Cross-Border / FX" %}
Move value between fiat and stablecoin corridors at competitive spreads.

**Example scenarios:**

* Remittance platforms sending USD → BRL in real-time
* Treasury desks converting USDC → BRL for local operations
* Marketplaces settling payouts to sellers across borders

**How to build it:**

* Use the **API or SDK** to integrate quickly
* **Generate wallets** for settlement flows
* **Create recipients** with bank or crypto details
* **Begin quoting** FX intents and fulfill at best price
  {% endtab %}

{% tab title="💳 Ramps" %}
Embed on/off-ramping into your app with a few lines of code.

**Example scenarios:**

* Wallets adding local bank deposits/withdrawals
* Exchanges offering direct top-ups
* Fintech apps letting users buy stablecoins instantly

**How to build it:**

* Create a Recipient with bank or crypto settlement details
* Request a quote and pass it to the end user to execute
* Use the widget for plug & use
  {% endtab %}

{% tab title="🔄 Swaps & Bridges" %}
Unify fragmented liquidity across blockchains and stablecoins.

**Example scenarios:**

* Swap USDC on Ethereum → BRZ on Base
* Bridge AUSD from Plasma → Solana
* Build network & currency abstracted apps with intent-based routing

**How to build it:**

* Use the **API** or **SDK** for cross-chain swaps
* Or embed the Widget for a drop-in swap UI
* Let solvers compete for best execution across chains
  {% endtab %}

{% tab title="⚙️ Advanced" %}
Push beyond basic flows with primitives that unlock infrastructure-level use cases.

**Example scenarios:**

* **On-chain liquidity management:** Borrow from vaults, rebalance float and monitor utilization without fragmented pre-funding
* **Chain-abstracted infrastructure:** Submit one intent and let solvers handle routing across chains and assets
* **Unified balances:** Power wallets with a single spendable balance (fiat + stablecoins + chains), bridging abstraction but extended to banks.
* **Solver strategies:** Run custom solver bots to capture spreads, arbitrage across corridors, or internalize margins as a PSP
  {% endtab %}
  {% endtabs %}

### Get started

* [**Quickstart**](/developers/quickstart)**:** Make your first request in 5 minutes
* [**Developer Portal**](https://app.orda.network/)**:** Authentication Access
* [**SDKs**](/developers/sdk)**:** Use orda in TypeScript & React (more coming soon)
* [**API Reference**](/developers/api)**:** Full endpoint documentation


# Who is an orda solver?

Solvers power the orda network

A **solver** is any participant who brings capital, routing, or execution to fulfill intents on the network. Unlike traditional market makers limited to crypto or FX, solvers in orda can operate across **fiat, stablecoins and blockchains** with the same interface.

#### What it means to be a solver

A solver is not just a market maker, it’s any participant who can bring capital, routing or execution to the table.

As a solver, you:

* **See intents first:** get visibility into real orderflow across multiple corridors.
* **Compete on price + speed:** win flow by offering the best execution.

#### Who typically becomes a solver

* **FX Desks & Brokers:** monetize corridor pricing.
* **Market Makers & LPs:** deploy capital where flow is.
* **Searchers & Quants:** capture cross-venue spreads and routing edge.
* **Fintechs & PSPs:** act as their own solver to internalize margin.

#### Why it matters

Solvers don’t just quote, they create the competitive environment that collapses spreads. Every new solver strengthens the network, increases liquidity and reduces costs for all participants.

***

> **You might already be a solver.**\
> Join the network, quote into live intents and help drive access to interbank levels. [Apply here](https://412149.share-na2.hsforms.com/2ErMKYKXtRgex2nypp4mMnQ)


# Pricing & Coverage

Value shouldn’t be priced by your volume.

### **S**olver Competition → Single Unified Tier

<table><thead><tr><th width="170.625">Market Segment</th><th width="120.49609375">Fees</th><th width="277.2578125">Access Mechanism</th><th>Settlement Time</th></tr></thead><tbody><tr><td>Everyone</td><td>0bps</td><td>orda network: RFQ &#x26; Intents</td><td>T+0</td></tr></tbody></table>

### Blockchain Coverage <a href="#integrations" id="integrations"></a>

<table><thead><tr><th width="160.37109375">Status</th><th width="209.83203125">Name</th><th width="159.5859375">NetworkID</th><th>Token Support</th></tr></thead><tbody><tr><td>✅ Live</td><td>Abstract</td><td><code>2741</code></td><td>Limited</td></tr><tr><td>✅ Live</td><td>Arbitrum</td><td><code>42161</code></td><td>All</td></tr><tr><td>✅ Live</td><td>Avalanche C-Chain</td><td><code>43114</code></td><td>All</td></tr><tr><td>✅ Live</td><td>Base</td><td><code>8453</code></td><td>All</td></tr><tr><td>✅ Live</td><td>Berachain</td><td><code>80094</code></td><td>All</td></tr><tr><td>🚧 In Progress</td><td>Bitcoin</td><td><code>1001002</code></td><td>Limited</td></tr><tr><td>✅ Live</td><td>BSC</td><td><code>56</code></td><td>All</td></tr><tr><td>✅ Live</td><td>CELO</td><td><code>42220</code></td><td>All</td></tr><tr><td>✅ Live</td><td>Ethereum</td><td><code>1</code></td><td>All</td></tr><tr><td>✅ Live</td><td>Gnosis</td><td><code>100</code></td><td>All</td></tr><tr><td>🚧 In Progress</td><td>HyperEVM</td><td><code>N/A</code></td><td>All</td></tr><tr><td>🚧 In Progress</td><td>Hyperliquid</td><td><code>N/A</code></td><td>Limited</td></tr><tr><td>✅ Live</td><td>Mantle</td><td><code>5000</code></td><td>Limited</td></tr><tr><td>✅ Live</td><td>MegaETH</td><td><code>4326</code></td><td>All</td></tr><tr><td>🚧 In Progress</td><td>Monad</td><td><code>N/A</code></td><td>All</td></tr><tr><td>✅ Live</td><td>Optimism</td><td><code>10</code></td><td>All</td></tr><tr><td>✅ Live</td><td>Plasma</td><td><code>9745</code></td><td>All</td></tr><tr><td>✅ Live</td><td>Polygon</td><td><code>137</code></td><td>All</td></tr><tr><td>✅ Live</td><td>Scroll</td><td><code>534352</code></td><td>All</td></tr><tr><td>✅ Live</td><td>SEI</td><td><code>1329</code></td><td>Limited</td></tr><tr><td>✅ Live</td><td>Solana</td><td><code>1001001</code></td><td>All</td></tr><tr><td>✅ Live</td><td>Stable</td><td><code>988</code></td><td>Limited</td></tr><tr><td>🚧 In Progress</td><td>Starknet</td><td><code>N/A</code></td><td><code>N/A</code></td></tr><tr><td>🚧 In Progress</td><td>Tempo</td><td><code>N/A</code></td><td><code>N/A</code></td></tr><tr><td>🕓 Planned</td><td>Tron</td><td><code>N/A</code></td><td><code>N/A</code></td></tr><tr><td>✅ Live</td><td>Unichain</td><td><code>130</code></td><td>All</td></tr><tr><td>✅ Live</td><td>Worldchain</td><td><code>480</code></td><td>All</td></tr></tbody></table>

### Banking Rail Coverage

<table><thead><tr><th>Status</th><th>Region</th><th width="119.8359375">Currencies</th><th>Types</th><th>Settlement Time</th></tr></thead><tbody><tr><td>Live</td><td>Brazil</td><td>BRL</td><td>PIX</td><td>minutes - hours</td></tr><tr><td>In Progress</td><td>USA</td><td>USD</td><td>ACH</td><td>minutes - 1 day</td></tr><tr><td>In Progress</td><td>Europe</td><td>EUR</td><td>SEPA</td><td>10 min - days</td></tr><tr><td>In Progress</td><td>Mexico</td><td>MXN</td><td>SPEI</td><td>minutes-hours</td></tr></tbody></table>

## Restricted Geographies <a href="#restricted-geographies" id="restricted-geographies"></a>

**Important Information Regarding International Transactions**

To ensure compliance with global regulations and promote safe financial practices, we kindly ask our customers to avoid conducting financial activities involving the following regions:

* Cuba
* Iran
* Sudan
* North Korea
* Venezuela
* Russia
* Ukraine
* Belarus
* Myanmar (Burma)
* Syria


# FAQs

Reach out to the team if you have any further questions or inquiries

<details>

<summary>What exactly is an “intent”?</summary>

An intent is a structured request to move value: e.g., *“convert $10,000 BRL to USDC,”* *“settle $50,000 invoice in USD,”* or *“bridge USDT from Ethereum to Solana.”* Solvers see these intents and compete to fulfill them.

</details>

<details>

<summary>How do solvers make money?</summary>

Solvers earn by quoting competitive prices and capturing fees or back running opportunities when they fulfill an intent. The better (faster, cheaper, more reliable) your quote, the more flow you win.

</details>

<details>

<summary>Do I need to pre-fund anything?</summary>

No. orda separates capital supply from execution.

</details>

<details>

<summary>Who can join as a solver?</summary>

Anyone with the ability to provide execution: FX desks, market makers, searchers, routing bots, even fintechs that want to internalize flow. If you can quote, you can solve. [Apply to join](https://412149.share-na2.hsforms.com/2ErMKYKXtRgex2nypp4mMnQ)

</details>

<details>

<summary>What are vaults?</summary>

Soon we will be releasing [Vaults](/solvers/vaults), where you can borrow corridor liquidity on-demand, so your balance sheet isn’t tied up with idle pre-funding.

</details>

<details>

<summary>How are spreads &#x26; fees determined?</summary>

Through competition. Multiple solvers see the same intent and quote simultaneously, best execution wins.

</details>


# Quickstart

Begin receiving quotes after 3 easy steps:

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-cover data-type="image">Cover image</th></tr></thead><tbody><tr><td>Create Account</td><td><a href="https://2927719792-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGNZX42boT5K8BnIz27Gl%2Fuploads%2F8jYHNLqxDVsnC11eca68%2Faccount.png?alt=media&amp;token=f6add92b-9cb6-4f59-b13d-80857cb29744">account.png</a></td></tr><tr><td>Create Project</td><td><a href="https://2927719792-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGNZX42boT5K8BnIz27Gl%2Fuploads%2FpjaCqnbosgrTFD15faow%2Fcreate.png?alt=media&amp;token=cd3a723a-cc74-4e30-bbc9-65178a111143">create.png</a></td></tr><tr><td>Save Project Keys</td><td><a href="https://2927719792-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGNZX42boT5K8BnIz27Gl%2Fuploads%2Fl8D2a5uZ8fpbQiykk8gk%2Fsave.png?alt=media&amp;token=2cbe7fb0-151b-46aa-a9a6-01e6c2cebbd4">save.png</a></td></tr></tbody></table>

#### Jump In With SDKs

{% tabs %}
{% tab title="Typescript" %}

```
import { OrdaSDK } from '@ordanetwork/sdk';

const orda = new OrdaSDK({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  // Never expose your clientSecret in frontend code
});

// Create a recipient with a smart wallet
const recipient = await orda.recipients.create({
  name: 'Test Recipient',
  cryptoSettlementDetails: {
    toChain: '8453',
    toToken: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
    // omit toAddress → auto-generates smart wallet
  }
});
console.log('Smart wallet:', recipient.smartWallet?.address);

// Request a quote
const quote = await orda.quote.request({
  fromChain: '1', // Ethereum mainnet
  fromToken: '0xA0b8...eB48', // USDC
  fromAddress: '0xYourAddress',
  intent: { method: 'usd', value: '100' },
  recipientId: recipient.recipientId,
});
```

{% endtab %}
{% endtabs %}

#### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

Before integrating with orda, ensure you're familiar with the following key concepts and workflows:

* An orda developer account ([Here](https://app.orda.network/))
* Project **clientID & secret** [(Learn more about auth here)](/developers/authentication)
* How to request & execute a quote
* Monitoring a quote/transaction

After registering, you'll need to generate a project key to start interacting with the orda network.

{% hint style="info" %}
If you want the embedded React component, jump to[Widget](/developers/widget).
{% endhint %}


# Authentication

#### Client ID/Secret Model <a href="#client-idsecret-model" id="client-idsecret-model"></a>

All API requests require proper signing with your Client Secret. The Client ID alone cannot be used to access the API.

* **Client ID:** Your public project identifier
* **Client Secret:** Your private signing key (must be kept secure)

**Important Security Note**: Knowing just your Client ID is not enough to access the API. All requests must be signed with your Client Secret.

{% hint style="info" %}
Obtain Keys [Here](https://app.orda.network/)
{% endhint %}

#### Security Benefits <a href="#security-benefits" id="security-benefits"></a>

This authentication model offers several security advantages:

* **Two-factor authentication**: Access requires both the Client ID and a valid signature
* **No secret transmission**: Your Client Secret is never sent to our servers
* **Request integrity**: The signature ensures requests haven't been tampered with
* **Reduced risk**: Even if your Client ID is exposed, attackers can't make API calls without the secret
* **Non-repudiation**: Signed requests provide a strong audit trail

#### Authentication Headers <a href="#authentication-headers" id="authentication-headers"></a>

All API requests to orda must include these headers:

| Header         | Description                                           |
| -------------- | ----------------------------------------------------- |
| `x-client-id`  | Your project's client ID                              |
| `x-signature`  | HMAC-SHA256 signature derived from your client secret |
| `Content-Type` | Usually application/json for requests with a body     |

**Optional Headers**

| Header        | Description                                                                    |
| ------------- | ------------------------------------------------------------------------------ |
| `x-timestamp` | Optional timestamp (in milliseconds since epoch) for preventing replay attacks |

#### Creating a Signature <a href="#creating-a-signature" id="creating-a-signature"></a>

The signature is an HMAC-SHA256 hash of the **canonicalized** request body, using your Client Secret as the key.

**Signature Process**

1. **Canonicalize** your request body to ensure consistent JSON serialization
2. For GET requests with no body, use an empty string
3. Create an HMAC-SHA256 hash of the canonical string using your Client Secret as the key
4. Convert the resulting hash to a hexadecimal string
5. Include this hex string in the x-signature header

**Canonical JSON Serialization**

The request body is canonicalized to ensure consistent signatures regardless of JSON key ordering:

* Object keys are sorted alphabetically
* No whitespace between elements
* Consistent string escaping
* Handles nested objects and arrays recursively

**Example:**

```json
// Original JSON (key order may vary)
{"name": "John", "age": 30, "city": "New York"}

// Canonical JSON (always same output)
{"age":30,"city":"New York","name":"John"}
```

**Security Recommendations**

* **Never share your Client Secret**: Your Client Secret should be treated like a password and never shared publicly or committed to version control.
* **Store secrets securely**: Use environment variables, secret management services, or secure storage solutions to manage your Client Secret.
* **Regenerate secrets if compromised**: If you suspect your Client Secret has been compromised, regenerate it immediately through the orda Dashboard.
* **Use HTTPS**: Always make API requests over HTTPS to ensure the security of your Client ID and signature.

**Implementation Tips**

* **Canonical JSON serialization**: The canonical serialization ensures consistent signatures regardless of object key ordering or JSON library differences.
* **Empty body handling**: For requests without a body (like GET requests), use an empty string as the input to the HMAC function.
* **Character encoding**: Always use UTF-8 encoding when converting strings to bytes for HMAC calculation.
* **Error handling**: Include proper error handling to diagnose signature creation issues during development.

#### Common Issues and Troubleshooting <a href="#common-issues-and-troubleshooting" id="common-issues-and-troubleshooting"></a>

**Invalid Signature Errors**

If you receive "Invalid signature" errors:

* **Check your Client Secret**: Ensure you're using the correct Client Secret for the Client ID.
* **Verify canonical serialization**: Ensure you're using the canonical JSON serialization method shown above.
* **HTTP method**: Confirm you're using the correct HTTP method (GET, POST, PUT, DELETE).
* **String encoding**: Verify you're using UTF-8 encoding for string conversions.
* **Empty bodies**: For GET requests, ensure you're signing an empty string, not "null" or "undefined".

#### Support <a href="#support" id="support"></a>

If you encounter any issues implementing this authentication method, reach out!


# API

A unified API for the new financial stack.

#### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

Before integrating with orda, ensure you're familiar with the following key concepts and workflows:

* Project **clientID & secret** vs **recipient** Id [(Learn more about auth here)](/developers/authentication)
* How to request & execute a quote
* Monitoring a quote/transaction
* Monetizing your order flow
* Create your account.

After registering, you'll need to generate a project key to start interacting with the orda API.

#### Core Concepts <a href="#core-concepts" id="core-concepts"></a>

**Authentication Types**

orda uses two distinct authentication concepts:

* **Project Client ID & Secret**: Used to authenticate your application's API requests
* **Recipient Client ID**: Identifies entities that can receive funds within your project

See the [Authentication Guide](/developers/authentication) for implementation details.

#### Transaction Flow <a href="#transaction-flow" id="transaction-flow"></a>

A typical transaction in orda follows this process:

1\. Request a quote for a specific value transfer

2\. Execute the quote to initiate the transaction

3\. Monitor the transaction status through completion

#### Creating a project <a href="#creating-a-project" id="creating-a-project"></a>

Head to our [dev portal ](http://app.orda.network/)to obtain your Client ID and Client Secret, and follow these steps:

1. Enter your **Project Name** to identify your integration.
2. Add a project description (optional) for internal specification.
3. **Add Members** (optional) who require access to the project.
4. Click **Generate Key**. Your Client ID & Client Secret will be displayed.
5. **Securely store** your **Client Secret**.

For security reasons, Client Secrets are only displayed once upon creation. Make sure to store it securely.

#### Managing or Starting your Integration <a href="#managing-or-starting-your-integration" id="managing-or-starting-your-integration"></a>

1. Log in or sign up on the [dev portal](https://app.orda.network/)
2. Navigate to the “Projects” section
3. Select the project you want to use or create a new one
4. Your Client ID will be displayed, and you can generate a new Client Secret

#### Next Steps <a href="#next-steps" id="next-steps"></a>

Once a project is created, you’ll receive a unique client ID & secret. Continue with the guides or API reference to properly integrate with *orda* to begin securely signing requests across blockchains & banking networks.


# Recipients

Recipients are used to onboard entities such as individuals or entities who will interact with your platform.

To manage recipients for a specific project, you can access the recipients tab of a specific project in the [orda developer portal](https://app.orda.network/)[.](https://app.orda.network/)

Creating an account generates a unique **client ID** specific to that account, which you'll use when sending funds or retrieving data associated with them through the API.

You can also update the account’s settlement details and deactivate recipients through the [dev porta](https://app.orda.network/)l.

**Overview**

* Recipients are used to identify **settlement destinations** for payments
* To create a recipient, you must first have created a project.
* You can update and deactivate recipients on the recipients page of a specific project.


# Creating a Recipient

This guide explains the purpose and general usage of the Create Recipient endpoint in the orda API.

#### Overview <a href="#overview" id="overview"></a>

You can create recipients associated to a project that can move money. Creating a recipient generates a unique ID specific to that recipient, which you'll use when sending funds to that recipient or retrieving data associated with them.

#### Authentication <a href="#authentication" id="authentication"></a>

To create recipients via the API, you must have a project **client ID** and **secret**. You can create a new project on the [*orda* developer portal](https://app.orda.network/)

You must sign each API request with a **HMAC signature** with an `x-signature` in the header, derived from your **client secret**. Refer to the [authentication guide](/developers/authentication) for more info on how to authenticate your requests.

#### Notes <a href="#notes" id="notes"></a>

To create a recipient, you must include the **settlement details** where the user can receive funds in **fiat currency and/or on-chain**. At least one of the following settlement details are required:

* Blockchain settlement information associated to the recipient (destination chain, token, wallet address)
* Fiat settlement information (KYB/KYC information, banking details)

The recipient will be associated with the project **client ID** provided in the request header as such:

| Header         | Description                                           |
| -------------- | ----------------------------------------------------- |
| `x-client-id`  | Your project's client ID                              |
| `x-signature`  | HMAC-SHA256 signature derived from your client secret |
| `Content-Type` | `application/json` for this request                   |

#### Common Issues <a href="#common-issues" id="common-issues"></a>

* Not signing the request with an `x-signature` derived from your client secret. Refer to the [authentication guide](/developers/authentication) for more info.
* Providing a token address or wallet address that is invalid or not compatible with the specified blockchain.

#### Next Steps <a href="#next-steps" id="next-steps"></a>

Once a recipient is created, you’ll receive a unique recipient ID for them in the response. This key should be securely stored and used when interacting with that recipient’s data or initiating payouts.

For implementation details, such as request format and sample code, refer to the [API reference.](https://orda.gitbook.io/orda-docs/api-reference/)


# Updating Recipient Details

You can update the details for any recipient associated with your project.

This is useful in cases where the settlement destination changes - such as when a vendor switches wallets or chooses to receive payouts on a different chain.

Example: *A marketplace user changes their preferred payout token from USDC on Base to ETH on mainnet.*

#### API Authentication <a href="#api-authentication" id="api-authentication"></a>

To update an recipient's settlement details via the API, you must authenticate your request using your **client ID** and **secret**. Specifically:

* Sign requests with the `x-signature` header derived from your client secret.
* Include your `x-client-id` in the headers.

Refer to the [authentication ](/developers/authentication)guide for help generating the correct signature.

#### Common Issues <a href="#common-issues" id="common-issues"></a>

* **Missing or invalid signature**: All API requests must be signed using your generated signature.
* **Invalid blockchain or token values**: Ensure the `toChain` and `toToken` correspond to supported networks and contract addresses.
* **Incorrect** `toAddress`: Make sure this wallet is valid and can receive the specified token on the chosen chain.

#### API Authentication <a href="#api-authentication" id="api-authentication"></a>

Updating settlement details is helpful when:

* A vendor updates their wallet for security reasons.
* A payout recipient wants to switch to a faster or cheaper chain.
* You need to correct setup mistakes from initial onboarding.


# Deactivating a Recipient

This guide explains how to deactivate a recipients using the orda API.

Deactivating a recipients ensures that the recipient no longer receives payouts or processes transactions. This is particularly useful when a recipient is no longer active or needs to be disabled for security or operational reasons.

#### Authentication <a href="#authentication" id="authentication"></a>

To deactivate a recipient, you must authenticate your request using your project’s **client ID** and **secret**. Each request must include:

* An `x-signature` header that is generated using your client secret.
* An `x-client-id` header containing your project’s client ID.

Refer to the [authentication guide](/developers/authentication) for detailed instructions on generating the correct signature.

#### Common Issues <a href="#common-issues" id="common-issues"></a>

* **Missing or Invalid Signature:** Ensure that every deactivation request is properly signed with an `x-signature` derived from your client secret.
* **Incorrect Recipient Identification:** Double-check that the recipient you are deactivating is the intended one to prevent accidental deactivation.
* **Mismatched Client ID:** Verify that the `x-client-id` provided in the request corresponds to the correct project.

#### When to use this endpoint <a href="#when-to-use-this-endpoint" id="when-to-use-this-endpoint"></a>

Deactivating a recipient is recommended when:

* An entity (such as a vendor or partner) no longer requires settlement services.
* Security or compliance reasons necessitate revoking a recipient’s ability to process payouts.
* You need to manage recipients’ activity through your administrative controls rather than manual intervention.

For implementation details, including the precise request format, please refer to the [API reference](https://orda.gitbook.io/orda-docs/api-reference/).


# Onchain Transactions

Crypto-to-Crypto Transactions (Swaps, Bridges, Transfers)

## Crypto-to-Crypto Transfers <a href="#crypto-to-crypto-transfers" id="crypto-to-crypto-transfers"></a>

This document describes the process for executing crypto-to-crypto transactions using the orda API. This involves requesting a price quote, executing the quoted transaction and monitoring its status until completion.

**Developer Portal**

While the core transaction flow (quote, execute, monitor) happens via the API, initial setup requires the [*orda* developer portal](https://app.orda.network/). You'll need:

* A **Project Client ID** and **Secret** for API authentication.
* A **Recipient Client ID** representing the entity receiving the transaction. Settlement details for the *destination* of the transaction are configured within the account settings in the portal.

**Overview**

* **Request a Quote:** Get pricing, fees, and transaction details before execution using the `/v1/quote` endpoint. Quotes are short-lived (approx. 30 seconds).
* **Execute the Quote:** After obtaining a valid quote, execute the transaction. This may involve a separate token approval step before the main transfer.
* **Monitor Status:** Track the progress of the transaction using the `/v1/status` endpoint with the `transactionId` from the quote response or transaction hashes.
* **Authentication:** All API requests require authentication using your project's client ID and a signature generated with your client secret. See the [authentication guide](/developers/authentication).


# Requesting a Quote

```plaintext
POST https://api.orda.network/v1/quote
```

This guide explains how to request a quote using the orda API. A quote request lets you execute a crypto-to-crypto transaction across any of our supported tokens and chains.

#### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

Before you start, make sure you have:

1. A project client id a project secret and your HMAC signature.
2. The details of the transaction you want to quote

#### Authentication <a href="#authentication" id="authentication"></a>

All API requests to orda require HMAC signatures using your project’s client ID and client secret. To authenticate your quote request:

* Generate an `x-signature` header using your client secret.
* Include your `x-client-id` in the request headers.

For detailed instructions on generating the signature, refer to our [Authentication Guide](https://docs.orda.network/version-11-alpha/guide/authentication).

**Required Headers**

| Header         | Description                                           |
| -------------- | ----------------------------------------------------- |
| `x-client-id`  | Your project's client ID                              |
| `x-signature`  | HMAC-SHA256 signature derived from your client secret |
| `Content-Type` | `application/json` for this request                   |

The signature is an HMAC-SHA256 hash of the request body, using your Client Secret as the key. Never share your Client Secret or include it directly in your client-side code.

#### What is a Quote Request? <a href="#what-is-a-quote-request" id="what-is-a-quote-request"></a>

A quote request enables you to obtain pricing information for a potential transaction before executing it. This is useful for:

1. Showing the user how much they'll pay before they commit
2. Understanding the current exchange rates and fees
3. Preparing the necessary transaction details

#### Requesting a quote <a href="#requesting-a-quote" id="requesting-a-quote"></a>

**Intent Specification:** The quote request uses an `intent` Object to specify the amount calculation method:

* `usd`: Calculate based on USD amount (10 = 10$)
* `fromAmount`: Calculate based on the source token amount
* `toAmount`: Calculate based on the destination token amount

`fromAmount` and `toAmount` Methods must be in the token's **smallest unit based on its decimal precision per token**:

* ETH: 18 decimals (1 ETH = 1e18 units)
* USDC: 6 decimals (1 USDC = 1e6 units)
* BTC: 8 decimals (1 BTC = 1e8 units)

**Examples:**

* Swap 2.5 ETH: `fromAmount: "2500000000000000000"` (2.5 × 10^18)
* Receive 1000 USDC: `toAmount: "1000000000"` (1000 × 10^6)

#### Implementation Notes <a href="#implementation-notes" id="implementation-notes"></a>

* Only one intent type should be specified per quote request
* The specified amount serves as the constraint, while other amounts are calculated
* Market conditions, slippage, and fees affect the calculated amounts
* Always validate that the calculated amounts meet your requirements before executing the swap

#### Best Practices <a href="#best-practices" id="best-practices"></a>

* Use `fromAmount` for liquidating existing positions
* Use `toAmount` for precise purchasing requirements
* Use `usd` for dollar-cost averaging or consistent value strategies<br>

**Important Notes:**

* No need to worry about filling in your own settlement details - we use the settlement information you provided within the [developer portal](https://app.orda.network/).
* The `fromChain` should be a valid chain ID. Refer to the Active Chains documentation for supported networks.
* The `fromToken` should be the token address on the source blockchain.
* The API uses rate limiting to prevent abuse.

**Additional Information:**

* **Quote Provider:** The response includes details from the selected quote provider (e.g., LiFi, Relay, Wormhole or internal routing).
* **Approval Transaction:** approvalTxParams is only present if token approval is required.
* **Chain IDs:** Refer to active chains documentation.
* **Gas Estimates:** Based on current network conditions and may change.
* **Quote Expiration:** Quotes have a limited validity period of approximately 30 seconds. It’s advisable to set up an automatic quote refresh system for users who haven’t completed their transactions within the 30 second timeframe.
* **Slippage:** The actual received amount may differ due to price fluctuations.
* **Cross-Chain Transfers:** For multi-chain transactions, additional monitoring steps may be required.
* **Response Variation:** Structure may vary slightly based on the selected provider and transfer type (direct or cross-chain).
* **Best Quote Selection:** The API automatically selects the most optimal quote from available providers.

**Common Issues**

* **Incorrect HMAC Signature:** Verify that your signature is calculated over the exact request body and generated with your client secret. Refer to the Authentication Guide for more info.
* **Stale Data:** Quotes are valid for only a short period, so ensure that you request new quotes if the user delays or changes transaction parameters.
* **Incomplete Request Data:** Make sure all required transaction details are provided to avoid errors in the quote calculation.


# Executing a Quote

After receiving a quote from the API, you'll need to handle the transaction execution process. This involves managing token approvals (if needed) and executing the main transfer transaction.

\
**How it works**

Quote execution follows a straightforward process:

1\. Receive and process the quote response

2\. Execute token approval transaction if required

3\. Execute the main transfer transaction

4\. Monitor transaction status until completion

**Prerequisites**

Before executing a quote, you need:

* A valid quote response from a previous call to `POST https://api.orda.network/v1.1/quote`
* The ability to sign blockchain transactions (via libraries such as ethers.js or web3.js)
* A connected wallet or key management system

\
The execution process involves two potential steps:

**Step 1: Handle Token Approval (if needed)**

If the quote response includes `approvalTxParams`, you must:

* Execute the approval transaction using the provided parameters
* Wait for the approval to be confirmed on the blockchain
* Handle any approval-related errors appropriately

**Step 2: Execute Main Transaction**

After handling any approval requirements:

* For Direct transfers, use `transferTxParams`
* For Provider transfers, use `transactionRequest`
* Wait for transaction confirmation
* Monitor the transaction status using the transaction ID

Here's a simplified example of the core implementation logic:

```typescript
// If approval is needed, execute it first and wait for confirmation
if (quote.approvalTxParams) {
const approvalTx = await sendTransaction(quote.approvalTxParams);
await waitForConfirmation(approvalTx);
}

// Execute the main transaction
const txParams = quote.type === 'Direct'
? quote.transferTxParams
: quote.transactionRequest;
const tx = await sendTransaction(txParams);

// Monitor status until completion
await monitorTransaction(quote.transactionId);
```

typescript

**Best Practices**

* Approval Handling
  * Always check for `approvalTxParams` before proceeding
  * Wait for approval confirmation before executing the main transfer
  * Handle approval failures appropriately
* Transaction Execution
  * Use proper gas estimation from the quote
  * Handle both direct and cross-chain transfers
  * Monitor transaction status until completion
* User Experience
  * Show clear loading states during transactions
  * Provide feedback during approval and transfer steps
  * Handle errors gracefully with user-friendly messages
* Security
  * Validate all transaction parameters
  * Never modify gas limits without proper estimation
  * Always wait for transaction confirmations

**Common issues**

* User interaction errors:
  * User rejection of transactions is a common occurrence. Implement proper error handling to detect when users decline to sign transactions and provide appropriate guidance.
* Blockchain-related errors:
  * **Insufficient funds**: Ensure users have enough native tokens for gas fees plus transaction amount
  * **Network congestion**: Consider implementing dynamic gas price strategies during high-

    congestion periods
  * **Failed transactions**: Parse error messages from the blockchain to provide useful feedback
* Integration issues:
  * **Quote expiration**: Ensure quotes are executed within their validity window
  * **Incorrect parameter handling**: Double-check parameter mapping, especially when dealing

    with hexadecimal values
  * **Status monitoring failures**: Implement proper retry logic for status monitoring

**Status Monitoring**

The transaction status can be one of:

`Pending` Transaction is in progress

`Completed` Transaction successfully completed

`Failed` Transaction failed

Learn more about Transaction Status endpoint[ ](https://docs.scalar.com/editor#/version-11-alpha/reference/tag/crypto-to-crypto/GET/status)[here](/developers/api/onchain-transactions/monitoring-status).

**Next steps**

After executing a quote, you can:

1\. Implement webhook notifications to receive real-time updates about transaction status

2\. Build a transaction history interface to show users their past transactions

3\. Integrate with the [Monitoring Status](/developers/api/onchain-transactions/monitoring-status) endpoint for detailed monitoring

For implementation details, request format examples, and additional sample code, refer to our API Reference.


# Monitoring Status

```plaintext
POST https://api.orda.network/v1/status
```

This guide explains how to check the status of a transaction using the orda API. Monitoring transaction status helps you provide users with real-time feedback on their transfers and handle retries, timeouts, or failures appropriately.

**API Authentication**

To check transaction status, all API requests must be authenticated using your project’s **client ID** and **client secret**. For GET requests with no body, use the string "{}" (canonical empty object) when generating your `x-signature`.

**Required headers:**

* `x-client-id`: Your project’s client ID
* `x-signature`: HMAC-SHA256 signature derived from your client secret

For more details, refer to the [authentication guide](/developers/authentication).

**Query Parameters**

To check a transaction’s status, you must provide at least one of the following query parameters:

* `transactionId`: The unique ID returned from the quote request
* `sourceHash`: The on-chain source transaction hash
* `destinationHash`: The hash of the cross-chain destination transaction (if applicable)

These values allow you to retrieve status updates whether you're working with internal transaction records or on-chain data.

**Common Issues**

* **Missing required query parameters**: At least one of `transactionId`, `sourceHash`, or `destinationHash` must be provided.
* **Incorrect HMAC signature**: For GET requests, the signature must be generated using the string "{}" (canonical empty object).
* **Outdated or invalid transaction ID**: Confirm the transaction ID you are checking was retrieved from a valid quote response.

**When to Use This Endpoint**

Use this endpoint to:

* Poll transaction status after initiating a quote and transfer
* Confirm settlement on-chain before updating your UI or backend
* Track long-running or cross-chain transfers that involve multiple steps

**Next Steps**

If the transaction is complete or has failed, you can inform the user and log the result. If the transaction is still pending, you may continue polling or set a timeout based on your business logic.

For implementation specifics, such as sample code and response formats, refer to the API Reference.


# Off Ramps

This document describes the process for executing crypto-to-fiat transactions using the orda API. This involves requesting a price quote, executing the quoted transaction, and monitoring its status until completion.

**Developer Portal**

While the core transaction flow (quote, execute, monitor) occurs via the API, the initial setup requires the [orda developer portal](https://app.orda.network/). You'll need:

* A **Project Client ID** and **Secret** for API authentication.
* A **Recipient Client ID** representing the entity receiving the transaction. Settlement details for the *destination* of the transaction are configured within the account settings in the portal.

**Overview**

* **Request a Quote:** Get pricing, fees, and transaction details before execution using the `/v1/offramp/quote` endpoint. Quotes are short-lived (approx. 30 seconds).
* **Execute the Quote:** After obtaining a valid quote, execute the transaction. This may involve a separate token approval step before the main transfer.
* **Monitor Status:** Track the progress of the transaction using the `/v1.1/offramp/status` endpoint with the `transactionId` from the quote response or transaction hashes.
* **Authentication:** All API requests require authentication using your project's client ID and a signature generated with your client secret. See the [authentication guide](/developers/authentication).


# Requesting a Quote

```plaintext
POST https://api.orda.network/v1/offramp/quote
```

This guide explains how to request a crypto-to-fiat quote using the orda API. A quote request allows you to get pricing information for converting cryptocurrency to fiat currency before actually executing the transaction. This is typically the first step in processing an off-ramp transaction.

**Prerequisites**

Before you start, make sure you have:

* A project **Client ID** and **Client Secret**. If you don't have credentials yet, you can register for them [here](https://app.orda.network/).
* The details of the transaction you want to quote (e.g., source crypto, target fiat, amount).

**Authentication**

All API requests to orda require an HMAC signature using your Client ID and Client Secret. To authenticate your quote request:

* Generate an `x-signature` header using your Client Secret and the request body.
* Include your `x-client-id` in the request headers.
* Set the `Content-Type` header to `application/json`.

For detailed instructions on generating the signature, refer to our [Authentication Guide](/developers/authentication). Remember to never share your Client Secret or include it directly in client-side code.

**Required Headers**

| Header         | Description                                           |
| -------------- | ----------------------------------------------------- |
| `x-client-id`  | Your project's client ID                              |
| `x-signature`  | HMAC-SHA256 signature derived from your client secret |
| `Content-Type` | `application/json` for this request                   |

**What is a Crypto-to-Fiat Quote Request?**

A crypto-to-fiat quote request allows you to get pricing information for converting cryptocurrency to fiat currency before actually executing the transaction. This is useful for:

* Showing the user how much they'll receive in fiat before they commit.
* Understanding the current exchange rates and fees involved.
* Preparing the necessary transaction details for execution.

**Requesting a Quote**

To request a quote, you'll typically provide information such as:

* The source blockchain ID (`fromChain)`.
* The specific cryptocurrency token being converted (`fromToken`).
* The source wallet address (`fromAddress`).
* The amount of crypto to send (`fromAmount`).
* The ID of the recipient (`recipientId`).

Or, instead of providing a `recipientId`, you can include the fiat settlement details (\`fiatSettlementDetails\`) and KYC/KYB information (\`kybInformation\`) in the request to create a new recipient upon quote execution. Refer to the Crypto-to-Fiat API reference for more information.

**High-Level Use Case:** This endpoint is particularly useful for platforms like marketplaces that need to pay out international vendors in their local fiat currency after receiving payment in cryptocurrency.

**Important Considerations & Common Issues**

* **Quote Expiration:** Quotes are valid for a limited time (often less than a minute) due to fluctuating exchange rates. Ensure you execute the transaction promptly after receiving a quote, or request a fresh quote if there's a delay. Consider implementing an automatic refresh mechanism for your users.
* **Authentication Errors:**
  * Double-check that your Client ID is correct and active.
  * Verify your signature calculation precisely matches the request body. Refer to the [Authentication Guide](/developers/authentication).
  * Ensure the request body hasn't changed between signature calculation and sending the request.
* **Incorrect Input:** Ensure you provide valid token addresses, currency codes, and correctly formatted amounts.
* **Recipient Information:** Accurate recipient name and tax details are crucial for compliance and successful payouts.


# Executing a Quote

After receiving a crypto-to-fiat quote using the Request Crypto-to-Fiat Quote guide, the next step is to execute the transaction. This guide explains the process and best practices for initiating the conversion and handling the subsequent steps.

**Prerequisites**

Before executing an off-ramp quote, ensure you have:

* A valid `transactionId` obtained from a recent quote request.
* Complete and verified recipient KYC information (name, tax ID, tax ID country).
* Accurate fiat withdrawal details for the recipient (e.g., bank account/branch, IBAN, PIX key depending on the region).
* Recipient's email address for notifications.
* Details about the source of the funds (chain ID, wallet address).

**Best Practices**

* **Quote Handling:**
  * Always use a fresh quote. Quotes expire quickly due to market volatility. Re-request a quote if there's a delay before execution.
  * Store the `transactionId` securely, as it links the execution request to the specific pricing agreed upon.
  * Clearly display the final fiat amount, exchange rate, and fees from the quote to the user before they confirm execution.
* **Execution Handling:**
  * Ensure all required KYC and bank details are accurate before submitting the execution request to prevent payout failures.
  * Provide a valid recipient email address for transaction status updates.
  * Securely store the `transactionId` returned upon successful execution initiation. This ID is crucial for tracking the transaction's progress.
* **User Experience:**
  * Clearly communicate the steps involved: quote confirmation, crypto deposit, fiat payout.
  * Provide estimated processing and payout times.
  * Offer a way for users to track the transaction status using the `transactionId`.
  * Handle potential errors (e.g., invalid bank details, expired quote) gracefully with clear, user-friendly messages.
* **Security:**
  * Continue to follow authentication best practices as outlined in the Authentication Guide.
  * Validate all user inputs server-side before making the API call.
  * Securely manage API credentials (Client ID and Secret).
  * Handle sensitive recipient data (KYC, bank info) securely and in compliance with relevant regulations.

**Error Handling**

Be prepared to handle potential errors during execution, such as:

* Invalid or expired `providerQuoteId`.
* Missing or incorrect KYC or bank information.
* Authentication failures.
* API rate limiting.
* Network issues or timeouts.
* Insufficient funds or issues during the crypto deposit step.

**Status Monitoring**

Once the execution is initiated, the transaction will progress through several stages. You can track its status using the `transactionId`. Common statuses include:

* `pending`: The transaction is initiated and awaiting crypto deposit or processing.
* `completed`: The fiat payout has been successfully processed.
* `failed`: The transaction could not be completed due to an error.

For detailed information on tracking the transaction lifecycle, see the Monitor Off-Ramp Status guide. (Note: Assumes this path exists or will be created)


# Monitoring Status

```
POST https://api.orda.network/v1/offramp/status
```

This guide explains how to check the status of a crypto-to-fiat (off-ramp) transaction using the orda API. Monitoring transaction status allows you to track the progress of a fiat payout, provide users with updates, and handle different outcomes like completion or failure.

**API Authentication**

To check transaction status, all API requests must be authenticated using your project’s **Client ID** and **Client Secret**.

**Required headers:**

* `x-client-id`: Your project’s Client ID
* `x-signature`: HMAC-SHA256 signature derived from your Client Secret

**Important Note:** For GET requests like this status check, which do not have a request body, you must generate the `x-signature` using the string "{}" (canonical empty object) as the content to be hashed.

For more details, refer to the main Authentication Guide.

**Query Parameters**

To check a specific off-ramp transaction’s status, you must provide the following query parameter:

* `referenceId`: The unique reference ID returned when the off-ramp order was initially created (during the execution step).

This ID allows the API to retrieve the current status and details of that specific transaction.

**Common Issues**

* **Missing** `referenceId`: Ensure the `referenceId` query parameter is included and correct.
* **Incorrect HMAC Signature**: Verify the signature is calculated correctly for a GET request using the string "{}" (canonical empty object) and uses the correct Client Secret. Refer to the Authentication Guide for troubleshooting.
* **Invalid** `referenceId`: Double-check that the `referenceId` corresponds to a valid, previously initiated off-ramp transaction.

**Transaction Statuses**

The API will return the current status of the transaction. Common statuses include:

* `pending`: The order is created, awaiting crypto deposit.
* `processing`: Crypto received, fiat conversion/payout is in progress.
* `completed`: Fiat payout successfully sent to the recipient.
* `failed`: The transaction failed (e.g., due to invalid bank details, compliance issues).
* `refunded`: The transaction was refunded.

**When to Use This Endpoint**

Use this endpoint to:

* Periodically poll the status after initiating an off-ramp execution.
* Confirm successful fiat payout before updating your system or notifying the user.
* Investigate the final state of transactions that are no longer pending.

**Next Steps**

Based on the status returned:

* **Pending/Processing**: Continue polling at reasonable intervals.
* **Completed**: Update your records, notify the user of success.
* **Failed/Refunded**: Investigate the reason (check response details if available), inform the user, and potentially initiate corrective action.

For implementation specifics, such as sample code and detailed response formats, refer to the [API reference](https://orda.gitbook.io/orda-docs/api-reference/).


# On Ramps


# Requesting a Quote

## Requesting a Fiat-to-Crypto Quote <a href="#requesting-a-fiat-to-crypto-quote" id="requesting-a-fiat-to-crypto-quote"></a>

### Overview <a href="#overview" id="overview"></a>

Request a quote to convert fiat currency into cryptocurrency. The quote endpoint provides real-time exchange rates and generates deposit instructions for the fiat payment.

### Endpoint <a href="#endpoint" id="endpoint"></a>

```
POST /v1/onramp/quote
```

### Authentication <a href="#authentication" id="authentication"></a>

Requires HMAC authentication headers:

* `x-client-id`: Your project's client ID
* `x-signature`: HMAC-SHA256 signature
* `x-timestamp`: Request timestamp (optional)

Check our [authentication](/developers/authentication) guide for more info.

### Request Parameters <a href="#request-parameters" id="request-parameters"></a>

#### Required Fields <a href="#required-fields" id="required-fields"></a>

| Parameter      | Type   | Description                                                                                                                |
| -------------- | ------ | -------------------------------------------------------------------------------------------------------------------------- |
| `fromCurrency` | string | Source fiat currency code (e.g., "BRL")                                                                                    |
| `intent`       | object | Defines the transaction amount and method                                                                                  |
| `taxId`        | string | Fiat payer's Brazilian tax ID: CPF (11 digits) or CNPJ (14 digits), digits only with no punctuation (e.g., "11144477735"). |
| `taxIdCountry` | string | ISO 3166-1 alpha-3 country code, uppercase (e.g., "BRA").                                                                  |
| `recipientId`  | string | UUID of the recipient to receive cryptocurrency                                                                            |

#### Intent Object <a href="#intent-object" id="intent-object"></a>

The intent object supports three methods to specify transaction amounts:

| Method       | Description                    | Value Format                                        | Example                                                                    |
| ------------ | ------------------------------ | --------------------------------------------------- | -------------------------------------------------------------------------- |
| `fromAmount` | Exact fiat amount to spend     | Decimal string representing fiat amount             | `{ "method": "fromAmount", "value": "500" }` means 500 BRL                 |
| `toAmount`   | Exact crypto amount to receive | String representing smallest units (wei-equivalent) | `{ "method": "toAmount", "value": "100000000000000000000" }` means 100 BRZ |
| `usd`        | USD value for conversion       | String representing smallest units (18 decimals)    | `{ "method": "usd", "value": "100000000000000000000" }` means $100 USD     |

**Important:**

* Fiat amounts (`fromAmount`) use standard decimal notation: `"500"` = 500 BRL
* Crypto amounts (`toAmount`) use smallest units based on token decimals: `"100000000000000000000"` = 100 tokens (18 decimals)
* USD amounts (`usd`) use 18 decimals like Ether: `"100000000000000000000"` = $100 USD

### Amount Formats <a href="#amount-formats" id="amount-formats"></a>

#### Understanding Smallest Units <a href="#understanding-smallest-units" id="understanding-smallest-units"></a>

Cryptocurrency amounts are represented in their smallest indivisible units (similar to wei for Ether):

**18-Decimal Tokens (BRZ on most chains):**

* 1 BRZ = 1000000000000000000 smallest units
* Formula: `smallest_units = amount × 10^18`

**6-Decimal Tokens (USDC, USDT):**

* 1 USDC = 1000000 smallest units
* Formula: `smallest_units = amount × 10^6`

#### Conversion Examples <a href="#conversion-examples" id="conversion-examples"></a>

{% tabs %}
{% tab title="Ethers" %}

```javascript
import { ethers } from 'ethers';

// For 18-decimal tokens (BRZ)
const toSmallestUnits = ethers.parseUnits("100", 18);  // "100000000000000000000"
const fromSmallestUnits = ethers.formatUnits("100000000000000000000", 18);  // "100.0"

// For USD values (always 18 decimals)
const usdInSmallestUnits = ethers.parseUnits("100", 18);  // "100000000000000000000"
```

{% endtab %}

{% tab title="  Web3.js" %}

```javascript
import Web3 from 'web3';
const web3 = new Web3();

// For 18-decimal tokens
const toSmallestUnits = web3.utils.toWei("100", "ether");  // "100000000000000000000"
const fromSmallestUnits = web3.utils.fromWei("100000000000000000000", "ether");  // "100"

// For 6-decimal tokens
const toSmallestUnits = web3.utils.toWei("100", "mwei");  // "100000000"
```

{% endtab %}
{% endtabs %}

### Request Examples <a href="#request-examples" id="request-examples"></a>

{% tabs %}
{% tab title="Fiat Amount (BRL)" %}

```bash
curl -X POST https://api.orda.network/v1/onramp/quote \
  -H "Content-Type: application/json" \
  -H "x-client-id: your-client-id" \
  -H "x-signature: your-signature" \
  -H "x-timestamp: 1234567890" \
  -d '{
    "fromCurrency": "BRL",
    "intent": {
      "method": "fromAmount",
      "value": "500"
    },
    "taxId": "11144477735",
    "taxIdCountry": "BRA",
    "recipientId": "123e4567-e89b-12d3-a456-426614174000"
  }'
```

{% endtab %}

{% tab title="Crypto Amount" %}

```bash
curl -X POST https://api.orda.network/v1/onramp/quote \
  -H "Content-Type: application/json" \
  -H "x-client-id: your-client-id" \
  -H "x-signature: your-signature" \
  -H "x-timestamp: 1234567890" \
  -d '{
    "fromCurrency": "BRL",
    "intent": {
      "method": "toAmount",
      "value": "100000000000000000000"
    },
    "taxId": "11144477735",
    "taxIdCountry": "BRA",
    "recipientId": "123e4567-e89b-12d3-a456-426614174000"
  }'
```

**Note:** The value `"100000000000000000000"` represents 100 BRZ in smallest units (18 decimals).
{% endtab %}

{% tab title="USD Value" %}

```bash
curl -X POST https://api.orda.network/v1/onramp/quote \
  -H "Content-Type: application/json" \
  -H "x-client-id: your-client-id" \
  -H "x-signature: your-signature" \
  -H "x-timestamp: 1234567890" \
  -d '{
    "fromCurrency": "BRL",
    "intent": {
      "method": "usd",
      "value": "100"
    },
    "taxId": "11144477735",
    "taxIdCountry": "BRA",
    "recipientId": "123e4567-e89b-12d3-a456-426614174000"
  }'
```

{% endtab %}
{% endtabs %}

### Implementation Notes <a href="#implementation-notes" id="implementation-notes"></a>

#### Recipient Requirements <a href="#recipient-requirements" id="recipient-requirements"></a>

* Recipient must exist and belong to your project
* Must have crypto settlement details configured:
  * `toChain`: Target blockchain ID
  * `toToken`: Token contract address
  * `toAddress`: Wallet address for delivery

#### Quote Expiration <a href="#quote-expiration" id="quote-expiration"></a>

* Quotes typically expire after 5-10 minutes
* Check `expiresAt` field for exact expiration time
* Execute deposit before expiration to lock in rate

#### Rate Calculation <a href="#rate-calculation" id="rate-calculation"></a>

* Exchange rates include all fees
* No hidden charges or additional fees
* Rate is guaranteed once deposit is made

#### Current Flow Limitation

At present, all BRL on-ramp flows are routed through **BRZ** as an intermediate step:

* **Now:** `BRL → BRZ → Target Asset (e.g. USDC, ETH, AUSD)`
* **Future:** `BRL → Target Asset` (direct)

This means:

* When configuring a recipient, you must first enable **BRZ** settlement.
* Additional conversions (BRZ → USDC, ETH, etc.) are handled automatically, but they add one extra step in the flow.

{% hint style="warning" %}
⚠️ **Note:** Direct BRL → asset settlement is in development. Once live, you’ll be able to on-ramp directly into USDC, ETH or other supported tokens with a single transaction.
{% endhint %}

### Next Steps <a href="#next-steps" id="next-steps"></a>

After receiving a quote:

1. Display deposit instructions to user
2. For PIX: Show QR code or copy PIX key
3. Monitor payment status
4. [Execute the quote](/developers/api/on-ramps/executing-a-quote) by completing deposit
5. [Track transaction status](/developers/api/on-ramps/monitoring-status)


# Executing a Quote

## Executing a Fiat-to-Crypto Quote <a href="#executing-a-fiat-to-crypto-quote" id="executing-a-fiat-to-crypto-quote"></a>

### Overview <a href="#overview" id="overview"></a>

After requesting a quote, execute it by completing the fiat deposit using the provided payment instructions. The system automatically processes the payment and delivers cryptocurrency to the recipient's wallet.

### Payment Methods <a href="#payment-methods" id="payment-methods"></a>

#### PIX (Brazilian Real - BRL) <a href="#pix-brazilian-real---brl" id="pix-brazilian-real---brl"></a>

PIX is Brazil's instant payment system, available 24/7 for fast transfers.

**Payment Options**

1. **QR Code Payment**
   * Scan the QR code using your banking app
   * Confirm the payment details
   * Authorize the transfer
2. **PIX Key Copy & Paste**
   * Copy the PIX key string
   * Paste in your banking app's PIX section
   * Confirm and send payment

### Deposit Instructions <a href="#deposit-instructions" id="deposit-instructions"></a>

The quote response includes all necessary payment details:

```json
{
  "depositInstructions": {
    "method": "PIX",
    "amount": "527.50",
    "currency": "BRL",
    "pixQrCode": "data:image/png;base64,iVBORw0KGgoAAAANS...",
    "pixKey": "00020126580014br.gov.bcb.pix...",
    "expiresAt": "2024-01-15T10:30:00Z",
    "referenceId": "REF123456789"
  }
}
```

### Implementation Guide <a href="#implementation-guide" id="implementation-guide"></a>

#### Step 1: Display Payment Instructions <a href="#step-1-display-payment-instructions" id="step-1-display-payment-instructions"></a>

```javascript
// Example: Display PIX QR Code
function displayPaymentInstructions(depositInstructions) {
  if (depositInstructions.method === 'PIX') {
    // Show QR code image
    const qrImage = document.getElementById('qr-code');
    qrImage.src = depositInstructions.pixQrCode;
    
    // Show PIX key for copy
    const pixKeyElement = document.getElementById('pix-key');
    pixKeyElement.textContent = depositInstructions.pixKey;
    
    // Display amount
    const amountElement = document.getElementById('amount');
    amountElement.textContent = `${depositInstructions.currency} ${depositInstructions.amount}`;
    
    // Show expiration timer
    startExpirationTimer(depositInstructions.expiresAt);
  }
}
```

#### Step 2: Handle User Payment <a href="#step-2-handle-user-payment" id="step-2-handle-user-payment"></a>

```javascript
// Example: Copy PIX key to clipboard
function copyPixKey(pixKey) {
  navigator.clipboard.writeText(pixKey).then(() => {
    showNotification('PIX key copied to clipboard');
  });
}

// Example: Provide payment instructions
function showPaymentSteps() {
  const steps = [
    "1. Open your banking app",
    "2. Go to PIX section",
    "3. Select 'Pay with QR Code' or 'Pay with PIX Key'",
    "4. Scan the QR code or paste the PIX key",
    "5. Confirm the amount matches exactly",
    "6. Authorize the payment"
  ];
  
  displaySteps(steps);
}
```

#### Step 3: Monitor Payment Status <a href="#step-3-monitor-payment-status" id="step-3-monitor-payment-status"></a>

After initiating payment, monitor the transaction status:

```javascript
// Example: Poll for status updates
async function monitorPayment(transactionId) {
  const interval = setInterval(async () => {
    const status = await checkTransactionStatus(transactionId);
    
    updateUI(status);
    
    if (status.status === 'Completed' || status.status === 'Failed') {
      clearInterval(interval);
      handleFinalStatus(status);
    }
  }, 5000); // Check every 5 seconds
}
```

### Payment Processing Flow <a href="#payment-processing-flow" id="payment-processing-flow"></a>

<figure><img src="https://2927719792-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGNZX42boT5K8BnIz27Gl%2Fuploads%2F2o3TaRSVZAzInquyXFoH%2Fimage.png?alt=media&amp;token=a8e7d459-d679-4809-ae59-ba87f93b0f5a" alt=""><figcaption></figcaption></figure>

### Important Considerations <a href="#important-considerations" id="important-considerations"></a>

#### Timing <a href="#timing" id="timing"></a>

* **Quote Expiration**: Complete payment before quote expires (check `expiresAt` timestamp)
* **Processing Time**:
  * PIX confirmation: Typically within seconds
  * Crypto delivery: Estimated 60 seconds after payment confirmation
  * Total estimated duration: \~1-2 minutes from payment to crypto delivery
* **Availability**: PIX available 24/7, including weekends and holidays

#### Security <a href="#security" id="security"></a>

* **Verify Details**: Always verify payment amount and recipient
* **Official Apps Only**: Use official banking apps for payments
* **Save Reference**: Keep the transaction ID and reference ID

### Common Scenarios <a href="#common-scenarios" id="common-scenarios"></a>

#### Successful Payment <a href="#successful-payment" id="successful-payment"></a>

1. User completes PIX payment
2. System detects payment within seconds
3. Automatic conversion to cryptocurrency
4. Crypto sent to recipient's wallet
5. Transaction marked as completed

#### Payment Issues <a href="#payment-issues" id="payment-issues"></a>

**Quote Expired**

* Request a new quote if payment wasn't made in time
* New quote may have different exchange rate

**Incorrect Amount**

* Contact support if wrong amount was sent
* May require manual processing or refund

**Payment Not Detected**

* Allow 5-10 minutes for processing
* Check transaction status endpoint
* Contact support with reference ID if not processed

### Transaction Status <a href="#transaction-status" id="transaction-status"></a>

During execution, monitor the transaction status using the [status endpoint](/developers/api/on-ramps/monitoring-status):

| Status        | Description                                             |
| ------------- | ------------------------------------------------------- |
| `In_progress` | Payment pending, received, or being processed           |
| `Completed`   | Cryptocurrency successfully delivered to wallet         |
| `Failed`      | Payment failed, rejected, or transaction error occurred |

**Note:** These are high-level status categories. The underlying payment and blockchain operations may go through multiple intermediate states before reaching a final status.

### Best Practices <a href="#best-practices" id="best-practices"></a>

1. **Clear Instructions**: Provide step-by-step payment guidance
2. **Visual Feedback**: Show QR code prominently for PIX
3. **Copy Functionality**: Enable one-click copy for PIX key
4. **Timer Display**: Show countdown for quote expiration
5. **Status Updates**: Provide real-time payment status
6. **Error Recovery**: Guide users through error scenarios
7. **Support Access**: Provide easy access to support

### Next Steps <a href="#next-steps" id="next-steps"></a>

After executing the payment:

* [Monitor transaction status](/developers/api/on-ramps/monitoring-status)
* Handle success/failure scenarios
* Provide transaction receipt to user


# Monitoring Status

## Monitoring Status <a href="#monitoring-status" id="monitoring-status"></a>

```
GET https://api.orda.network/v1/onramp/status
```

This guide explains how to check the status of a fiat-to-crypto (on-ramp) transaction using the orda API. Monitoring transaction status allows you to track the progress from payment initiation through cryptocurrency delivery, provide users with updates, and handle different outcomes like completion or failure.

**API Authentication**

To check transaction status, all API requests must be authenticated using your project's **Client ID** and **Client Secret**.

**Required headers:**

* `x-client-id`: Your project's Client ID
* `x-signature`: HMAC-SHA256 signature derived from your Client Secret

**Important Note:** For GET requests like this status check, which do not have a request body, you must generate the `x-signature` using the string "{}" (canonical empty object) as the content to be hashed.

For more details, refer to the main [Authentication Guide](/developers/authentication).

**Query Parameters**

To check a specific on-ramp transaction's status, you must provide the following query parameter:

* `transactionId`: The unique transaction ID returned when the on-ramp quote was initially created.

This ID allows the API to retrieve the current status and details of that specific transaction.

**Common Issues**

* **Missing** `transactionId`: Ensure the `transactionId` query parameter is included and correct.
* **Incorrect HMAC Signature**: Verify the signature is calculated correctly for a GET request using the string "{}" (canonical empty object) and uses the correct Client Secret. Refer to the [Authentication Guide](/developers/authentication) for troubleshooting.
* **Invalid** `transactionId`: Double-check that the `transactionId` corresponds to a valid, previously initiated on-ramp transaction.

**Transaction Statuses**

The API will return the current status of the transaction. Common statuses include:

* `In_progress`: Payment pending or being processed, crypto conversion in progress.
* `Completed`: Cryptocurrency successfully delivered to recipient's wallet.
* `Failed`: The transaction failed (e.g., due to payment timeout, expired quote, invalid recipient details).

**When to Use This Endpoint**

Use this endpoint to:

* Periodically poll the status after the user initiates a PIX payment.
* Confirm successful crypto delivery before updating your system or notifying the user.
* Investigate the final state of transactions that are no longer pending.

**Next Steps**

Based on the status returned:

* **In\_progress**: Continue polling at reasonable intervals (e.g., every 5 seconds initially, then less frequently).
* **Completed**: Update your records, notify the user of success, display transaction receipt.
* **Failed**: Investigate the reason (check response details if available), inform the user, and potentially initiate corrective action or request a new quote.

For implementation specifics, such as sample code and detailed response formats, refer to the [API reference](broken://spaces/Pej4zM9TIFz5NZwMgGdT).


# SDK

## Quick Start

Install the package

{% tabs %}
{% tab title="npm" %}

```bash
npm install @ordanetwork/sdk
```

{% endtab %}

{% tab title="pnpm" %}

```bash
pnpm add @ordanetwork/sdk
```

{% endtab %}

{% tab title="yarn" %}

```bash
yarn add @ordanetwork/sdk
```

{% endtab %}
{% endtabs %}

**Requirements:** Node.js 18.0.0+

### Initialize SDK

```typescript
import { OrdaSDK } from '@ordanetwork/sdk';

const orda = new OrdaSDK({
  clientId: process.env.ORDA_CLIENT_ID,
  clientSecret: process.env.ORDA_CLIENT_SECRET
});
```

Visit the [orda developer portal](https://app.orda.network/) to create a project and manage API keys.

### Bridge & Swap

```typescript
const quote = await orda.quote.request({
  fromChain: '8453', // Base
  fromToken: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913', // USDC on Base
  fromAddress: '0xYourAddress',
  intent: {
    method: 'fromAmount',
    value: '1000000' // 1 USDC (6 decimals)
  },
  settlementDetails: {
    toChain: '42161', // Arbitrum One
    toToken: '0xdAC17F958D2ee523a2206206994597C13D831ec7', // USDT on Arbitrum
    toAddress: '0xRecipientAddress'
  }
})
```

This requests a quote to send **USDC from Base to USDT on Arbitrum**. orda will return the best path, including fees and expected settlement time.

{% hint style="info" %}
"Looking for a ready-to-embed React UI? See [Widget](/developers/widget)."
{% endhint %}

### Dependencies

* `@aa-sdk/core`
* `@account-kit/core`
* `@account-kit/infra`
* `@account-kit/smart-contracts`
* `viem`

### License

MIT


# Getting Started

### Creating a Project

Access our [Dev Portal](https://app.orda.network/) and create a project for your organization. You will be given the **Client ID** and **Client Secret** for authentication.

### Installation

{% tabs %}
{% tab title="npm" %}

```bash
npm install @ordanetwork/sdk
```

{% endtab %}

{% tab title="pnpm" %}

```bash
pnpm add @ordanetwork/sdk
```

{% endtab %}

{% tab title="yarn" %}

```bash
yarn add @ordanetwork/sdk
```

{% endtab %}
{% endtabs %}

**Requirements:** Node.js 18.0.0+

### Initialize SDK

```typescript
import { OrdaSDK } from '@ordanetwork/sdk';

const orda = new OrdaSDK({
  clientId: process.env.ORDA_CLIENT_ID,
  clientSecret: process.env.ORDA_CLIENT_SECRET
});
```

### Module Formats

The orda SDK is compatible with ES Modules and CommonJS:

{% tabs %}
{% tab title="ES Modules" %}

<pre class="language-typescript"><code class="lang-typescript"><strong>import { OrdaSDK } from '@ordanetwork/sdk';
</strong></code></pre>

{% endtab %}

{% tab title="CommonJS" %}

```javascript
const { OrdaSDK } = require('@ordanetwork/sdk');
```

{% endtab %}
{% endtabs %}

### Security

{% hint style="warning" %}
⚠️ Never expose credentials in frontend code. Always use environment variables on your backend server.

Example (backend):

{% code title="Backend initialization" %}

```javascript
const orda = new OrdaSDK({
  clientId: process.env.ORDA_CLIENT_ID,
  clientSecret: process.env.ORDA_CLIENT_SECRET
});
```

{% endcode %}
{% endhint %}


# Creating a Recipient (optional)

Recipients define where funds should be sent. Create one with crypto settlement, fiat settlement, or both.

## Crypto Recipient with Smart Wallet

Omit `toAddress` to auto-generate a [smart wallet](broken://pages/c4efdd11521fcd4dd3465e8438be6731c84e3551):

{% code title="TypeScript" %}

```typescript
const recipient = await orda.recipients.create({
  name: 'Alice',
  cryptoSettlementDetails: {
    toChain: '8453',  // Base
    toToken: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'  // USDC
  }
});

console.log(recipient.smartWallet?.address);
```

{% endcode %}

## Crypto Recipient with Specific Address

{% code title="TypeScript" %}

```typescript
const recipient = await orda.recipients.create({
  name: 'Bob',
  cryptoSettlementDetails: {
    toChain: '8453',
    toToken: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
    toAddress: '0xYourRecipientAddress'
  }
});
```

{% endcode %}

## Fiat Recipient (for Off-Ramp)

{% code title="TypeScript" %}

```typescript
const recipient = await orda.recipients.create({
  name: 'Carlos',
  fiatSettlementDetails: {
    toCurrency: 'BRL',
    pixKey: 'user@example.com'
  },
  kycInformation: {
    taxId: '12345678901',
    taxIdCountry: 'BRA',
    email: 'user@example.com',
    name: 'Carlos Silva'
  }
});
```

{% endcode %}

## Update Recipient

{% code title="TypeScript" %}

```typescript
await orda.recipients.updateSettlement({
  recipientId: 'recipient-id',
  cryptoSettlementDetails: {
    toChain: '1',
    toToken: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
  }
});
```

{% endcode %}

## Deactivate Recipient

{% code title="TypeScript" %}

```typescript
await orda.recipients.deactivate({
  recipientId: 'recipient-id'
});
```

{% endcode %}


# Bridge/Swap

Request quotes for crypto transfers with flexible intent methods.

## Requesting a quote

You can request a quote using an existing recipient ID or by passing the settlement details directly in the payload.

{% tabs %}
{% tab title="Using Recipient ID" %}
{% code title="example.ts" %}

```typescript
const quote = await orda.quote.request({
  fromChain: '1',  // Ethereum
  fromToken: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',  // USDC
  fromAddress: '0xYourAddress',
  intent: {
    method: 'usd',
    value: '100'
  },
  recipientId: 'recipient-id'
});
```

{% endcode %}
{% endtab %}

{% tab title="Using Inline Settlement" %}
{% code title="example.ts" %}

```typescript
const quote = await orda.quote.request({
  fromChain: '1',
  fromToken: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  fromAddress: '0xYourAddress',
  intent: {
    method: 'fromAmount',
    value: '1000000'  // 1 USDC (6 decimals)
  },
  settlementDetails: {
    toChain: '8453',
    toToken: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
    toAddress: '0xRecipientAddress'
  }
});
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Intent Methods

Use one of these intent methods to specify the quote intent.

{% tabs %}
{% tab title="USD Value" %}

```typescript
{ method: 'usd', value: '100' }  // $100 worth
```

{% endtab %}

{% tab title="From Amount" %}

```typescript
{ method: 'fromAmount', value: '1000000' }  // Exact input amount
```

The intent value when using `fromAmount` must be in smallest units (e.g. for USDC with 6 decimals: 100000 = 1 USDC)
{% endtab %}

{% tab title="To Amount" %}

```typescript
{ method: 'toAmount', value: '1000000' }  // Exact output amount
```

The intent value when using `toAmount` must be in smallest units (e.g. for USDC with 6 decimals: 100000 = 1 USDC)
{% endtab %}
{% endtabs %}


# Off Ramp Quote

{% stepper %}
{% step %}

### Request Quote

You can request a quote using an existing recipient ID or by passing the settlement details directly in the payload.

{% tabs %}
{% tab title="Request Quote (with recipient)" %}

```typescript
const quote = await orda.offRamp.requestQuote({
  fromChain: '8453',  // Base
  fromToken: '0xE9185Ee218cae427aF7B9764A011bb89FeA761B4',  // BRZ
  fromAddress: '0xYourAddress',
  intent: {
    method: 'fromAmount',
    value: '10000000000000000000'  // 10 BRZ
  },
  recipientId: 'recipient-id'
});
```

{% endtab %}

{% tab title="Request Quote (inline settlement)" %}

```typescript
const quote = await orda.offRamp.requestQuote({
  fromChain: '8453',
  fromToken: '0xE9185Ee218cae427aF7B9764A011bb89FeA761B4',
  fromAddress: '0xYourAddress',
  intent: {
    method: 'usd',
    value: '100'
  },
  kycInformation: {
    taxId: '12345678901',
    taxIdCountry: 'BRA',
    email: 'user@example.com',
    name: 'User Name'
  },
  fiatSettlementDetails: {
    toCurrency: 'BRL',
    pixKey: 'user@example.com'
  }
});
```

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

### Get Status

```typescript
const status = await orda.offRamp.getStatus(quote.transactionId);
console.log(status.status);  // 'Pending', 'Completed', 'Failed', etc.
```

{% endstep %}

{% step %}

### Wait for Completion

```typescript
await orda.offRamp.waitForCompletion(quote.transactionId, {
  intervalMs: 10000,
  timeoutMs: 1800000,
  onStatusUpdate: (status) => console.log('Status:', status)
});
```

{% endstep %}
{% endstepper %}

{% hint style="info" %}
Terminal statuses:

* Completed — Transfer successful
* Failed — Transfer failed
* Refunded — Funds returned
  {% endhint %}


# On Ramp Quote

Convert fiat currency to cryptocurrency (e.g., BRL to BRZ via PIX).

**Note:** we currently only support BRL → BRZ on ramps at the moment.

## Request a Quote

You can request a quote using an existing recipient ID or by passing the settlement details directly in the payload.

{% tabs %}
{% tab title="Using Recipient ID" %}
{% code title="TypeScript" %}

```typescript
const quote = await orda.onRamp.requestQuote({
  fromCurrency: 'BRL',
  intent: {
    method: 'fromAmount',
    value: '100.00'
  },
  taxId: '11144477735',
  taxIdCountry: 'BRA',
  recipientId: 'recipient-id'
});

console.log('PIX Key:', quote.depositInstructions.pixKey);
console.log('Transaction ID:', quote.transactionId);
```

{% endcode %}
{% endtab %}

{% tab title="Using Inline Settlement" %}
{% code title="TypeScript" %}

```typescript
const quote = await orda.onRamp.requestQuote({
  fromCurrency: 'BRL',
  intent: {
    method: 'usd',
    value: '100'
  },
  taxId: '11144477735',
  taxIdCountry: 'BRA',
  settlementDetails: {
    toChain: '8453',
    toToken: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
    toAddress: '0xRecipientAddress'
  }
});
```

{% endcode %}
{% endtab %}
{% endtabs %}

**Note:** `taxId` and `taxIdCountry` are required on every on-ramp quote. `taxId` is the fiat payer's Brazilian tax ID (CPF with 11 digits or CNPJ with 14 digits, digits only with no punctuation) and `taxIdCountry` is the ISO 3166-1 alpha-3 country code in uppercase (for example, "BRA").

## Deposit Instructions

The quote response includes PIX deposit details and a QR code formatted in Base64.

{% code title="Response (JSON)" %}

```json
{
  "transactionId": "tx-id",
  "depositInstructions": {
    "pixKey": "pix@orda.network",
    "pixKeyType": "EMAIL",
    "amount": "100.00",
    "currency": "BRL"
  }
}
```

{% endcode %}

## Get Status

{% code title="TypeScript" %}

```typescript
const status = await orda.onRamp.getStatus(quote.transactionId);
console.log(status.status);  // 'AwaitingDeposit', 'Processing', 'Completed', etc.
```

{% endcode %}

## Wait for Completion

{% code title="TypeScript" %}

```typescript
await orda.onRamp.waitForCompletion(quote.transactionId, {
  intervalMs: 15000,
  timeoutMs: 3600000,
  onStatusUpdate: (status) => console.log('Status:', status)
});
```

{% endcode %}

## Terminal Statuses

<details>

<summary>Possible terminal statuses</summary>

* Completed - Crypto received
* Failed - Transfer failed
* Cancelled - Transfer cancelled
* Refunded - Fiat returned

</details>


# Monitoring Transactions

Track transaction status using multiple methods.

## Get Transaction Status

Query by transaction ID, source hash, or destination hash:

{% code title="example.ts" %}

```typescript
// By transaction ID
const status = await orda.transactions.getStatus({
  transactionId: 'tx-id'
});

// By source hash
const status = await orda.transactions.getStatus({
  sourceHash: '0xabcd...'
});

// By destination hash
const status = await orda.transactions.getStatus({
  destinationHash: '0x1234...'
});
```

{% endcode %}

## Status Response

{% code title="response.ts" %}

```typescript
{
  transaction: {
    transactionId: 'tx-id',
    status: 'COMPLETED',
    fromChain: '1',
    toChain: '8453',
    sourceHash: '0xabcd...',
    destinationHash: '0x1234...',
    ...
  }
}
```

{% endcode %}

## Wait for Completion

Poll automatically until a terminal status:

{% code title="example.ts" %}

```typescript
await orda.transactions.waitForCompletion('tx-id', {
  intervalMs: 5000,      // Poll every 5 seconds
  timeoutMs: 600000,     // Timeout after 10 minutes
  onStatusUpdate: (status) => {
    console.log('Current status:', status);
  }
});
```

{% endcode %}

{% hint style="info" %}
The waitForCompletion helper will poll the transaction status at the supplied interval and call onStatusUpdate with intermediate updates. If a terminal status is reached or the timeout expires, the promise resolves/rejects accordingly.
{% endhint %}

## Get Successful Transactions

Retrieve all successful transactions:

{% code title="example.ts" %}

```typescript
const transactions = await orda.transactions.getSuccessfulTransactions();
```

{% endcode %}

## Transaction Statuses

{% columns %}
{% column %}

#### Active

* PENDING — Initiated
* PROCESSING — In progress
* WAITING\_FOR\_DEPOSIT — Awaiting funds
  {% endcolumn %}

{% column %}

#### Terminal

* COMPLETED — Success
* FAILED — Failed
* CANCELLED — Cancelled
* REFUNDED — Refunded
  {% endcolumn %}
  {% endcolumns %}

## Error Handling

{% code title="example.ts" %}

```typescript
try {
  const status = await orda.transactions.getStatus({ transactionId: 'tx-id' });
} catch (error) {
  if (error instanceof OrdaError) {
    console.error('Status:', error.statusCode);
    console.error('Code:', error.code);
    console.error('Details:', error.details);
  }
}
```

{% endcode %}

{% hint style="warning" %}
Inspect error.statusCode, error.code, and error.details when catching OrdaError to determine the cause and handle it appropriately.
{% endhint %}


# Widget

The orda Widget is a comprehensive, embeddable React component that enables\
multi-chain cryptocurrency payments in your application — swap, on-ramp, and\
off-ramp flows with built-in wallet connection, all wrapped around the orda\
TypeScript SDK.

{% hint style="info" %}
**Replaces the old `/developers/widget-beta` page.** The widget moved out of `@ordanetwork/sdk/react` (deleted in the SDK v2 release) into its own package **`@ordanetwork/widget@1.0.0`**. If you were on the beta, see Migrating from `@ordanetwork/sdk/react` at the bottom.Try the [widget →](https://widget.orda.network/)
{% endhint %}

### What it does

* **Multi-chain support** — EVM (Ethereum, Polygon, Arbitrum, Base, Optimism, plus plasma / stable / megaeth) and Solana
* **Three transaction flows** — Swap, Off-ramp (crypto → BRL via PIX), On-ramp (BRL → crypto via PIX)
* **Wallet integration** — WalletConnect / Reown AppKit modal mounted for you
* **Lifecycle callbacks** — 10 typed events for quote / transaction / wallet / error, plus a firehose for analytics
* **Recipient management** — save and manage payment recipients
* **Token prices & balances** — real-time USD prices and multi-chain balance fetching
* **Responsive UI** — desktop and mobile
* **Customizable theming** — CSS variables

### Prerequisites

1. WalletConnect / Reown project id — [cloud.reown.com](https://cloud.reown.com/)
2. orda API credentials — `clientId` and `clientSecret`
3. React 18 or React 19
4. Node.js 18+

### Installation

```bash
npm install @ordanetwork/widget @ordanetwork/sdk
# peers (you almost certainly have most of these already)
npm install react react-dom @tanstack/react-query wagmi viem
```

#### Version compatibility

| Package                 | Version                |
| ----------------------- | ---------------------- |
| `@ordanetwork/widget`   | `^1.0.0`               |
| `@ordanetwork/sdk`      | `^1.3.0 \|\| ^2.0.0`   |
| `react`                 | `^18.0.0 \|\| ^19.0.0` |
| `react-dom`             | `^18.0.0 \|\| ^19.0.0` |
| `@tanstack/react-query` | `^5.0.0`               |
| `wagmi`                 | `^2.0.0`               |
| `viem`                  | `^2.0.0`               |

`@solana/web3.js`, `@reown/appkit*`, and the radix-ui primitives are direct dependencies of `@ordanetwork/widget` — you don't need to install them yourself.

### Quick start

#### Step 1 — Set environment variables (`.env.local`)

```bash
NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID=your_walletconnect_project_id
ORDA_CLIENT_ID=prj_your_client_id
ORDA_CLIENT_SECRET=sec_your_client_secret
```

#### Step 2 — Create the JWT auth route (`app/api/auth/jwt/route.ts`)

The widget calls `config.getToken()` to obtain a JWT; you handle credential exchange server-side so the secret never reaches the browser.

```ts
import { NextResponse } from 'next/server';
import { UniversalHttpClient, JWT } from '@ordanetwork/sdk';

const CLIENT_ID = process.env.ORDA_CLIENT_ID!;
const CLIENT_SECRET = process.env.ORDA_CLIENT_SECRET!;
const API_URL = process.env.NEXT_PUBLIC_ORDA_API_BASE_URL || 'https://api.orda.network/v1';

export async function POST() {
  try {
    if (!CLIENT_ID || !CLIENT_SECRET) {
      return NextResponse.json(
        { error: 'Server configuration error: missing API credentials' },
        { status: 500 },
      );
    }

    const http = new UniversalHttpClient(API_URL, 30_000);
    const jwt = new JWT(http);

    const { token, expiresAt } = await jwt.generate({
      clientId: CLIENT_ID,
      clientSecret: CLIENT_SECRET,
      permissions: [
        'quotes:read',
        'offramp:read',
        'onramp:read',
        'transactions:read',
        'recipients:read',
        'recipients:write',
        'balances:read',
        'prices:read',
      ],
    });

    return NextResponse.json({
      jwt: token,
      expiresAt: Math.floor(new Date(expiresAt).getTime() / 1000),
    });
  } catch (err: any) {
    return NextResponse.json(
      { error: err?.message ?? 'Failed to generate token' },
      { status: err?.statusCode ?? 500 },
    );
  }
}
```

#### Step 3 — Create the provider (`app/providers.tsx`)

```tsx
'use client';

import { OrdaProvider, createAppKitConfig } from '@ordanetwork/widget';

// Module scope (SSR-safe).
const appKitConfig = createAppKitConfig({
  projectId: process.env.NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID!,
  metadata: {
    name: 'Your App',
    description: 'Your app description',
    url: 'https://yourapp.com',
    icons: ['https://yourapp.com/icon.png'],
  },
});

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <OrdaProvider
      config={{
        getToken: async () => {
          const res = await fetch('/api/auth/jwt', { method: 'POST' });
          if (!res.ok) {
            const { error } = await res.json();
            throw new Error(error || 'Failed to get JWT');
          }
          return res.json(); // { jwt: string, expiresAt: number }
        },
        appKitConfig,
        debug: process.env.NODE_ENV === 'development',
      }}
    >
      {children}
    </OrdaProvider>
  );
}
```

#### Step 4 — Mount the provider + styles in your root layout (`app/layout.tsx`)

```tsx
import './globals.css';
import '@ordanetwork/widget/styles.css';
import { Providers } from './providers';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}
```

#### Step 5 — Drop in the Widget (`app/page.tsx`)

```tsx
'use client';

import { Widget } from '@ordanetwork/widget';

export default function Home() {
  return (
    <main className="min-h-screen flex items-center justify-center p-4 bg-zinc-100">
      <div className="w-full max-w-md">
        <h1 className="text-2xl font-bold text-center mb-6">Crypto Payments</h1>
        <Widget
          onTransactionSettled={(e) => console.log('settled', e.payload)}
          onError={(e) => console.error(e.payload.message)}
        />
      </div>
    </main>
  );
}
```

#### Step 6 — Run

```bash
npm run dev
```

### Lifecycle callbacks

All optional props on `<Widget />`. Every event fires alongside `onAnalyticsEvent` — dedupe by `event.id` if you wire both (see Analytics firehose below).

| Callback                 | Fires when                                                                                  |
| ------------------------ | ------------------------------------------------------------------------------------------- |
| `onQuoteRequested`       | The widget asked the SDK for a quote (before network round-trip).                           |
| `onQuoteAccepted`        | A quote returned successfully (or was served from the 30 s cache — `payload.cached: true`). |
| `onQuoteFailed`          | Quote request failed (network / validation / SDK error).                                    |
| `onTransactionInitiated` | User confirmed; the wallet was asked to sign / submit.                                      |
| `onTransactionSettled`   | Transaction confirmed on-chain **or** settled by the backend.                               |
| `onTransactionFailed`    | Transaction reverted, was rejected, or failed before settling.                              |
| `onWalletConnected`      | An EVM or Solana wallet just connected.                                                     |
| `onWalletDisconnected`   | A wallet just disconnected.                                                                 |
| `onError`                | Any user-visible error (fires alongside the specific `*_failed` callback when applicable).  |
| `onAnalyticsEvent`       | **Firehose** — every event in order.                                                        |

Every event payload shares the same envelope:

```ts
{
  id: string;          // stable nanoid per event
  timestamp: number;   // Date.now() at emit
  flow?: 'swap' | 'onramp' | 'offramp';
  type: WidgetEventType;
  payload: { ... };    // discriminated by type
}
```

#### Analytics firehose

`onAnalyticsEvent` fires for **every** event, alongside the specific callback. Dedupe by `event.id` when you wire both:

```tsx
const seen = new Set<string>();

<Widget
  onTransactionSettled={(e) => {
    if (seen.has(e.id)) return;
    seen.add(e.id);
    yourTxHistoryStore.add(e.payload);
  }}
  onAnalyticsEvent={(e) => {
    if (seen.has(e.id)) return;
    seen.add(e.id);
    analytics.track(e.type, e.payload); // safe to forward verbatim — see below
  }}
/>
```

#### Payload redaction (PII)

{% hint style="success" %}
Event payloads are deliberately redacted so they are safe to forward verbatim to a third-party analytics sink (Segment / GA / PostHog / Mixpanel).
{% endhint %}

* **`quote_accepted`** carries only a serializable summary — `transactionId`, `provider`, `fromSymbol`/`toSymbol`, `fromAmount`/`toAmount`, `fromChainId`/`toChainId`, `estimatedDuration`, and `cached`. It does **not** include PIX key / QR code, deposit address, reference id, raw `transactionRequest` / `approvalTxParams` (signed calldata), or wallet addresses.
* **`quote_failed`, `transaction_failed`, and `error`** expose a human-readable `message` plus an optional `causeMessage` string. The underlying error object is **never** forwarded — viem / RPC errors embed tx params and request payloads, so only a message string crosses the callback boundary.

If you need the full, unredacted quote (e.g. to render PIX deposit instructions yourself), read it from the hook return values (`useOnRamp().quote`, etc.) rather than from events.

### Configuration flags

All optional on the `config` object passed to `<OrdaProvider>`:

| Field                 | Default      | Effect                                                                                                                                                                                 |
| --------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `getToken`            | — (required) | Returns `{ jwt, expiresAt }`. Called on mount and \~5 min before expiry.                                                                                                               |
| `appKitConfig`        | — (required) | From `createAppKitConfig({ projectId, metadata })`.                                                                                                                                    |
| `debug`               | `false`      | Verbose console logs for SDK init / refresh.                                                                                                                                           |
| `notifications`       | `true`       | When `true`, mounts a Sonner `<Toaster />`. When `false`, in-progress states render as inline `<Alert />` banners and success / error states surface only through lifecycle callbacks. |
| `disableOnRamp`       | `false`      | Hide on-ramp (fiat → crypto) flows.                                                                                                                                                    |
| `disableOffRamp`      | `false`      | Hide off-ramp (crypto → fiat) flows.                                                                                                                                                   |
| `enableOfframpSolana` | `false`      | Allow Solana as a source chain for off-ramp.                                                                                                                                           |

Apps controlling these via env (e.g. `NEXT_PUBLIC_ON_RAMP_DISABLED`) should map the env value to the config field when constructing the provider — the widget does not read `process.env.*` directly.

### SSR / RSC

`@ordanetwork/widget` is a client component. The bundle starts with `'use client';` so importing it from a React Server Component is safe — you get the `'use client'` boundary automatically. You do **not** need to wrap it.

`createAppKitConfig()` must be called at module scope (outside components) for SSR safety — see Step 3 above.

### Wallet mode

`@ordanetwork/widget@1.0.0` ships one wallet mode: **`appkit`** (the default). The widget mounts Wagmi + the Reown AppKit modal internally; you supply a `projectId` via `createAppKitConfig`.

{% hint style="info" %}
**BYOW (`wallet: 'external'`) is coming in 1.1.0** — for hosts that already own a `<WagmiProvider>` and want the widget to consume it. The plumbing exists internally; a few downstream call sites are still being migrated. Tracked as **COR-963**.
{% endhint %}

### TypeScript

All types ship with the package; no `@types/...` install needed.

```ts
import type {
  WidgetEvent,
  WidgetCallbacks,
  QuoteAcceptedPayload,
  TransactionSettledPayload,
  TransactionFailedPayload,
  OrdaProviderConfig,
} from '@ordanetwork/widget';
```

The full event union is discriminated by `type`, so narrowing in a callback works without casts.

### Security note

{% hint style="danger" %}
Never expose `ORDA_CLIENT_SECRET` to the browser. Always exchange credentials for a JWT on a server-side route (Step 2) and let the widget call that route via `config.getToken`.
{% endhint %}

### Migrating from `@ordanetwork/sdk/react`

If you integrated against the beta (when the widget lived inside the core SDK), here's the migration:

| Before (`@ordanetwork/sdk/react`)                                                   | After (`@ordanetwork/widget`)                                                    |
| ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `npm install @ordanetwork/sdk`                                                      | `npm install @ordanetwork/widget @ordanetwork/sdk`                               |
| `import { OrdaProvider, Widget, createAppKitConfig } from '@ordanetwork/sdk/react'` | `import { OrdaProvider, Widget, createAppKitConfig } from '@ordanetwork/widget'` |
| `import '@ordanetwork/sdk/react/styles.css'`                                        | `import '@ordanetwork/widget/styles.css'`                                        |

No runtime behavior changes — the same components, the same `OrdaProvider` config shape, the same `Widget` props. The split is purely about packaging: the React UI now ships independently of the core SDK so it can version on its own cadence.

The `@ordanetwork/sdk` itself remains a peer dependency (the widget uses it internally for quote / transaction / recipient API calls).


# Authentication

## JWT Authentication

### Authentication Flow

The widget uses JWT (JSON Web Token) authentication to securely communicate with the orda API:

{% stepper %}
{% step %}

### Initial request

When `OrdaProvider` mounts, it calls your `getToken()` function.
{% endstep %}

{% step %}

### Server exchange

Your server route exchanges `clientId` + `clientSecret` for a JWT.
{% endstep %}

{% step %}

### Token storage

JWT is stored in React state and used for all API requests.
{% endstep %}

{% step %}

### Auto-refresh

SDK automatically refreshes the token 5 minutes before expiration.
{% endstep %}

{% step %}

### Request queuing

Requests during refresh are queued and executed after completion.
{% endstep %}
{% endstepper %}

### Token Permissions

Your JWT should include the following permissions:

| Permission          | Description                         |
| ------------------- | ----------------------------------- |
| `quotes:read`       | Generate payment quotes             |
| `offramp:read`      | Off-ramp operations (crypto → fiat) |
| `onramp:read`       | On-ramp operations (fiat → crypto)  |
| `transactions:read` | View transaction status             |
| `recipients:read`   | List saved recipients               |
| `recipients:write`  | Create/update recipients            |

### Security Best Practices

1. Never expose `clientSecret` in browser code
   * Always generate JWT server-side
   * Use environment variables for secrets
   * Never commit secrets to version control
2. Use HTTPS in production
   * Ensure your JWT endpoint uses HTTPS
   * Tokens sent over HTTP can be intercepted
3. Implement rate limiting
   * Limit JWT generation requests per IP/user
   * Prevent abuse of your authentication endpoint
4. Set appropriate token expiration
   * Default: 1 hour (`expiresIn: 3600`)
   * Balance security and user experience
   * SDK handles auto-refresh seamlessly

### Example with Error Handling

```typescript
export async function POST() {
  try {
    if (!CLIENT_ID || !CLIENT_SECRET) {
      return NextResponse.json(
        { error: 'Server configuration error' },
        { status: 500 }
      );
    }

    const httpClient = new UniversalHttpClient(API_URL, 30000);
    const jwtApi = new JWT(httpClient);

    const { token, expiresAt } = await jwtApi.generate({
      clientId: CLIENT_ID,
      clientSecret: CLIENT_SECRET,
      permissions: [
        'quotes:read',
        'offramp:read',
        'onramp:read',
        'transactions:read',
        'recipients:read',
        'recipients:write',
        'balances:read',
        'prices:read'
      ],
    });

    return NextResponse.json({
      jwt: token,
      expiresAt: Math.floor(new Date(expiresAt).getTime() / 1000),
    });
  } catch (error: any) {
    console.error('JWT generation failed:', error);

    // Return appropriate error response
    return NextResponse.json(
      {
        error: error?.message || 'Authentication failed',
        code: error?.code
      },
      { status: error?.statusCode || 500 }
    );
  }
}
```

***

## Environment Variables

### Required Variables

| Variable                                | Description                   | Where to Get It                             |
| --------------------------------------- | ----------------------------- | ------------------------------------------- |
| `NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID` | WalletConnect project ID      | [cloud.reown.com](https://cloud.reown.com/) |
| `ORDA_CLIENT_ID`                        | orda project ID (server-side) | orda Developer Portal                       |
| `ORDA_CLIENT_SECRET`                    | orda API secret (server-side) | orda Developer Portal                       |

### Optional Variables

| Variable                        | Description       | Default                       |
| ------------------------------- | ----------------- | ----------------------------- |
| `NEXT_PUBLIC_ORDA_API_BASE_URL` | orda API base URL | `https://api.orda.network/v1` |

### Example `.env.local`

```bash
# WalletConnect Configuration
NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

# orda API Credentials (DO NOT expose to client)
ORDA_CLIENT_ID=prj_8a8ce3b783ef467f8f48270e4818e57b
ORDA_CLIENT_SECRET=sec_a3e8773348898a0e6ab19e94ee1169505283c1d5b3eb6f40fdaee99b476a25ea

# NEXT_PUBLIC_ORDA_API_BASE_URL=http://localhost:5002/v1
```

### Getting Your Credentials

{% stepper %}
{% step %}

### WalletConnect Project ID

1. Visit [cloud.reown.com](https://cloud.reown.com/)
2. Sign up or log in
3. Create a new project
4. Copy your **Project ID**
5. Add your app domains to the allowlist
   {% endstep %}

{% step %}

### orda API Credentials

1. Visit the orda Developer Portal
2. Sign up for an account
3. Create a new project
4. Copy your **Client ID** and **Client Secret**
   {% endstep %}
   {% endstepper %}


# Features

The widget supports three types of payment operations with comprehensive support for wallets and recipient management.

## Transaction Types

### Swap (Cross-Chain Token Exchange)

Exchange tokens across different blockchain networks.

{% stepper %}
{% step %}

#### User selects source token and chain (e.g., USDC on Ethereum)

{% endstep %}

{% step %}

#### User selects destination token and chain (e.g., USDT on Polygon)

{% endstep %}

{% step %}

#### User enters amount

{% endstep %}

{% step %}

#### Widget generates quote

{% endstep %}

{% step %}

#### User connects wallet and confirms transaction

{% endstep %}

{% step %}

#### Widget executes cross-chain swap

{% endstep %}
{% endstepper %}

**Supported**:

* Same-chain swaps (e.g., ETH → USDC on Ethereum)
* Cross-chain swaps (e.g., USDC on Ethereum → USDT on Polygon)
* Native token swaps (e.g., ETH → MATIC)

***

### Off-Ramp (Crypto to Fiat)

Convert cryptocurrency to fiat currency (currently BRL via PIX).

{% stepper %}
{% step %}

#### User selects source crypto (e.g., USDC on Polygon)

{% endstep %}

{% step %}

#### User enters amount in crypto or BRL

{% endstep %}

{% step %}

#### User enters PIX key or selects saved recipient

{% endstep %}

{% step %}

#### Widget generates quote with fees and exchange rate

{% endstep %}

{% step %}

#### User confirms and executes transaction

{% endstep %}

{% step %}

#### Fiat sent to recipient's bank account via PIX

{% endstep %}
{% endstepper %}

**Supported Fiat**:

* BRL (Brazilian Real) via PIX

**PIX Key Types**:

* CPF (Individual Tax ID)
* CNPJ (Business Tax ID)
* Email
* Phone
* Random Key

***

### On-Ramp (Fiat to Crypto)

Convert fiat currency to cryptocurrency (currently BRL → BRZ).

{% stepper %}
{% step %}

#### User selects destination crypto and chain

{% endstep %}

{% step %}

#### User enters amount in BRL or BRZ

{% endstep %}

{% step %}

#### Widget generates quote with payment details

{% endstep %}

{% step %}

#### User receives PIX payment instructions

{% endstep %}

{% step %}

#### User makes PIX payment from their bank app

{% endstep %}

{% step %}

#### Crypto sent to user's wallet after payment confirmation

{% endstep %}
{% endstepper %}

**Features**:

* Real-time PIX payment detection
* QR code for easy payment
* Copy-paste PIX payment string
* Transaction status tracking

***

## Wallet Connection

The widget integrates with WalletConnect/Reown AppKit for seamless wallet connections.

**Supported Wallets**:

* MetaMask
* WalletConnect compatible wallets
* Coinbase Wallet
* Rainbow Wallet
* Trust Wallet
* And more...

**Features**:

* One-click wallet connection
* Multi-chain support (automatically switch networks)
* Account management
* Transaction history
* Wallet disconnect

***

## Recipient Management

Save and manage payment recipients for faster transactions.

**Features**:

* **Crypto Recipients**: Save wallet addresses with labels
* **Fiat Recipients**: Save PIX keys with labels
* **Local Storage**: Recipients persisted in browser
* **Quick Selection**: Choose from saved recipients
* **Edit/Delete**: Manage your recipient list

**Example Usage**:

```typescript
import { useLocalRecipients } from '@ordanetwork/sdk/react';

function RecipientManager() {
  const {
    fiatRecipients,
    addFiatRecipient,
    cryptoRecipients,
    addCryptoRecipient,
  } = useLocalRecipients();

  const saveFiatRecipient = () => {
    addFiatRecipient({
      recipientId: 'rec_123',
      name: 'John Doe',
      pixKey: '12345678900',
    });
  };

  const saveCryptoRecipient = () => {
    addCryptoRecipient({
      recipientId: 'rec_456',
      name: 'Alice',
      address: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
      chainId: '1',
      tokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
    });
  };

  return (
    <div>
      <h2>Saved Recipients</h2>
      <p>Fiat: {fiatRecipients.length}</p>
      <p>Crypto: {cryptoRecipients.length}</p>
    </div>
  );
}
```


# Advanced Usage

## Using Hooks Independently

You can use the SDK hooks independently without the full widget UI.

### useQuote - Generate Payment Quotes

{% code title="useQuote example.tsx" %}

```typescript
import { useQuote } from '@ordanetwork/sdk/react';

function QuoteExample() {
  const { quote, isLoading, error, requestQuote } = useQuote();

  const getQuote = async () => {
    const result = await requestQuote({
      fromChainId: '1',        // Ethereum
      toChainId: '137',        // Polygon
      fromTokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
      toTokenAddress: '0xc2132D05D31c914a87C6611C10748AEb04B58e8F',   // USDT
      amount: '100',           // 100 USDC
      fromAddress: '0x...',    // User wallet
    });

    console.log('Quote:', result);
  };

  return (
    <div>
      <button onClick={getQuote} disabled={isLoading}>
        {isLoading ? 'Loading...' : 'Get Quote'}
      </button>
      {quote && (
        <div>
          <p>You will receive: {quote.toAmount} {quote.toToken.symbol}</p>
          <p>Fee: {quote.fee}</p>
        </div>
      )}
    </div>
  );
}
```

{% endcode %}

***

### useTransaction - Monitor Transaction Status

{% code title="useTransaction example.tsx" %}

```typescript
import { useTransaction } from '@ordanetwork/sdk/react';

function TransactionStatus({ txId }: { txId: string }) {
  const { status, isLoading, waitForCompletion } = useTransaction();

  useEffect(() => {
    if (txId) {
      // Poll for transaction completion
      waitForCompletion(txId, {
        interval: 2000,    // Check every 2 seconds
        timeout: 300000,   // Timeout after 5 minutes
      }).then((finalStatus) => {
        console.log('Transaction complete:', finalStatus);
      });
    }
  }, [txId, waitForCompletion]);

  return (
    <div>
      {status && (
        <div>
          <p>Status: {status.status}</p>
          <p>Progress: {status.completionPercentage}%</p>
        </div>
      )}
    </div>
  );
}
```

{% endcode %}

***

### useTokenPrices - Fetch USD Prices

{% code title="useTokenPrices example.tsx" %}

```typescript
import { useTokenPrices } from '@ordanetwork/sdk/react';

function TokenPrices() {
  const { prices, isLoading, error } = useTokenPrices([
    { address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', chainId: '1' }, // USDC
    { address: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', chainId: '1' }, // WETH
  ]);

  if (isLoading) return <div>Loading prices...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      {prices.map((price) => (
        <div key={price.address}>
          <p>{price.symbol}: ${price.usdPrice}</p>
        </div>
      ))}
    </div>
  );
}
```

{% endcode %}

***

### useBalances - Fetch Wallet Balances

{% code title="useBalances example.tsx" %}

```typescript
import { useBalances } from '@ordanetwork/sdk/react';
import { useAccount } from 'wagmi';

function WalletBalances() {
  const { address } = useAccount();
  const { data, isLoading, error } = useBalances(address, {
    chainIds: ['1', '137', '42161'], // Ethereum, Polygon, Arbitrum
    filter: 'known', // Only show known tokens
  });

  if (isLoading) return <div>Loading balances...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      {data?.balances.map((balance) => (
        <div key={`${balance.chainId}-${balance.address}`}>
          <p>
            {balance.symbol}: {balance.formatted} (${balance.usdValue})
          </p>
        </div>
      ))}
    </div>
  );
}
```

{% endcode %}

***

## Accessing the SDK Instance

Access the core SDK instance for direct API calls:

{% code title="useOrdaSDK example.tsx" %}

```typescript
import { useOrdaSDK } from '@ordanetwork/sdk/react';

function CustomComponent() {
  const { sdk, isLoading, error } = useOrdaSDK();

  useEffect(() => {
    if (sdk) {
      // Direct SDK access
      sdk.quote.request({ /* params */ })
        .then((quote) => console.log('Quote:', quote));
    }
  }, [sdk]);

  if (isLoading) return <div>Initializing SDK...</div>;
  if (error) return <div>SDK Error: {error.message}</div>;

  return <div>SDK Ready!</div>;
}
```

{% endcode %}

***

## Using UI Components Separately

All UI components can be used independently:

{% code title="UI components example.tsx" %}

```typescript
import { Button, Dialog, Input } from '@ordanetwork/sdk/react';

function CustomForm() {
  return (
    <Dialog>
      <DialogTrigger asChild>
        <Button variant="default">Open Form</Button>
      </DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Enter Amount</DialogTitle>
        </DialogHeader>
        <Input type="number" placeholder="0.00" />
        <Button>Submit</Button>
      </DialogContent>
    </Dialog>
  );
}
```

{% endcode %}

***

### OrdaProvider Configuration

The `OrdaProvider` component accepts a `config` prop with the following options:

```typescript
interface OrdaProviderConfig {
  /**
   * Async function that fetches a JWT token from your backend.
   * Called on initialization and automatically before token expiration.
   *
   * @returns Promise resolving to { jwt: string, expiresAt: number }
   */
  getToken: () => Promise<TokenResponse>;

  /**
   * AppKit configuration for wallet connections.
   * Create using createAppKitConfig().
   */
  appKitConfig: AppKitConfig;

  /**
   * Enable debug mode for development.
   * Logs SDK initialization, token refresh, and request details.
   *
   * @default false
   */
  debug?: boolean;
}

interface TokenResponse {
  jwt: string;      // JWT token string
  expiresAt: number; // Unix timestamp in seconds
}
```

### AppKit Configuration

The `createAppKitConfig` function creates a wallet connection configuration:

```typescript
interface AppKitFactoryConfig {
  /**
   * WalletConnect Project ID from cloud.reown.com
   * Required for wallet connections.
   */
  projectId: string;

  /**
   * Optional metadata for wallet connection UI
   */
  metadata?: {
    name?: string;        // App name (default: 'orda Widget')
    description?: string; // App description
    url?: string;         // App URL (default: 'https://orda.network')
    icons?: string[];     // App icon URLs
  };
}
```

Example with custom metadata:

```typescript
const appKitConfig = createAppKitConfig({
  projectId: process.env.NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID!,
  metadata: {
    name: 'My DeFi App',
    description: 'Multi-chain payment platform',
    url: 'https://mydefiapp.com',
    icons: ['https://mydefiapp.com/logo.png'],
  },
});
```


# Styling

## Importing Styles

You must import the widget styles in your root layout:

{% code title="root layout (TypeScript)" %}

```typescript
import '@ordanetwork/sdk/react/styles.css';
```

{% endcode %}

## CSS Variables

The widget uses CSS variables for theming, scoped to `.orda-widget`:

{% code title="Theme variables (CSS)" %}

```css
.orda-widget {
  /* Border radius */
  --orda-radius: 0.625rem;

  /* Colors (OKLCH format) */
  --orda-background: oklch(1 0 0);           /* White */
  --orda-foreground: oklch(0.145 0 0);       /* Near-black */
  --orda-primary: oklch(0.205 0 0);          /* Dark */
  --orda-destructive: oklch(0.577 0.245 27.325); /* Red */

  /* Custom backgrounds */
  --orda-main-bg: #fbfbfb;
}
```

{% endcode %}

## Dark Mode

Apply the `.dark` class to enable dark mode:

{% code title="Dark mode (CSS)" %}

```css
.orda-widget.dark {
  --orda-background: oklch(0.145 0 0);       /* Near-black */
  --orda-foreground: oklch(0.985 0 0);       /* Near-white */
  --orda-primary: oklch(0.985 0 0);          /* White */
  --orda-main-bg: #1a1a1a;
}
```

{% endcode %}

## Customizing Theme

Override CSS variables in your global CSS:

{% code title="globals.css" %}

```css
/* globals.css */
.orda-widget {
  --orda-primary: oklch(0.5 0.2 250);  /* Custom blue */
  --orda-radius: 0.5rem;               /* Smaller border radius */
}
```

{% endcode %}

## Tailwind CSS Integration

If your app uses Tailwind CSS, the widget styles will work alongside your Tailwind configuration. The widget's Tailwind classes are scoped to avoid conflicts.

{% hint style="info" %}
Do not include node\_modules in your Tailwind `content` paths — the widget ships pre-compiled styles and shouldn't be scanned.
{% endhint %}

**Example integration**:

{% code title="tailwind.config.ts" %}

```typescript
// tailwind.config.ts
import type { Config } from 'tailwindcss';

const config: Config = {
  content: [
    './app/**/*.{js,ts,jsx,tsx}',
    './components/**/*.{js,ts,jsx,tsx}',
    // Don't include node_modules - widget has pre-compiled styles
  ],
  theme: {
    extend: {
      // Your custom theme
    },
  },
  plugins: [],
};

export default config;
```

{% endcode %}


# Troubleshooting

### Widget Not Rendering

**Problem**: Widget doesn't appear or styles are broken.

**Solution**:

{% stepper %}
{% step %}
Verify you've imported the styles:

```typescript
import '@ordanetwork/sdk/react/styles.css';
```

{% endstep %}

{% step %}
Check browser console for errors.
{% endstep %}

{% step %}
Ensure `OrdaProvider` wraps your component.
{% endstep %}

{% step %}
Verify all peer dependencies are installed.
{% endstep %}
{% endstepper %}

### Authentication Errors

**Problem**: "Failed to get JWT token" or 401 errors.

**Solution**:

{% stepper %}
{% step %}
Check your `.env.local` has correct credentials:

```bash
ORDA_CLIENT_ID=prj_...
ORDA_CLIENT_SECRET=sec_...
```

{% endstep %}

{% step %}
Verify your JWT endpoint is working:

```bash
curl -X POST http://localhost:3000/api/auth/jwt
```

{% endstep %}

{% step %}
Check server logs for error details.
{% endstep %}

{% step %}
Ensure `getToken()` returns correct format:

```typescript
{ jwt: string, expiresAt: number }
```

{% endstep %}
{% endstepper %}

### Wallet Connection Issues

**Problem**: Wallets won't connect or WalletConnect modal doesn't open.

**Solution**:

{% stepper %}
{% step %}
Verify `NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID` is set.
{% endstep %}

{% step %}
Check projectId is valid (32+ characters).
{% endstep %}

{% step %}
Ensure your domain is allowlisted in WalletConnect Cloud.
{% endstep %}

{% step %}
Try clearing browser cache and reconnecting.
{% endstep %}

{% step %}
Check browser console for WalletConnect errors.
{% endstep %}
{% endstepper %}

### Build Errors

**Problem**: TypeScript errors or build failures.

**Solution**:

{% stepper %}
{% step %}
Ensure peer dependencies match version requirements:

```bash
npm ls react wagmi viem @tanstack/react-query
```

{% endstep %}

{% step %}
Clear node\_modules and reinstall:

```bash
rm -rf node_modules package-lock.json
npm install
```

{% endstep %}

{% step %}
Check TypeScript version (5.0+):

```bash
npx tsc --version
```

{% endstep %}
{% endstepper %}

### Style Conflicts

**Problem**: Widget styles conflict with app styles.

**Solution**:

{% stepper %}
{% step %}
Widget styles are scoped to `.orda-widget`.
{% endstep %}

{% step %}
Import widget styles AFTER your global styles:

```typescript
import './globals.css';
import '@ordanetwork/sdk/react/styles.css'; // After globals
```

{% endstep %}

{% step %}
Use CSS modules or scoped styles for your app.
{% endstep %}
{% endstepper %}

### Token Prices Not Loading

**Problem**: Token prices show as $0 or fail to load.

**Solution**:

{% stepper %}
{% step %}
Check network connectivity.
{% endstep %}

{% step %}
Verify JWT has `quotes:read` permission.
{% endstep %}

{% step %}
Check browser console for API errors.
{% endstep %}

{% step %}
Ensure token addresses are correct.
{% endstep %}

{% step %}
Try refreshing the page.
{% endstep %}
{% endstepper %}

### Debug Mode

Enable debug mode to see detailed logs:

```typescript
<OrdaProvider
  config={{
    getToken: async () => { /* ... */ },
    appKitConfig,
    debug: true, // Enable debug logs
  }}
>
```

Debug logs will show:

* SDK initialization
* Token refresh timing
* API request details
* Error stack traces

***

## Additional Resources

### Documentation

1. **orda Developer Portal**: <https://app.orda.network>
2. **API Documentation**: <https://docs.orda.network>
3. **orda SDK**: <https://www.npmjs.com/package/@ordanetwork/sdk>


# Frameworks

## Next.js App Router

See the [Getting Started guide](broken://pages/da44cbbeddd86ec7ab9bc5c02ebcb17f8e61fa95) for a complete Next.js App Router example with step-by-step instructions.

***

## Next.js Pages Router

For Next.js Pages Router, wrap your app in `_app.tsx`:

{% code title="pages/\_app.tsx" %}

```typescript
import type { AppProps } from 'next/app';
import '@ordanetwork/sdk/react/styles.css';
import { Providers } from '../components/Providers';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <Providers>
      <Component {...pageProps} />
    </Providers>
  );
}
```

{% endcode %}

{% code title="components/Providers.tsx" %}

```typescript
'use client';

import { OrdaProvider, createAppKitConfig } from '@ordanetwork/sdk/react';

const appKitConfig = createAppKitConfig({
  projectId: process.env.NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID!,
});

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <OrdaProvider
      config={{
        getToken: async () => {
          const res = await fetch('/api/auth/jwt', { method: 'POST' });
          return res.json();
        },
        appKitConfig,
      }}
    >
      {children}
    </OrdaProvider>
  );
}
```

{% endcode %}

{% code title="pages/api/auth/jwt.ts" %}

```typescript
import type { NextApiRequest, NextApiResponse } from 'next';
import { UniversalHttpClient, JWT } from '@ordanetwork/sdk';

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Method not allowed' });
  }

  try {
    const httpClient = new UniversalHttpClient(
      process.env.NEXT_PUBLIC_ORDA_API_BASE_URL || 'https://api.orda.network/v1',
      30000
    );
    const jwtApi = new JWT(httpClient);

    const { token, expiresAt } = await jwtApi.generate({
      clientId: process.env.ORDA_CLIENT_ID!,
      clientSecret: process.env.ORDA_CLIENT_SECRET!,
      permissions: [
        'quotes:read',
        'offramp:read',
        'onramp:read',
        'transactions:read',
        'recipients:read',
        'recipients:write',
      ],
    });

    res.status(200).json({
      jwt: token,
      expiresAt: Math.floor(new Date(expiresAt).getTime() / 1000),
    });
  } catch (error: any) {
    console.error('JWT generation failed:', error);
    res.status(500).json({ error: error?.message || 'Authentication failed' });
  }
}
```

{% endcode %}

***

## Vite + React

{% code title="main.tsx" %}

```typescript
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import '@ordanetwork/sdk/react/styles.css';
import './index.css';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);
```

{% endcode %}

{% code title="App.tsx" %}

```typescript
import { OrdaProvider, createAppKitConfig, Widget } from '@ordanetwork/sdk/react';

const appKitConfig = createAppKitConfig({
  projectId: import.meta.env.VITE_WALLET_CONNECT_PROJECT_ID,
});

function App() {
  return (
    <OrdaProvider
      config={{
        getToken: async () => {
          // Call your backend to get JWT
          const res = await fetch('https://yourapi.com/auth/jwt', {
            method: 'POST',
          });
          return res.json();
        },
        appKitConfig,
      }}
    >
      <div className="app">
        <Widget />
      </div>
    </OrdaProvider>
  );
}

export default App;
```

{% endcode %}

***

## Create React App

Similar to Vite, but use `process.env.REACT_APP_*` for environment variables:

{% code title="index.tsx" %}

```typescript
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import '@ordanetwork/sdk/react/styles.css';
import './index.css';

const root = ReactDOM.createRoot(
  document.getElementById('root') as HTMLElement
);

root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);
```

{% endcode %}

Create React App setup is similar to Vite:

{% code title="App.tsx (Create React App)" %}

```typescript
import { OrdaProvider, createAppKitConfig, Widget } from '@ordanetwork/sdk/react';

const appKitConfig = createAppKitConfig({
  projectId: process.env.REACT_APP_WALLET_CONNECT_PROJECT_ID!,
});

function App() {
  return (
    <OrdaProvider
      config={{
        getToken: async () => {
          const res = await fetch('https://yourapi.com/auth/jwt', {
            method: 'POST',
          });
          return res.json();
        },
        appKitConfig,
      }}
    >
      <div className="app">
        <Widget />
      </div>
    </OrdaProvider>
  );
}

export default App;
```

{% endcode %}


# Widget Reference

### `OrdaProvider`

Main provider component that wraps your application.

```typescript
interface OrdaProviderProps {
  config: OrdaProviderConfig;
  children: React.ReactNode;
}

interface OrdaProviderConfig {
  getToken: () => Promise<TokenResponse>;
  appKitConfig: AppKitConfig;
  debug?: boolean;
}
```

### `createAppKitConfig`

Factory function for creating wallet configuration.

```typescript
function createAppKitConfig(config: AppKitFactoryConfig): AppKitConfig;

interface AppKitFactoryConfig {
  projectId: string;
  metadata?: {
    name?: string;
    description?: string;
    url?: string;
    icons?: string[];
  };
}
```

### Hooks

#### `useOrdaSDK`

Access the SDK instance and authentication state.

```typescript
function useOrdaSDK(): OrdaSDKContextValue;

interface OrdaSDKContextValue {
  sdk: OrdaSDK | null;
  isLoading: boolean;
  error: Error | null;
  refreshToken: () => Promise<void>;
  isRefreshing: boolean;
  waitForRefresh: () => Promise<void>;
}
```

#### `useQuote`

Generate payment quotes.

```typescript
function useQuote(): UseQuoteReturn;

interface UseQuoteReturn {
  quote: TransferResponse | DirectTransferResponse | null;
  isLoading: boolean;
  error: Error | null;
  requestQuote: (params: QuoteRequestParams) => Promise<QuoteResponse>;
  clearQuote: () => void;
}
```

#### `useTransaction`

Monitor transaction status.

```typescript
function useTransaction(): UseTransactionReturn;

interface UseTransactionReturn {
  status: TransactionStatusResponse | null;
  isLoading: boolean;
  error: Error | null;
  getStatus: (params: TransactionStatusParams) => Promise<TransactionStatusResponse>;
  waitForCompletion: (txId: string, options?: PollingOptions) => Promise<TransactionStatusResponse>;
  clearStatus: () => void;
}
```

#### `useTokenPrices`

Fetch token USD prices.

```typescript
function useTokenPrices(
  tokens: TokenPriceRequest[],
  options?: UseTokenPricesOptions
): UseTokenPricesReturn;

interface UseTokenPricesReturn {
  prices: TokenPriceData[];
  isLoading: boolean;
  isFetching: boolean;
  error: Error | null;
  refetch: () => Promise<void>;
}
```

#### `useBalances`

Fetch wallet token balances.

```typescript
function useBalances(
  address: string | undefined,
  options?: UseBalancesOptions
): UseBalancesReturn;

interface UseBalancesReturn {
  data: BalancesFetchResponse | null;
  isLoading: boolean;
  isFetching: boolean;
  error: Error | null;
  refetch: () => Promise<void>;
}
```

### Components

#### Widget

Main payment widget component.

```typescript
function Widget(): JSX.Element;
```

#### UI Components

shadcn/ui-based components:

* `Button` - Button component with variants
* `Dialog` - Modal dialog
* `Drawer` - Bottom drawer (mobile)
* `Input` - Text input
* `Select` - Dropdown select
* `Badge` - Badge/chip component
* `Label` - Form label
* `Popover` - Popover tooltip
* `Sheet` - Side sheet

### Utilities

```typescript
// Formatting
formatUsd(value: number): string;
formatUsdFull(value: number): string;
formatCryptoAmount(amount: string, decimals: number): string;
truncateAddress(address: string, start?: number, end?: number): string;

// Parsing
parseToNativeUnits(amount: string, decimals: number): string;
parseFromNativeUnits(amount: string, decimals: number): string;

// Validation
isValidAddress(address: string): boolean;
isValidAmount(amount: string): boolean;

// Chain utilities
getWagmiChain(chainId: string): Chain | undefined;
getChainName(chainId: string): string;
```

### Constants

```typescript
// Chain IDs
enum ChainId {
  ETHEREUM = '1',
  POLYGON = '137',
  ARBITRUM = '42161',
  // ... more chains
}

// Supported chains
const SUPPORTED_CHAINS: ChainInfo[];

// Common tokens
const COMMON_TOKENS: TokenInfo[];

// Fiat currencies
const FIAT_CURRENCIES: FiatInfo[];
```


# Guides


# Postman Workspace

### Overview

orda provides a comprehensive Postman collection to explore and test our payments & settlement API. The collection includes ready-to-use requests, inline tests, and a pre-request **HMAC (SHA-256) canonical JSON** signing script so your requests match our server-side signature verification.

### Accessing the Collection

Our official workspace and collection live here:

* **orda API Postman Workspace:** [postman.com/orda-nw/orda-api/overview](https://postman.com/orda-nw/orda-api/overview)
* **Direct collection link (share/fork):** [orda API Public Postman Collection (Postman)](https://www.postman.com/orda-nw/orda-api/collection/zfuut50/orda-api-public-postman-collection?action=share\&creator=48155498)

### Collection Features

* **Ready-to-Use Requests:** Preconfigured calls for creating recipients (crypto address & Brazilian PIX), requesting quotes, executing transfers, and checking statuses.
* **Authentication Built-In:** A pre-request script signs every call with **HMAC-SHA256 over canonical JSON**; works with or without a body.
* **Inline Tests & Env Writes:** Responses capture IDs (e.g., `pix_recipient_id`) into environment variables for use in follow-up steps.
* **Environment Template:** Variables for `base_url`, `api_client_id`, `api_client_secret`, recipient wallets/IDs, PIX fields, and transaction refs.

### Getting Started

#### 1) Fork the Collection

* Open the orda API workspace and fork the public collection into your own workspace.

#### 2) Set Up Your Environment

Create a **Postman environment** with the following keys (values in your env, not in code):

* `base_url` → `https://api.orda.network`
* `api_client_id`, `api_client_secret` → from your orda account
* Optional/flow-specific: `test_from_address`, `ethereum_recipient_wallet`, `base_recipient_wallet`, `pix_key`, `pix_recipient_tax_id`, `pix_recipient_email`, `pix_recipient_name`, plus result variables the tests will populate (`*_recipient_id`, `transaction_id`, `pix_quote_id`).

> Keep `api_client_secret` in Postman as a **secret** and never commit it to source control.

#### 3) Make Your First Requests

1. **Run “1. Setup – Create Recipients”**
   * Example (EVM wallet on Base for BRZ): POST `{{base_url}}/v1/create-recipient` with `toChain=8453`, `toToken=BRZ on Base`, `toAddress={{base_recipient_wallet}}`. The test saves returned IDs to your environment.
   * Example (Brazilian PIX recipient): POST `{{base_url}}/v1/create-recipient` with `fiatSettlementDetails.toCurrency="BRL"` and PIX/KYC fields; the test writes `pix_recipient_id`.
2. **Use “2. Cross-Chain Transfers”** to request quotes/execute, and then **check the status** with `/v1/status?transactionId={{transaction_id}}`.
3. **Use “3. Fiat Operations”** for **on-ramp** (PIX→crypto) and **off-ramp** (crypto→PIX) flows, including `/v1/onramp/status` tracked via `{{pix_quote_id}}`.

### Authentication

All requests are signed with **HMAC-SHA256** using a **canonical JSON** string. The pre-request script:

* Resolves `{{environment}}` placeholders before hashing
* Canonicalizes JSON (stable key order, consistent primitives)
* Handles empty/no-body requests gracefully\
  This ensures signatures match server verification across all endpoints.

**Required headers** (the script sets them as needed):

* `x-client-id: {{api_client_id}}`
* `x-timestamp`
* `x-signature`
* `content-type: application/json`

### Available Folders & Example Endpoints

* **1. Setup – Create Recipients**
  * `POST /v1/create-recipient` (EVM wallet for BRZ on Base)
  * `POST /v1/create-recipient` (Brazilian PIX recipient; KYC required)
* **2. Cross-Chain Transfers**
  * `GET /v1/status?transactionId={{transaction_id}}` (transfer lifecycle)
* **3. Fiat Operations**
  * On-ramp & Off-ramp quote/status flows (PIX↔crypto) with env-driven IDs.

### Best Practices

* Keep your API credentials in a Postman **environment**; never hardcode or share them.
* Reuse environment variables for wallets, PIX data, and IDs saved by tests to chain requests correctly.
* Use the Postman Console to inspect canonical JSON and signatures when debugging. The script logs key steps and verifies canonicalization.


# Vaults

The credit layer for corridor liquidity

**Vaults** are the credit layer for corridor liquidity. Vaults separate capital supply from execution so liquidity providers deposit once, and solvers borrow only when needed. This eliminates the inefficiencies of fragmented pre-funding, concentrates liquidity into a shared venue, and drives spreads toward interbank levels.

### **Direct stakeholders**

* **Liquidity Providers (LPs):** Single-sided currency deposits. One vault, one yield.
* **Solvers:** Borrow liquidity as needed. No balance sheet drag.

#### **Extended network**

* **OTC Desks & Brokers:** On-demand corridor liquidity. No idle float.
* **Neo-banks & Brokers:** Multi-currency access. Interbank-level pricing.
* **Issuers & Stablecoin Ecosystems:** Supply growth. Plug into all corridors.
* **Payment Supply Chain (PSPs, processors, acquirers):** Spread compression. Earnable product.

### Get involved

We’re working with early partners to open new corridors, expand liquidity and prove the model at scale. Reach out to <hunter@orda.network> with any questions or inquiries.


# API Reference

This is the authoritative, versioned specification for the orda network. It documents every endpoint, request/response schema, authentication method, and error code for:

* **Crypto ↔ Fiat Ramps:** deposit, withdrawal, and conversion
* **Chain-Abstracted Transfers:** stablecoin and token movement on or across networks

Use this reference when building or debugging with orda. For a quicker start, begin with the onboarding guides and Postman collection, then return here for exact parameter names, data types, and example payloads.


# Authentication

This API uses HMAC-SHA256 authentication to ensure request integrity and authenticity. All requests must include proper authentication headers.


# Required Headers

| Header        | Description                                                          | Example         |
| ------------- | -------------------------------------------------------------------- | --------------- |
| `x-client-id` | Your project client ID from orda dashboard                           | `prj_abc123...` |
| `x-signature` | HMAC-SHA256 signature of the canonical request body                  | `a1b2c3d4...`   |
| `x-timestamp` | Request timestamp in milliseconds (for replay protection - Optional) | `1704067200000` |


# Signature Generation

The HMAC signature is generated using the following process:

#### 1. Canonical JSON Serialization

The request body is canonicalized to ensure consistent signatures regardless of JSON key ordering:

* Object keys are sorted alphabetically
* No whitespace between elements
* Consistent string escaping
* Handles nested objects and arrays recursively

**Example:**

```json
// Original JSON (key order may vary)
{"name": "John", "age": 30, "city": "New York"}

// Canonical JSON (always same output)
{"age":30,"city":"New York","name":"John"}
```

#### 2. HMAC-SHA256 Calculation

```
signature = HMAC-SHA256(canonical_body, client_secret)
```

Where:

* `canonical_body` is the canonicalized JSON string. **For GET or requests with no body**, use the string `"{}"` (canonical empty object), not the literal empty string `""`. The API and SDK sign GET requests with `"{}"`.
* `client_secret` is your API client secret
* Output is hexadecimal string


# Authentication Flow

1. **Canonicalize** the request body JSON (if present)
2. **Generate** HMAC-SHA256 signature using your client secret
3. **Add headers** to your request:
   * `x-client-id`: Your project client ID
   * `x-signature`: The generated signature
   * `x-timestamp`: Current timestamp in milliseconds - Optional
4. **Send** the request


# Error Responses

| Status Code | Error               | Description                                      |
| ----------- | ------------------- | ------------------------------------------------ |
| `401`       | `INVALID_SIGNATURE` | Signature verification failed                    |
| `401`       | `MISSING_SIGNATURE` | Required x-signature header missing              |
| `401`       | `MISSING_CLIENT_ID` | Required x-client-id header missing              |
| `401`       | `TIMESTAMP_TOO_OLD` | Request timestamp is too old (replay protection) |
| `403`       | `INVALID_CLIENT`    | Client credentials are invalid                   |


# Code Examples

#### JavaScript (Node.js)

```javascript
const crypto = require('crypto');

function canonicalizeJSON(obj, seenObjects = new WeakSet()) {
    if (obj === null) return 'null';
    if (typeof obj === 'undefined') return 'undefined';
    if (typeof obj === 'boolean' || typeof obj === 'number') return String(obj);
    if (typeof obj === 'string') return JSON.stringify(obj);
    if (obj instanceof Date) return JSON.stringify(obj.toISOString());
    
    if (Array.isArray(obj)) {
        if (seenObjects.has(obj)) return '[Circular]';
        seenObjects.add(obj);
        const items = obj.map(item => canonicalizeJSON(item, seenObjects));
        seenObjects.delete(obj);
        return `[${items.join(',')}]`;
    }
    
    if (typeof obj === 'object') {
        if (seenObjects.has(obj)) return '{Circular}';
        seenObjects.add(obj);
        const sortedKeys = Object.keys(obj).sort();
        const pairs = sortedKeys.map(key => {
            const value = canonicalizeJSON(obj[key], seenObjects);
            return `${JSON.stringify(key)}:${value}`;
        });
        seenObjects.delete(obj);
        return `{${pairs.join(',')}}`;
    }
    
    return JSON.stringify(obj);
}

function generateSignature(body, clientSecret) {
    const canonicalBody = body ? canonicalizeJSON(body) : '{}';
    return crypto
        .createHmac('sha256', clientSecret)
        .update(canonicalBody)
        .digest('hex');
}

// Add to request headers
const headers = {
    'x-client-id': clientId,
    'x-signature': generateSignature(requestBody, clientSecret),
    'x-timestamp': Date.now().toString(),
    'Content-Type': 'application/json'
};
```

#### Python

```python
import hashlib
import hmac
import json
import time
from typing import Any, Set

def canonicalize_json(obj: Any, seen_objects: Set[int] = None) -> str:
    if seen_objects is None:
        seen_objects = set()
        
    if obj is None:
        return 'null'
    elif isinstance(obj, bool):
        return 'true' if obj else 'false'
    elif isinstance(obj, (int, float)):
        return str(obj)
    elif isinstance(obj, str):
        return json.dumps(obj)
    elif isinstance(obj, list):
        obj_id = id(obj)
        if obj_id in seen_objects:
            return '[Circular]'
        seen_objects.add(obj_id)
        items = [canonicalize_json(item, seen_objects) for item in obj]
        seen_objects.remove(obj_id)
        return f"[{','.join(items)}]"
    elif isinstance(obj, dict):
        obj_id = id(obj)
        if obj_id in seen_objects:
            return '{Circular}'
        seen_objects.add(obj_id)
        sorted_keys = sorted(obj.keys())
        pairs = [f'"{key}":{canonicalize_json(obj[key], seen_objects)}' for key in sorted_keys]
        seen_objects.remove(obj_id)
        return f"{{{','.join(pairs)}}}"
    else:
        return json.dumps(obj)

def generate_signature(body: dict, client_secret: str) -> str:
    canonical_body = canonicalize_json(body) if body else '{}'
    signature = hmac.new(
        client_secret.encode('utf-8'),
        canonical_body.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return signature

# Add to request headers
headers = {
    'x-client-id': client_id,
    'x-signature': generate_signature(request_body, client_secret),
    'x-timestamp': str(int(time.time() * 1000)),
    'Content-Type': 'application/json'
}
```

#### cURL

```bash
# You'll need to implement canonical JSON serialization
# and HMAC generation in your preferred scripting language

SIGNATURE=$(echo -n "$CANONICAL_BODY" | openssl dgst -sha256 -hmac "$CLIENT_SECRET" -hex | cut -d' ' -f2)
TIMESTAMP=$(date +%s)000

curl -X POST "https://api.orda.network/v1/endpoint" \
  -H "Content-Type: application/json" \
  -H "x-client-id: $CLIENT_ID" \
  -H "x-signature: $SIGNATURE" \
  -H "x-timestamp: $TIMESTAMP" \
  -d "$REQUEST_BODY"
```


# Important Notes

* **Empty bodies**: For requests with no body (e.g. GET), use the canonical empty object string `"{}"` for signature generation—not the literal empty string `""`. The API middleware and SDK sign GET requests with `"{}"`.
* **Key ordering**: The canonical JSON ensures consistent signatures regardless of object key order
* **Environment variables**: When using Postman, environment variables in the format `{{variable_name}}` are automatically resolved
* **Replay protection**: Timestamps prevent replay attacks; ensure your system clock is synchronized
* **Secret security**: Keep your client secret secure and never expose it in client-side code


# Testing Your Implementation

To verify your HMAC implementation is working correctly:

1. Test with the same JSON object but different key orders
2. Ensure both generate identical signatures
3. Verify empty body requests work correctly
4. Test with nested objects and arrays


# Authentication

Operations for generating and managing API tokens

## Generate JWT token

> Generate a JWT token for SDK authentication.\
> \
> \### Authentication\
> \
> This endpoint uses client credentials (not HMAC signature). You must provide:\
> \- \`x-client-id\`: Your project's client ID\
> \- \`x-client-secret\`: Your project's client secret\
> \
> \*\*Important Notes:\*\*\
> \- Tokens expire after the specified duration (default: 1 hour)\
> \- Use this endpoint from your backend to obtain tokens for frontend SDK usage\
> \- Never expose your client secret in client-side code<br>

```json
{"openapi":"3.0.3","info":{"title":"Orda API","version":"1.1.0"},"tags":[{"name":"Authentication","description":"Operations for generating and managing API tokens"}],"servers":[{"url":"https://api.orda.network/v1","description":"Default API path"}],"security":[{"ClientId":[],"Signature":[],"Timestamp":[]}],"components":{"securitySchemes":{"ClientId":{"type":"apiKey","in":"header","name":"x-client-id","description":"Your project client ID from orda dashboard"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error type identifier"},"message":{"type":"string","description":"Human-readable error message"},"correlationId":{"type":"string","description":"Request correlation ID for debugging"}}}}},"paths":{"/tokens":{"post":{"summary":"Generate JWT token","description":"Generate a JWT token for SDK authentication.\n\n### Authentication\n\nThis endpoint uses client credentials (not HMAC signature). You must provide:\n- `x-client-id`: Your project's client ID\n- `x-client-secret`: Your project's client secret\n\n**Important Notes:**\n- Tokens expire after the specified duration (default: 1 hour)\n- Use this endpoint from your backend to obtain tokens for frontend SDK usage\n- Never expose your client secret in client-side code\n","tags":["Authentication"],"parameters":[{"name":"x-client-id","in":"header","required":true,"description":"Your project's client ID","schema":{"type":"string"}},{"name":"x-client-secret","in":"header","required":true,"description":"Your project's client secret","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"expiresIn":{"type":"integer","minimum":60,"maximum":86400,"default":3600,"description":"Token expiration time in seconds (default 3600 = 1 hour)"},"permissions":{"type":"array","items":{"type":"string","enum":["quotes:read","offramp:read","onramp:read","transactions:read","recipients:read","recipients:write"]},"default":["quotes:read","offramp:read","onramp:read","transactions:read","recipients:read"],"description":"Permissions to grant to the token"}}}}}},"responses":{"200":{"description":"Token generated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","description":"JWT token for SDK authentication"},"expiresAt":{"type":"string","format":"date-time","description":"ISO 8601 timestamp when the token expires"}}}}}},"401":{"description":"Unauthorized - Invalid or missing credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```


# Crypto To Crypto

Operations for handling direct and cross-chain transactions

## Request a quote

> \### Authentication\
> \
> All API requests to orda require HMAC signatures using your project's client ID and client secret. To authenticate your quote request the signature is a HMAC-SHA256 hash of the request body, using your Client Secret as the key. Never share your Client Secret or include it directly in your client-side code.\
> \
> \- Generate an \`x-signature\` header using your client secret.\
> \- Include your \`x-client-id\` in the request headers.\
> \
> \#### Required Headers\
> \
> \| Header | Description |\
> \|--------|-------------|\
> \| \`x-client-id\` | Your project's client ID |\
> \| \`x-signature\` | HMAC-SHA256 signature derived from your client secret |\
> \| \`Content-Type\` | \`application/json\` for this request |\
> \
> \---\
> \
> \*\*Intent Specification:\*\*\
> The quote request uses an \`intent\` object to specify the amount calculation method:\
> \- \`usd\`: Calculate based on USD amount\
> \- \`fromAmount\`: Calculate based on source token amount  \
> \- \`toAmount\`: Calculate based on destination token amount\
> \
> \*\*Important Notes:\*\*\
> \- On the direct-transfer path the response \`message\` is \`Direct transfer transaction prepared\` (otherwise \`Quote requested\`)\
> \- Make sure you are using the correct token decimals for the token and chain when using toAmount and fromAmount intent methods\
> \- Users should request new quotes frequently for accurate pricing\
> \- The API uses rate limiting for all end points (10 requests per 5 minutes per project)\
> \- You must provide either recipientId OR settlementDetails (not both)<br>

```json
{"openapi":"3.0.3","info":{"title":"Orda API","version":"1.1.0"},"tags":[{"name":"Crypto-to-crypto","description":"Operations for handling direct and cross-chain transactions"}],"servers":[{"url":"https://api.orda.network/v1","description":"Default API path"}],"security":[{"ClientId":[],"Signature":[],"Timestamp":[]}],"components":{"securitySchemes":{"ClientId":{"type":"apiKey","in":"header","name":"x-client-id","description":"Your project client ID from orda dashboard"}},"parameters":{"ClientIdHeader":{"name":"x-client-id","in":"header","required":true,"description":"Your project client ID from orda dashboard","schema":{"type":"string","default":"prj_abc123def456ghi789"}},"SignatureHeader":{"name":"x-signature","in":"header","required":true,"description":"HMAC-SHA256 signature of canonical request body using your client secret","schema":{"type":"string","default":"a1b2c3d4e5f6789abc123def456ghi789abc123def456"}},"TimestampHeader":{"name":"x-timestamp","in":"header","required":false,"description":"Unix timestamp in milliseconds for replay protection (recommended)","schema":{"type":"string","default":"1704067200000"}}},"schemas":{"QuoteRequest":{"type":"object","required":["fromChain","fromToken","fromAddress","intent"],"properties":{"fromChain":{"type":"string","description":"Source blockchain chain ID"},"fromToken":{"type":"string","description":"Source token contract address"},"fromAddress":{"type":"string","description":"Source wallet address"},"intent":{"type":"object","required":["method","value"],"properties":{"method":{"type":"string","enum":["usd","fromAmount","toAmount"],"description":"Quote calculation method"},"value":{"type":"string","description":"Amount value for the specified method"}}},"recipientId":{"type":"string","description":"The ID of an existing recipient to send funds to (provide either this OR settlementDetails)"},"settlementDetails":{"type":"object","description":"Inline settlement details (provide either this OR recipientId)","properties":{"toChain":{"type":"string","description":"Destination blockchain chain ID"},"toToken":{"type":"string","description":"Destination token contract address"},"toAddress":{"type":"string","description":"Destination wallet address"}}}}},"QuoteResponse":{"type":"object","properties":{"message":{"type":"string","description":"Status message"},"transactionId":{"type":"string","description":"Transaction ID"},"quote":{"type":"object","nullable":true,"description":"Detailed provider quote. Returned on the routed (provider/bridge) path only; omitted on the direct-transfer path (when `providerQuoteDetails.isDirectTransfer` is `true`).","properties":{"provider":{"type":"string","description":"Provider used for the transaction"},"subProvider":{"type":"string","description":"Sub-provider used (e.g., specific DEX or bridge within an aggregator)","nullable":true},"providerRequestId":{"type":"string","description":"Provider-specific request ID"},"fromToken":{"type":"object","properties":{"address":{"type":"string","description":"Token contract address"},"decimals":{"type":"integer","description":"Token decimals"},"symbol":{"type":"string","description":"Token symbol"},"price":{"type":"number","description":"Token price in USD"},"chainId":{"type":"integer","description":"Chain ID where this token is located"}}},"toToken":{"type":"object","properties":{"address":{"type":"string","description":"Token contract address"},"decimals":{"type":"integer","description":"Token decimals"},"symbol":{"type":"string","description":"Token symbol"},"price":{"type":"number","description":"Token price in USD"},"chainId":{"type":"integer","description":"Chain ID where this token is located"}}},"fromAmount":{"type":"string","description":"Amount in source token"},"toAmount":{"type":"string","description":"Amount in destination token"},"fromAddress":{"type":"string","description":"Source wallet address"},"toAddress":{"type":"string","description":"Destination wallet address"},"estimatedDuration":{"type":"integer","description":"Estimated duration in minutes"},"fees":{"type":"object","properties":{"bridge":{"type":"object","description":"Bridge/relayer fee details","properties":{"amount":{"type":"string","description":"Fee amount in smallest token units"},"token":{"type":"string","description":"Token symbol for the fee"}}},"gas":{"type":"object","description":"Gas fee details","properties":{"amount":{"type":"string","description":"Gas fee amount in smallest token units"},"token":{"type":"string","description":"Token symbol for the gas fee"}}},"integrator":{"type":"string","description":"Integrator fee"},"maxSlippage":{"type":"number","nullable":true,"description":"Maximum slippage tolerance as a decimal (e.g., 0.01 for 1%). Null if not applicable."}}}}},"approvalTxParams":{"type":"object","nullable":true,"description":"ERC-20 approval transaction the client must sign before the main transaction. Returned on the routed (provider/bridge) path only; omitted on the direct-transfer path. May also be absent when no approval is required.","properties":{"from":{"type":"string","description":"Source address"},"to":{"type":"string","description":"Token contract address"},"gas":{"type":"string","description":"Gas limit"},"data":{"type":"string","description":"Transaction data"},"value":{"type":"string","description":"Transaction value"},"nonce":{"type":"integer","description":"Transaction nonce"}}},"transactionRequest":{"type":"object","properties":{"from":{"type":"string","description":"Source address"},"to":{"type":"string","description":"Destination address"},"data":{"type":"string","description":"Transaction data"},"value":{"type":"string","description":"Transaction value"},"chainId":{"type":"integer","description":"Chain ID"},"requestId":{"type":"string","description":"Request ID"},"gas":{"type":"string","description":"Gas limit"},"gasPrice":{"type":"string","description":"Gas price in hex wei. Present on the direct-transfer path."},"nonce":{"type":"string","description":"Sender account nonce in hex. Present on the direct-transfer path."},"maxFeePerGas":{"type":"string","description":"Maximum fee per gas"},"maxPriorityFeePerGas":{"type":"string","description":"Maximum priority fee per gas"}}},"feeTxParams":{"type":"object","nullable":true,"description":"Recipient-fee transaction the client must sign and broadcast in addition to the main transfer. Returned on the direct-transfer path only (when `providerQuoteDetails.isDirectTransfer` is `true`), and only when the organization has a non-zero recipient fee and a configured fee wallet. Null otherwise.","properties":{"from":{"type":"string","description":"Source address"},"to":{"type":"string","description":"Recipient of the transfer (fee wallet for native transfers, token contract address for ERC-20 transfers)"},"gas":{"type":"string","description":"Gas limit (hex-encoded)"},"gasPrice":{"type":"string","description":"Gas price (hex-encoded)"},"data":{"type":"string","description":"Transaction data ('0x' for native transfers, encoded ERC-20 transfer call otherwise)"},"nonce":{"type":"string","description":"Transaction nonce (hex-encoded)"},"value":{"type":"string","description":"Transaction value, hex-encoded (transfer amount for native transfers, '0x0' for ERC-20 transfers)"},"chainId":{"type":"integer","description":"Chain ID the fee transaction targets"}}},"providerQuoteDetails":{"type":"object","description":"Summary of the resolved quote, including which path produced it. Present on both the routed and direct-transfer paths.","properties":{"fromAmount":{"type":"string","description":"Resolved source amount in the source token's smallest unit"},"toAmount":{"type":"string","description":"Resolved destination amount in the destination token's smallest unit"},"isDirectTransfer":{"type":"boolean","description":"Whether the quote resolved to a same-chain direct transfer (`true`) or a routed provider/bridge transfer (`false`). When `true`, the response includes `transactionRequest` and (conditionally) `feeTxParams` but omits `quote` and `approvalTxParams`."},"provider":{"type":"string","description":"Provider that produced the quote ('Direct' on the direct-transfer path)"},"originalIntent":{"type":"object","description":"Echo of the intent supplied in the quote request","properties":{"method":{"type":"string","enum":["usd","fromAmount","toAmount"]},"value":{"type":"string"}}}}}}},"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error type identifier"},"message":{"type":"string","description":"Human-readable error message"},"correlationId":{"type":"string","description":"Request correlation ID for debugging"}}}}},"paths":{"/quote":{"post":{"summary":"Request a quote","description":"### Authentication\n\nAll API requests to orda require HMAC signatures using your project's client ID and client secret. To authenticate your quote request the signature is a HMAC-SHA256 hash of the request body, using your Client Secret as the key. Never share your Client Secret or include it directly in your client-side code.\n\n- Generate an `x-signature` header using your client secret.\n- Include your `x-client-id` in the request headers.\n\n#### Required Headers\n\n| Header | Description |\n|--------|-------------|\n| `x-client-id` | Your project's client ID |\n| `x-signature` | HMAC-SHA256 signature derived from your client secret |\n| `Content-Type` | `application/json` for this request |\n\n---\n\n**Intent Specification:**\nThe quote request uses an `intent` object to specify the amount calculation method:\n- `usd`: Calculate based on USD amount\n- `fromAmount`: Calculate based on source token amount  \n- `toAmount`: Calculate based on destination token amount\n\n**Important Notes:**\n- On the direct-transfer path the response `message` is `Direct transfer transaction prepared` (otherwise `Quote requested`)\n- Make sure you are using the correct token decimals for the token and chain when using toAmount and fromAmount intent methods\n- Users should request new quotes frequently for accurate pricing\n- The API uses rate limiting for all end points (10 requests per 5 minutes per project)\n- You must provide either recipientId OR settlementDetails (not both)\n","tags":["Crypto-to-crypto"],"parameters":[{"$ref":"#/components/parameters/ClientIdHeader"},{"$ref":"#/components/parameters/SignatureHeader"},{"$ref":"#/components/parameters/TimestampHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"}}}},"responses":{"200":{"description":"Quote generated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteResponse"}}}},"400":{"description":"Bad Request - Invalid or missing parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - Invalid API key or signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found - Business or recipient not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Get transaction status

> Retrieve the status of a transaction by transaction ID, source hash, or destination hash.\
> At least one of these parameters must be provided.\
> \
> \### Authentication\
> \
> All API requests to orda require HMAC signatures using your project's client ID and client secret. The signature is a HMAC-SHA256 hash of the request body, using your Client Secret as the key. For GET or endpoints with no request body, use the string \`"{}"\` (canonical empty object) for the signature.\
> \
> \#### Required Headers\
> \
> \| Header | Description |\
> \|--------|-------------|\
> \| \`x-client-id\` | Your project's client ID |\
> \| \`x-signature\` | HMAC-SHA256 signature derived from your client secret |\
> \| \`Content-Type\` | \`application/json\` for this request |\
> \
> \---\
> \
> \*\*Status Values:\*\*\
> \- \`In\_progress\`: Cross-chain processing in progress\
> \- \`Completed\`: Transaction completed successfully\
> \- \`Failed\`: Transaction failed (internally-expired transactions are reported as \`Failed\`)\
> \- \`Refunded\`: Transaction was refunded<br>

```json
{"openapi":"3.0.3","info":{"title":"Orda API","version":"1.1.0"},"tags":[{"name":"Crypto-to-crypto","description":"Operations for handling direct and cross-chain transactions"}],"servers":[{"url":"https://api.orda.network/v1","description":"Default API path"}],"security":[{"ClientId":[],"Signature":[],"Timestamp":[]}],"components":{"securitySchemes":{"ClientId":{"type":"apiKey","in":"header","name":"x-client-id","description":"Your project client ID from orda dashboard"}},"parameters":{"ClientIdHeader":{"name":"x-client-id","in":"header","required":true,"description":"Your project client ID from orda dashboard","schema":{"type":"string","default":"prj_abc123def456ghi789"}},"SignatureHeader":{"name":"x-signature","in":"header","required":true,"description":"HMAC-SHA256 signature of canonical request body using your client secret","schema":{"type":"string","default":"a1b2c3d4e5f6789abc123def456ghi789abc123def456"}},"TimestampHeader":{"name":"x-timestamp","in":"header","required":false,"description":"Unix timestamp in milliseconds for replay protection (recommended)","schema":{"type":"string","default":"1704067200000"}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error type identifier"},"message":{"type":"string","description":"Human-readable error message"},"correlationId":{"type":"string","description":"Request correlation ID for debugging"}}}}},"paths":{"/status":{"get":{"summary":"Get transaction status","description":"Retrieve the status of a transaction by transaction ID, source hash, or destination hash.\nAt least one of these parameters must be provided.\n\n### Authentication\n\nAll API requests to orda require HMAC signatures using your project's client ID and client secret. The signature is a HMAC-SHA256 hash of the request body, using your Client Secret as the key. For GET or endpoints with no request body, use the string `\"{}\"` (canonical empty object) for the signature.\n\n#### Required Headers\n\n| Header | Description |\n|--------|-------------|\n| `x-client-id` | Your project's client ID |\n| `x-signature` | HMAC-SHA256 signature derived from your client secret |\n| `Content-Type` | `application/json` for this request |\n\n---\n\n**Status Values:**\n- `In_progress`: Cross-chain processing in progress\n- `Completed`: Transaction completed successfully\n- `Failed`: Transaction failed (internally-expired transactions are reported as `Failed`)\n- `Refunded`: Transaction was refunded\n","tags":["Crypto-to-crypto"],"parameters":[{"$ref":"#/components/parameters/ClientIdHeader"},{"$ref":"#/components/parameters/SignatureHeader"},{"$ref":"#/components/parameters/TimestampHeader"},{"name":"transactionId","in":"query","description":"Transaction ID from quote response","schema":{"type":"string","format":"uuid"}},{"name":"sourceHash","in":"query","description":"Source transaction hash","schema":{"type":"string"}},{"name":"destinationHash","in":"query","description":"Destination transaction hash","schema":{"type":"string"}}],"responses":{"200":{"description":"Transaction status retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"requestSuccess":{"type":"boolean"},"transaction":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["In_progress","Completed","Failed","Refunded"]},"type":{"type":"string","enum":["Direct","LiFi","Relay","Wormhole","Transfero"]},"fromChain":{"type":"string"},"toChain":{"type":"string"},"fromToken":{"type":"string"},"toToken":{"type":"string"},"fromAmount":{"type":"string"},"usdAmount":{"type":"number"},"sourceTransactionHash":{"type":"string"},"destinationTransactionHash":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Bad request - Missing required parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Transaction not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## List successful transactions

> Returns all completed transactions for your organization.\
> \### Authentication\
> \
> All API requests to orda require HMAC signatures using your project's client ID and client secret. The signature is a HMAC-SHA256 hash of the request body, using your Client Secret as the key. For GET or endpoints with no request body, use the string \`"{}"\` (canonical empty object) for the signature.\
> \
> \#### Required Headers\
> \
> \| Header | Description |\
> \|--------|-------------|\
> \| \`x-client-id\` | Your project's client ID |\
> \| \`x-signature\` | HMAC-SHA256 signature derived from your client secret |\
> \| \`Content-Type\` | \`application/json\` for this request |\
> \
> \---\
> \
> \*\*Notes:\*\*\
> \- Transactions are sorted by creation date (newest first)\
> \- Results include both direct transfers and cross-chain swaps\
> \- Scope is your entire organization; only \`Completed\` transactions are returned<br>

```json
{"openapi":"3.0.3","info":{"title":"Orda API","version":"1.1.0"},"tags":[{"name":"Crypto-to-crypto","description":"Operations for handling direct and cross-chain transactions"}],"servers":[{"url":"https://api.orda.network/v1","description":"Default API path"}],"security":[{"ClientId":[],"Signature":[],"Timestamp":[]}],"components":{"securitySchemes":{"ClientId":{"type":"apiKey","in":"header","name":"x-client-id","description":"Your project client ID from orda dashboard"}},"parameters":{"ClientIdHeader":{"name":"x-client-id","in":"header","required":true,"description":"Your project client ID from orda dashboard","schema":{"type":"string","default":"prj_abc123def456ghi789"}},"SignatureHeader":{"name":"x-signature","in":"header","required":true,"description":"HMAC-SHA256 signature of canonical request body using your client secret","schema":{"type":"string","default":"a1b2c3d4e5f6789abc123def456ghi789abc123def456"}},"TimestampHeader":{"name":"x-timestamp","in":"header","required":false,"description":"Unix timestamp in milliseconds for replay protection (recommended)","schema":{"type":"string","default":"1704067200000"}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error type identifier"},"message":{"type":"string","description":"Human-readable error message"},"correlationId":{"type":"string","description":"Request correlation ID for debugging"}}}}},"paths":{"/successful-transactions":{"get":{"summary":"List successful transactions","description":"Returns all completed transactions for your organization.\n### Authentication\n\nAll API requests to orda require HMAC signatures using your project's client ID and client secret. The signature is a HMAC-SHA256 hash of the request body, using your Client Secret as the key. For GET or endpoints with no request body, use the string `\"{}\"` (canonical empty object) for the signature.\n\n#### Required Headers\n\n| Header | Description |\n|--------|-------------|\n| `x-client-id` | Your project's client ID |\n| `x-signature` | HMAC-SHA256 signature derived from your client secret |\n| `Content-Type` | `application/json` for this request |\n\n---\n\n**Notes:**\n- Transactions are sorted by creation date (newest first)\n- Results include both direct transfers and cross-chain swaps\n- Scope is your entire organization; only `Completed` transactions are returned\n","tags":["Crypto-to-crypto"],"parameters":[{"$ref":"#/components/parameters/ClientIdHeader"},{"$ref":"#/components/parameters/SignatureHeader"},{"$ref":"#/components/parameters/TimestampHeader"}],"responses":{"200":{"description":"Transactions retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"fromChain":{"type":"string"},"toChain":{"type":"string"},"fromToken":{"type":"string"},"toToken":{"type":"string"},"fromAmount":{"type":"string"},"toAmount":{"type":"string"},"usdAmount":{"type":"number"},"fromAddress":{"type":"string"},"toAddress":{"type":"string"},"type":{"type":"string","enum":["Direct","LiFi","Relay","Wormhole","Transfero"]},"fee":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"sourceTransactionHash":{"type":"string"},"destinationTransactionHash":{"type":"string"}}}}}}},"400":{"description":"Bad Request - API key is missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found - Business not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error - Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```


# Crypto To Fiat

Operations for crypto to fiat conversions (off-ramp)

## Request off-ramp quote

> \
> Generate a quote for converting cryptocurrency to fiat currency.\
> \
> You can provide either an existing recipientId or create a new recipient \
> by providing kycInformation and fiatSettlementDetails.\
> \### Authentication\
> \
> All API requests to orda require HMAC signatures using your project's client ID and client secret. The signature is a HMAC-SHA256 hash of the request body, using your Client Secret as the key. For GET or endpoints with no request body, use the string \`"{}"\` (canonical empty object) for the signature.\
> \
> \#### Required Headers\
> \
> \| Header | Description |\
> \|--------|-------------|\
> \| \`x-client-id\` | Your project's client ID |\
> \| \`x-signature\` | HMAC-SHA256 signature derived from your client secret |\
> \| \`Content-Type\` | \`application/json\` for this request |\
> \
> \---\
> \
> \*\*Intent Specification:\*\*\
> The quote request uses an \`intent\` object to specify the amount calculation method:\
> \- \`usd\`: Calculate based on USD amount\
> \- \`fromAmount\`: Calculate based on source token amount  \
> \- \`toAmount\`: Calculate based on destination token amount\
> \
> \*\*Important Notes:\*\*\
> \- Provide EITHER \`recipientId\` OR both \`kycInformation\` and \`fiatSettlementDetails\` (not both options)\
> \- If a \`recipientId\` is provided, the system will use the recipient's pre-configured settlement details\
> \- If you provide \`kycInformation\` and \`fiatSettlementDetails\`, settlement details are provided inline\
> \- KYC information is required for compliance with financial regulations\
> \- Quotes have a limited validity period<br>

```json
{"openapi":"3.0.3","info":{"title":"Orda API","version":"1.1.0"},"tags":[{"name":"Crypto-to-fiat","description":"Operations for crypto to fiat conversions (off-ramp)"}],"servers":[{"url":"https://api.orda.network/v1","description":"Default API path"}],"security":[{"ClientId":[],"Signature":[],"Timestamp":[]}],"components":{"securitySchemes":{"ClientId":{"type":"apiKey","in":"header","name":"x-client-id","description":"Your project client ID from orda dashboard"}},"parameters":{"ClientIdHeader":{"name":"x-client-id","in":"header","required":true,"description":"Your project client ID from orda dashboard","schema":{"type":"string","default":"prj_abc123def456ghi789"}},"SignatureHeader":{"name":"x-signature","in":"header","required":true,"description":"HMAC-SHA256 signature of canonical request body using your client secret","schema":{"type":"string","default":"a1b2c3d4e5f6789abc123def456ghi789abc123def456"}},"TimestampHeader":{"name":"x-timestamp","in":"header","required":false,"description":"Unix timestamp in milliseconds for replay protection (recommended)","schema":{"type":"string","default":"1704067200000"}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error type identifier"},"message":{"type":"string","description":"Human-readable error message"},"correlationId":{"type":"string","description":"Request correlation ID for debugging"}}}}},"paths":{"/offramp/quote":{"post":{"summary":"Request off-ramp quote","description":"\nGenerate a quote for converting cryptocurrency to fiat currency.\n\nYou can provide either an existing recipientId or create a new recipient \nby providing kycInformation and fiatSettlementDetails.\n### Authentication\n\nAll API requests to orda require HMAC signatures using your project's client ID and client secret. The signature is a HMAC-SHA256 hash of the request body, using your Client Secret as the key. For GET or endpoints with no request body, use the string `\"{}\"` (canonical empty object) for the signature.\n\n#### Required Headers\n\n| Header | Description |\n|--------|-------------|\n| `x-client-id` | Your project's client ID |\n| `x-signature` | HMAC-SHA256 signature derived from your client secret |\n| `Content-Type` | `application/json` for this request |\n\n---\n\n**Intent Specification:**\nThe quote request uses an `intent` object to specify the amount calculation method:\n- `usd`: Calculate based on USD amount\n- `fromAmount`: Calculate based on source token amount  \n- `toAmount`: Calculate based on destination token amount\n\n**Important Notes:**\n- Provide EITHER `recipientId` OR both `kycInformation` and `fiatSettlementDetails` (not both options)\n- If a `recipientId` is provided, the system will use the recipient's pre-configured settlement details\n- If you provide `kycInformation` and `fiatSettlementDetails`, settlement details are provided inline\n- KYC information is required for compliance with financial regulations\n- Quotes have a limited validity period\n","tags":["Crypto-to-fiat"],"parameters":[{"$ref":"#/components/parameters/ClientIdHeader"},{"$ref":"#/components/parameters/SignatureHeader"},{"$ref":"#/components/parameters/TimestampHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fromChain","fromToken","fromAddress","intent"],"properties":{"fromChain":{"type":"string","description":"Source blockchain chain ID"},"fromToken":{"type":"string","description":"Source token contract address"},"fromAddress":{"type":"string","description":"Source wallet address"},"intent":{"type":"object","required":["method","value"],"properties":{"method":{"type":"string","enum":["usd","fromAmount","toAmount"],"description":"Quote calculation method"},"value":{"type":"string","description":"Amount value for the specified method"}},"description":"The `intent` object specifies the amount calculation method:\n- `usd`: Calculate based on USD amount (e.g., `10` for $10)\n- `fromAmount`: Calculate based on the source token amount in its smallest unit\n- `toAmount`: Calculate based on the destination token amount in its smallest unit\n\n**Token Amount Formatting:**\nAmounts for `fromAmount` and `toAmount` must be provided in the token's smallest unit, based on its decimal precision.\n- **ETH (18 decimals):** 1 ETH = 1e18 units (e.g., 2.5 ETH is \"2500000000000000000\")\n- **USDC (6 decimals):** 1 USDC = 1e6 units (e.g., 1000 USDC is \"1000000000\")\n- **BTC (8 decimals):** 1 BTC = 1e8 units\n"},"recipientId":{"type":"string","description":"The ID of the recipient to send funds to (provide either this OR kycInformation+fiatSettlementDetails)"},"kycInformation":{"type":"object","description":"KYC information for inline settlement (required with fiatSettlementDetails if not using recipientId)","properties":{"taxId":{"type":"string","description":"Tax identification number of the recipient. For Brazil\n(`taxIdCountry: 'BRA'`), send the CPF as 11 unformatted digits or the\nCNPJ as 14 unformatted digits — no dots, dashes, or slashes.\nFormatted values such as `023.717.365-46` are rejected with a 400\nvalidation error. Non-Brazilian `taxId` values are accepted as-is.\n"},"taxIdCountry":{"type":"string","description":"ISO 3166-1 alpha-3 country code for the tax ID (e.g. `BRA` for Brazil)"},"name":{"type":"string","description":"Full name of the recipient"},"email":{"type":"string","description":"Email address of the recipient"}}},"fiatSettlementDetails":{"type":"object","description":"Bank account and fiat currency details for inline settlement (required with kycInformation if not using recipientId)","properties":{"toCurrency":{"type":"string","description":"Destination fiat currency code"},"bankAccount":{"type":"string","description":"Bank account number"},"bankBranch":{"type":"string","description":"Bank's identifier"},"bankAccountType":{"type":"string","description":"The current account type in target bank"},"iban":{"type":"string","description":"International bank account number"},"pixKey":{"type":"string","description":"PIX key for Brazilian recipients. Supported types:\n  - email (e.g. `user@example.com`)\n  - E.164 phone (e.g. `+5511999999999`)\n  - random UUID / EVP (e.g. `123e4567-e89b-12d3-a456-426614174000`)\n  - CPF (11 digits, unformatted — e.g. `12345678901`)\n  - CNPJ (14 digits, unformatted — e.g. `12345678000190`)\n\nCPF/CNPJ keys must be digits only. Formatted values such as\n`023.717.365-46` or `12.345.678/0001-90` are rejected with a 400\nvalidation error — strip punctuation client-side before sending.\n"},"cbuCvu":{"type":"string","description":"CBU/CVU for Argentina"}}}}}}}},"responses":{"200":{"description":"Off-ramp quote generated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"transactionId":{"type":"string","format":"uuid"},"quote":{"type":"object","properties":{"provider":{"type":"string"},"providerRequestId":{"type":"string"},"fromToken":{"type":"object","description":"Source token information (enhanced with chainId, decimals, and price)","properties":{"chainId":{"type":"integer","description":"Chain ID where this token is located"},"address":{"type":"string","description":"Token contract address"},"symbol":{"type":"string","description":"Token symbol"},"decimals":{"type":"integer","description":"Token decimals"},"price":{"type":"number","description":"Token price in USD"}}},"toCurrency":{"type":"string"},"fromAmount":{"type":"string"},"toAmount":{"type":"string"},"exchangeRate":{"type":"string"},"fromAddress":{"type":"string"},"estimatedDuration":{"type":"integer","description":"Estimated processing time in seconds"},"fees":{"type":"object","nullable":true,"description":"Fee breakdown for the conversion. Only present when fromToken is not BRZ\n(i.e., when a swap/bridge is required). Not included for direct BRZ transfers.\n","properties":{"bridge":{"type":"object","description":"Bridge/relayer fee details","properties":{"amount":{"type":"string","description":"Fee amount in smallest token units"},"token":{"type":"string","description":"Token symbol for the fee"}}},"gas":{"type":"object","description":"Gas fee details","properties":{"amount":{"type":"string","description":"Gas fee amount in smallest token units"},"token":{"type":"string","description":"Token symbol for the gas fee"}}},"integrator":{"type":"number","description":"Integrator fee"},"maxSlippage":{"type":"number","nullable":true,"description":"Maximum slippage tolerance as a decimal. Null if not applicable."}}}}},"approvalTxParams":{"type":"object","nullable":true,"description":"ERC-20 approval transaction parameters. Null for direct BRZ transfers that do not require an allowance.","properties":{"from":{"type":"string"},"to":{"type":"string"},"gas":{"type":"string"},"data":{"type":"string"},"value":{"type":"string"},"nonce":{"type":"integer"}}},"transactionRequest":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"data":{"type":"string"},"value":{"type":"string"},"chainId":{"type":"integer"},"requestId":{"type":"string"},"maxFeePerGas":{"type":"string"},"maxPriorityFeePerGas":{"type":"string"}}}}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - Invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found - Business not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Get off-ramp status

> \## Authentication\
> \
> All API requests to orda require HMAC signatures using your project's client ID and client secret:\
> \
> \#### Required Headers\
> \
> \| Header | Description |\
> \|--------|-------------|\
> \| \`x-client-id\` | Your project's client ID |\
> \| \`x-signature\` | HMAC-SHA256 signature derived from your client secret |\
> \
> The signature is an HMAC-SHA256 hash of the request body, using your Client Secret as the key.\
> \
> \---\
> \
> Check the status of a crypto-to-fiat transaction.\
> \
> \*\*Status Values:\*\*\
> \- \`Processing\`: The crypto has been received and fiat conversion is in process\
> \- \`Completed\`: The fiat has been successfully sent to the recipient's bank account\
> \- \`Failed\`: The transaction failed\
> \- \`Refunded\`: The transaction was refunded<br>

```json
{"openapi":"3.0.3","info":{"title":"Orda API","version":"1.1.0"},"tags":[{"name":"Crypto-to-fiat","description":"Operations for crypto to fiat conversions (off-ramp)"}],"servers":[{"url":"https://api.orda.network/v1","description":"Default API path"}],"security":[{"ClientId":[],"Signature":[],"Timestamp":[]}],"components":{"securitySchemes":{"ClientId":{"type":"apiKey","in":"header","name":"x-client-id","description":"Your project client ID from orda dashboard"}},"parameters":{"ClientIdHeader":{"name":"x-client-id","in":"header","required":true,"description":"Your project client ID from orda dashboard","schema":{"type":"string","default":"prj_abc123def456ghi789"}},"SignatureHeader":{"name":"x-signature","in":"header","required":true,"description":"HMAC-SHA256 signature of canonical request body using your client secret","schema":{"type":"string","default":"a1b2c3d4e5f6789abc123def456ghi789abc123def456"}},"TimestampHeader":{"name":"x-timestamp","in":"header","required":false,"description":"Unix timestamp in milliseconds for replay protection (recommended)","schema":{"type":"string","default":"1704067200000"}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error type identifier"},"message":{"type":"string","description":"Human-readable error message"},"correlationId":{"type":"string","description":"Request correlation ID for debugging"}}}}},"paths":{"/offramp/status":{"get":{"summary":"Get off-ramp status","description":"## Authentication\n\nAll API requests to orda require HMAC signatures using your project's client ID and client secret:\n\n#### Required Headers\n\n| Header | Description |\n|--------|-------------|\n| `x-client-id` | Your project's client ID |\n| `x-signature` | HMAC-SHA256 signature derived from your client secret |\n\nThe signature is an HMAC-SHA256 hash of the request body, using your Client Secret as the key.\n\n---\n\nCheck the status of a crypto-to-fiat transaction.\n\n**Status Values:**\n- `Processing`: The crypto has been received and fiat conversion is in process\n- `Completed`: The fiat has been successfully sent to the recipient's bank account\n- `Failed`: The transaction failed\n- `Refunded`: The transaction was refunded\n","tags":["Crypto-to-fiat"],"parameters":[{"$ref":"#/components/parameters/ClientIdHeader"},{"$ref":"#/components/parameters/SignatureHeader"},{"$ref":"#/components/parameters/TimestampHeader"},{"name":"transactionId","in":"query","description":"UUID of the off-ramp transaction","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Transaction status retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["Processing","Completed","Failed","Refunded"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"depositAddress":{"type":"string"},"depositAmount":{"type":"string"},"depositTxHash":{"type":"string"},"withdrawalAmount":{"type":"string"},"withdrawalDetails":{"type":"object","description":"Details of the fiat withdrawal"}}}}}},"400":{"description":"Bad Request - Invalid or missing transactionId","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found - Transaction not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```


# Fiat To Crypto

Operations for fiat to crypto conversions (on-ramp)

## Request on-ramp quote

> Generate a quote for converting fiat currency to cryptocurrency.\
> \
> \### Authentication\
> \
> All API requests to Orda require HMAC signatures using your project's client ID and client secret. The signature is a HMAC-SHA256 hash of the request body, using your Client Secret as the key.\
> \
> \#### Required Headers\
> \
> \| Header | Description |\
> \|--------|-------------|\
> \| \`x-client-id\` | Your project's client ID |\
> \| \`x-signature\` | HMAC-SHA256 signature derived from your client secret |\
> \| \`Content-Type\` | \`application/json\` for this request |\
> \
> \---\
> \
> \*\*Intent Specification:\*\*\
> The quote request uses an \`intent\` object to specify the amount calculation method:\
> \- \`fromAmount\`: Specify exact fiat amount to spend\
> \- \`toAmount\`: Specify exact crypto amount to receive\
> \- \`usd\`: Specify USD value for conversion\
> \
> \*\*Important Notes:\*\*\
> \- Currently supports BRL to BRZ conversions\
> \- \`taxId\` and \`taxIdCountry\` are required: the fiat payer's Brazilian tax ID (CPF or CNPJ, digits only) and its ISO 3166-1 alpha-3 country code\
> \- Provide EITHER \`recipientId\` OR \`settlementDetails\` (not both)\
> \- If using \`recipientId\`, recipient must have crypto settlement details configured\
> \- If using \`settlementDetails\`, provide destination chain, token, and address inline\
> \- Quote includes PIX payment instructions for BRL\
> \- Quotes expire after 5-10 minutes (check \`expiresAt\` field)\
> \- Exchange rates include all fees<br>

```json
{"openapi":"3.0.3","info":{"title":"Orda API","version":"1.1.0"},"tags":[{"name":"Fiat-to-crypto","description":"Operations for fiat to crypto conversions (on-ramp)"}],"servers":[{"url":"https://api.orda.network/v1","description":"Default API path"}],"security":[{"ClientId":[],"Signature":[],"Timestamp":[]}],"components":{"securitySchemes":{"ClientId":{"type":"apiKey","in":"header","name":"x-client-id","description":"Your project client ID from orda dashboard"}},"parameters":{"ClientIdHeader":{"name":"x-client-id","in":"header","required":true,"description":"Your project client ID from orda dashboard","schema":{"type":"string","default":"prj_abc123def456ghi789"}},"SignatureHeader":{"name":"x-signature","in":"header","required":true,"description":"HMAC-SHA256 signature of canonical request body using your client secret","schema":{"type":"string","default":"a1b2c3d4e5f6789abc123def456ghi789abc123def456"}},"TimestampHeader":{"name":"x-timestamp","in":"header","required":false,"description":"Unix timestamp in milliseconds for replay protection (recommended)","schema":{"type":"string","default":"1704067200000"}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error type identifier"},"message":{"type":"string","description":"Human-readable error message"},"correlationId":{"type":"string","description":"Request correlation ID for debugging"}}}}},"paths":{"/onramp/quote":{"post":{"summary":"Request on-ramp quote","description":"Generate a quote for converting fiat currency to cryptocurrency.\n\n### Authentication\n\nAll API requests to Orda require HMAC signatures using your project's client ID and client secret. The signature is a HMAC-SHA256 hash of the request body, using your Client Secret as the key.\n\n#### Required Headers\n\n| Header | Description |\n|--------|-------------|\n| `x-client-id` | Your project's client ID |\n| `x-signature` | HMAC-SHA256 signature derived from your client secret |\n| `Content-Type` | `application/json` for this request |\n\n---\n\n**Intent Specification:**\nThe quote request uses an `intent` object to specify the amount calculation method:\n- `fromAmount`: Specify exact fiat amount to spend\n- `toAmount`: Specify exact crypto amount to receive\n- `usd`: Specify USD value for conversion\n\n**Important Notes:**\n- Currently supports BRL to BRZ conversions\n- `taxId` and `taxIdCountry` are required: the fiat payer's Brazilian tax ID (CPF or CNPJ, digits only) and its ISO 3166-1 alpha-3 country code\n- Provide EITHER `recipientId` OR `settlementDetails` (not both)\n- If using `recipientId`, recipient must have crypto settlement details configured\n- If using `settlementDetails`, provide destination chain, token, and address inline\n- Quote includes PIX payment instructions for BRL\n- Quotes expire after 5-10 minutes (check `expiresAt` field)\n- Exchange rates include all fees\n","tags":["Fiat-to-crypto"],"parameters":[{"$ref":"#/components/parameters/ClientIdHeader"},{"$ref":"#/components/parameters/SignatureHeader"},{"$ref":"#/components/parameters/TimestampHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fromCurrency","intent","taxId","taxIdCountry"],"properties":{"fromCurrency":{"type":"string","description":"Source fiat currency code (currently only \"BRL\" supported)","enum":["BRL"]},"intent":{"type":"object","required":["method","value"],"properties":{"method":{"type":"string","enum":["fromAmount","toAmount","usd"],"description":"Quote calculation method:\n- `fromAmount`: Exact fiat amount to spend\n- `toAmount`: Exact crypto amount to receive\n- `usd`: USD value for conversion\n"},"value":{"type":"string","description":"Amount value for the specified method"}}},"taxId":{"type":"string","description":"Fiat payer's Brazilian tax ID. CPF (11 digits) or CNPJ (14 digits), digits only with no punctuation."},"taxIdCountry":{"type":"string","description":"ISO 3166-1 alpha-3 country code, uppercase."},"recipientId":{"type":"string","description":"UUID of the recipient to receive cryptocurrency (provide either this OR settlementDetails)"},"settlementDetails":{"type":"object","description":"Inline crypto settlement details (provide either this OR recipientId)","properties":{"toChain":{"type":"string","description":"Destination blockchain chain ID"},"toToken":{"type":"string","description":"Destination token contract address (BRZ token)"},"toAddress":{"type":"string","description":"Destination wallet address"}}}}}}}},"responses":{"200":{"description":"On-ramp quote generated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"transactionId":{"type":"string"},"recipientName":{"type":"string","description":"Display name of the recipient (when a recipientId was supplied)"},"depositInstructions":{"type":"object","properties":{"method":{"type":"string","description":"Payment method (e.g., \"PIX\")"},"amount":{"type":"number","description":"Exact fiat amount to deposit"},"currency":{"type":"string","description":"Fiat currency code"},"pixQrCode":{"type":"string","description":"Base64-encoded PIX QR code (BRL only)"},"pixKey":{"type":"string","description":"PIX key value to send the deposit to (BRL only)"},"expiresAt":{"type":"string","format":"date-time","description":"ISO 8601 timestamp for quote expiration"},"referenceId":{"type":"string","description":"Reference ID for the deposit"}}},"quote":{"type":"object","properties":{"provider":{"type":"string","description":"Liquidity provider name"},"fromCurrency":{"type":"string","description":"Source fiat currency"},"toCrypto":{"type":"string","description":"Target cryptocurrency token address"},"toCryptoSymbol":{"type":"string","description":"Target cryptocurrency token symbol"},"toChain":{"type":"string","description":"Destination blockchain ID"},"fromAmount":{"type":"string","description":"Fiat amount"},"toAmount":{"type":"string","description":"Crypto amount to receive in the token's smallest units (integer string).\nFor example, BRZ on Solana has 4 decimals, so `\"102900\"` represents\n`10.29 BRZ`. Use `toAmountHumanReadable` for display.\n"},"toAmountHumanReadable":{"type":"string","description":"Human-readable crypto amount formatted with the token symbol.\nUse this for UI display. `toAmount` is the smallest-unit value.\n"},"tokenDecimals":{"type":"integer","description":"Number of decimal places for the target token. Required to convert\n`toAmount` (smallest units) to a human-readable value.\n"},"toAddress":{"type":"string","description":"Recipient's wallet address"},"exchangeRate":{"type":"number","description":"Current exchange rate"},"estimatedDuration":{"type":"integer","description":"Estimated processing time in seconds"}}}}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - Invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found - Recipient not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Bad Gateway - External service error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Get on-ramp status

> Check the status of a fiat-to-crypto transaction.\
> \
> \### Authentication\
> \
> All API requests to Orda require HMAC signatures using your project's client ID and client secret. The signature is a HMAC-SHA256 hash of the request body (use \`"{}"\` for GET requests), using your Client Secret as the key.\
> \
> \#### Required Headers\
> \
> \| Header | Description |\
> \|--------|-------------|\
> \| \`x-client-id\` | Your project's client ID |\
> \| \`x-signature\` | HMAC-SHA256 signature derived from your client secret |\
> \
> \---\
> \
> \*\*Status Values:\*\*\
> \- \`In\_progress\`: Payment pending or being processed\
> \- \`Completed\`: Cryptocurrency successfully delivered\
> \- \`Failed\`: Payment failed or was rejected\
> \- \`Refunded\`: Payment was refunded to the sender\
> \- \`Expired\`: Quote/order expired before the deposit completed\
> \
> \*\*Deposit Status Values:\*\*\
> \- \`Awaiting\_deposit\`: Order placed, waiting for the user's deposit\
> \- \`Deposit\_processing\`: Deposit being confirmed\
> \- \`Deposit\_received\`: Deposit confirmed\
> \- \`Converting\`: Currency conversion in progress\
> \- \`Sending\`: Crypto in transit to the destination wallet\
> \- \`Completed\`: Successfully delivered\
> \- \`Failed\`: Order could not be completed<br>

```json
{"openapi":"3.0.3","info":{"title":"Orda API","version":"1.1.0"},"tags":[{"name":"Fiat-to-crypto","description":"Operations for fiat to crypto conversions (on-ramp)"}],"servers":[{"url":"https://api.orda.network/v1","description":"Default API path"}],"security":[{"ClientId":[],"Signature":[],"Timestamp":[]}],"components":{"securitySchemes":{"ClientId":{"type":"apiKey","in":"header","name":"x-client-id","description":"Your project client ID from orda dashboard"}},"parameters":{"ClientIdHeader":{"name":"x-client-id","in":"header","required":true,"description":"Your project client ID from orda dashboard","schema":{"type":"string","default":"prj_abc123def456ghi789"}},"SignatureHeader":{"name":"x-signature","in":"header","required":true,"description":"HMAC-SHA256 signature of canonical request body using your client secret","schema":{"type":"string","default":"a1b2c3d4e5f6789abc123def456ghi789abc123def456"}},"TimestampHeader":{"name":"x-timestamp","in":"header","required":false,"description":"Unix timestamp in milliseconds for replay protection (recommended)","schema":{"type":"string","default":"1704067200000"}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error type identifier"},"message":{"type":"string","description":"Human-readable error message"},"correlationId":{"type":"string","description":"Request correlation ID for debugging"}}}}},"paths":{"/onramp/status":{"get":{"summary":"Get on-ramp status","description":"Check the status of a fiat-to-crypto transaction.\n\n### Authentication\n\nAll API requests to Orda require HMAC signatures using your project's client ID and client secret. The signature is a HMAC-SHA256 hash of the request body (use `\"{}\"` for GET requests), using your Client Secret as the key.\n\n#### Required Headers\n\n| Header | Description |\n|--------|-------------|\n| `x-client-id` | Your project's client ID |\n| `x-signature` | HMAC-SHA256 signature derived from your client secret |\n\n---\n\n**Status Values:**\n- `In_progress`: Payment pending or being processed\n- `Completed`: Cryptocurrency successfully delivered\n- `Failed`: Payment failed or was rejected\n- `Refunded`: Payment was refunded to the sender\n- `Expired`: Quote/order expired before the deposit completed\n\n**Deposit Status Values:**\n- `Awaiting_deposit`: Order placed, waiting for the user's deposit\n- `Deposit_processing`: Deposit being confirmed\n- `Deposit_received`: Deposit confirmed\n- `Converting`: Currency conversion in progress\n- `Sending`: Crypto in transit to the destination wallet\n- `Completed`: Successfully delivered\n- `Failed`: Order could not be completed\n","tags":["Fiat-to-crypto"],"parameters":[{"$ref":"#/components/parameters/ClientIdHeader"},{"$ref":"#/components/parameters/SignatureHeader"},{"$ref":"#/components/parameters/TimestampHeader"},{"name":"transactionId","in":"query","description":"UUID of the transaction to check","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Transaction status retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"transactionId":{"type":"string","description":"Unique transaction identifier"},"status":{"type":"string","enum":["In_progress","Completed","Failed","Refunded","Expired"],"description":"Current transaction status"},"type":{"type":"string","description":"Transaction type (always \"FIAT_TO_CRYPTO\")"},"fromCurrency":{"type":"string","description":"Source fiat currency"},"toCrypto":{"type":"string","description":"Target cryptocurrency token address"},"toChain":{"type":"string","description":"Destination blockchain ID"},"fiatAmount":{"type":"string","description":"Amount of fiat currency deposited"},"cryptoAmount":{"type":"string","description":"Amount of cryptocurrency to receive"},"settlementAddress":{"type":"string","description":"Recipient's wallet address"},"depositMethod":{"type":"string","description":"Payment method used (e.g., \"PIX\")"},"depositStatus":{"type":"string","description":"Current deposit status"},"transferoOrderId":{"type":"string","description":"Provider's order identifier"},"transferoReferenceId":{"type":"string","description":"Provider's reference ID"},"createdAt":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of transaction creation"},"updatedAt":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of last update"}}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - Invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found - Transaction not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```


# Recipients

Operations for managing recipient accounts

## Fetch recipients

> Retrieve a paginated list of recipients for the authenticated project. Only returns active recipients.\
> \
> \### Authentication\
> \
> All API requests to orda require HMAC signatures using your project's client ID and client secret. The signature is a HMAC-SHA256 hash of the string \`"{}"\` (no request body for GET requests), using your Client Secret as the key.\
> \
> \#### Required Headers\
> \
> \| Header | Description |\
> \|--------|-------------|\
> \| \`x-client-id\` | Your project's client ID |\
> \| \`x-signature\` | HMAC-SHA256 signature (hash of \`"{}"\` for GET requests) |\
> \
> \--\
> \
> \*\*Response Details:\*\*\
> \- Returns only \*\*active\*\* recipients (deactivated recipients are excluded)\
> \- Recipients are scoped to the authenticated project\
> \- Includes full settlement details (crypto and/or fiat)\
> \- Includes KYC information when available\
> \- Results are ordered alphabetically by recipient name\
> \- Smart wallet information included when recipient was created with generated smart wallet<br>

```json
{"openapi":"3.0.3","info":{"title":"Orda API","version":"1.1.0"},"tags":[{"name":"Recipients","description":"Operations for managing recipient accounts"}],"servers":[{"url":"https://api.orda.network/v1","description":"Default API path"}],"security":[{"ClientId":[],"Signature":[],"Timestamp":[]}],"components":{"securitySchemes":{"ClientId":{"type":"apiKey","in":"header","name":"x-client-id","description":"Your project client ID from orda dashboard"}},"parameters":{"ClientIdHeader":{"name":"x-client-id","in":"header","required":true,"description":"Your project client ID from orda dashboard","schema":{"type":"string","default":"prj_abc123def456ghi789"}},"SignatureHeader":{"name":"x-signature","in":"header","required":true,"description":"HMAC-SHA256 signature of canonical request body using your client secret","schema":{"type":"string","default":"a1b2c3d4e5f6789abc123def456ghi789abc123def456"}},"TimestampHeader":{"name":"x-timestamp","in":"header","required":false,"description":"Unix timestamp in milliseconds for replay protection (recommended)","schema":{"type":"string","default":"1704067200000"}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error type identifier"},"message":{"type":"string","description":"Human-readable error message"},"correlationId":{"type":"string","description":"Request correlation ID for debugging"}}}}},"paths":{"/recipients":{"get":{"summary":"Fetch recipients","description":"Retrieve a paginated list of recipients for the authenticated project. Only returns active recipients.\n\n### Authentication\n\nAll API requests to orda require HMAC signatures using your project's client ID and client secret. The signature is a HMAC-SHA256 hash of the string `\"{}\"` (no request body for GET requests), using your Client Secret as the key.\n\n#### Required Headers\n\n| Header | Description |\n|--------|-------------|\n| `x-client-id` | Your project's client ID |\n| `x-signature` | HMAC-SHA256 signature (hash of `\"{}\"` for GET requests) |\n\n--\n\n**Response Details:**\n- Returns only **active** recipients (deactivated recipients are excluded)\n- Recipients are scoped to the authenticated project\n- Includes full settlement details (crypto and/or fiat)\n- Includes KYC information when available\n- Results are ordered alphabetically by recipient name\n- Smart wallet information included when recipient was created with generated smart wallet\n","tags":["Recipients"],"parameters":[{"$ref":"#/components/parameters/ClientIdHeader"},{"$ref":"#/components/parameters/SignatureHeader"},{"$ref":"#/components/parameters/TimestampHeader"},{"name":"page","in":"query","description":"Page number for pagination","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","description":"Number of recipients per page","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"toAddress","in":"query","description":"Filter by destination wallet address of the recipient's crypto settlement","required":false,"schema":{"type":"string"}},{"name":"name","in":"query","description":"Filter by recipient name","required":false,"schema":{"type":"string"}},{"name":"pixKey","in":"query","description":"Filter by the PIX key on the recipient's fiat settlement","required":false,"schema":{"type":"string"}},{"name":"taxId","in":"query","description":"Filter by the tax ID on the recipient's KYC information","required":false,"schema":{"type":"string"}},{"name":"chainIds","in":"query","description":"Filter by one or more destination chain IDs of the recipient's crypto\nsettlement. Accepts a single chain ID, a comma-separated list\n(e.g. `1,8453,42161`), or a repeated array query parameter.\n","required":false,"schema":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}],"responses":{"200":{"description":"Recipients retrieved successfully","headers":{"X-Total-Count":{"description":"Total number of recipients","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique recipient identifier"},"name":{"type":"string","description":"Recipient name"},"isActive":{"type":"boolean","description":"Whether the recipient is active"},"projectId":{"type":"string","description":"Associated project ID"},"organizationId":{"type":"string","description":"Associated organization ID"},"smartWalletAddress":{"type":"string","nullable":true,"description":"Smart wallet address if generated"},"walletType":{"type":"string","enum":["ALCHEMY_SMART_WALLET","USER_PROVIDED"],"description":"Type of wallet"},"cryptoSettlement":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"toChain":{"type":"string","description":"Destination blockchain chain ID"},"toToken":{"type":"string","description":"Destination token address"},"toAddress":{"type":"string","description":"Destination wallet address"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"fiatSettlement":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"toCurrency":{"type":"string","description":"Fiat currency code"},"method":{"type":"string","enum":["PIX","IBAN","CBU","unknown"],"description":"Settlement method"},"pixDetails":{"type":"object","nullable":true,"properties":{"pixKey":{"type":"string"},"keyType":{"type":"string","nullable":true,"description":"Always returned as `null` on the public API.\nThe PIX key type is not persisted/derived for\nlist responses.\n"}}},"ibanDetails":{"type":"object","nullable":true,"properties":{"iban":{"type":"string"},"bankAccount":{"type":"string"},"bankBranch":{"type":"string"},"bankAccountType":{"type":"string"}}},"cbuDetails":{"type":"object","nullable":true,"properties":{"cbu":{"type":"string"},"cvu":{"type":"string"}}}}},"kycInformation":{"type":"object","nullable":true,"properties":{"taxId":{"type":"string","description":"Tax identification number of the recipient. For Brazil\n(`taxIdCountry: 'BRA'`), send the CPF as 11 unformatted digits or the\nCNPJ as 14 unformatted digits — no dots, dashes, or slashes.\nFormatted values such as `023.717.365-46` are rejected with a 400\nvalidation error. Non-Brazilian `taxId` values are accepted as-is.\n"},"taxIdCountry":{"type":"string","description":"Country code for tax ID (use 'BRA' for Brazil, ISO 3166-1 alpha-3)"},"name":{"type":"string","description":"Full name"},"email":{"type":"string","description":"Email address"}}},"createdAt":{"type":"string","format":"date-time","description":"Recipient creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}},"pagination":{"type":"object","properties":{"page":{"type":"integer","description":"Current page number"},"limit":{"type":"integer","description":"Number of items per page"},"totalCount":{"type":"integer","description":"Total number of recipients"},"totalPages":{"type":"integer","description":"Total number of pages"}}}}}}}},"401":{"description":"Unauthorized - Invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Create a recipient

> Create a new recipient for payments. Recipients can have crypto settlement details, \
> fiat settlement details with KYC information, or both.\
> \### Authentication\
> \
> All API requests to orda require HMAC signatures using your project's client ID and client secret. The signature is a HMAC-SHA256 hash of the request body, using your Client Secret as the key. For GET or endpoints with no request body, use the string \`"{}"\` (canonical empty object) for the signature.\
> \
> \#### Required Headers\
> \
> \| Header | Description |\
> \|--------|-------------|\
> \| \`x-client-id\` | Your project's client ID |\
> \| \`x-signature\` | HMAC-SHA256 signature derived from your client secret |\
> \| \`Content-Type\` | \`application/json\` for this request |\
> \
> \--\
> \
> \*\*Important Notes:\*\*\
> \- A \`name\` alone is \*\*not\*\* sufficient to create a recipient. You must also provide\
> &#x20; settlement details: either \`cryptoSettlementDetails\`, OR both\
> &#x20; \`fiatSettlementDetails\` and \`kycInformation\`. Requests with only a \`name\` are\
> &#x20; rejected with a 400 validation error.\
> \- The \`cryptoSettlementDetails\` object contains blockchain settlement information\
> \- The \`kycInformation\` object is required for \`fiatSettlementDetails\`\
> \- Both \`kycInformation\` and \`fiatSettlementDetails\` are optional for crypto-only transactions\
> \- You need a project client ID to create recipients<br>

```json
{"openapi":"3.0.3","info":{"title":"Orda API","version":"1.1.0"},"tags":[{"name":"Recipients","description":"Operations for managing recipient accounts"}],"servers":[{"url":"https://api.orda.network/v1","description":"Default API path"}],"security":[{"ClientId":[],"Signature":[],"Timestamp":[]}],"components":{"securitySchemes":{"ClientId":{"type":"apiKey","in":"header","name":"x-client-id","description":"Your project client ID from orda dashboard"}},"parameters":{"ClientIdHeader":{"name":"x-client-id","in":"header","required":true,"description":"Your project client ID from orda dashboard","schema":{"type":"string","default":"prj_abc123def456ghi789"}},"SignatureHeader":{"name":"x-signature","in":"header","required":true,"description":"HMAC-SHA256 signature of canonical request body using your client secret","schema":{"type":"string","default":"a1b2c3d4e5f6789abc123def456ghi789abc123def456"}},"TimestampHeader":{"name":"x-timestamp","in":"header","required":false,"description":"Unix timestamp in milliseconds for replay protection (recommended)","schema":{"type":"string","default":"1704067200000"}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error type identifier"},"message":{"type":"string","description":"Human-readable error message"},"correlationId":{"type":"string","description":"Request correlation ID for debugging"}}}}},"paths":{"/create-recipient":{"post":{"summary":"Create a recipient","description":"Create a new recipient for payments. Recipients can have crypto settlement details, \nfiat settlement details with KYC information, or both.\n### Authentication\n\nAll API requests to orda require HMAC signatures using your project's client ID and client secret. The signature is a HMAC-SHA256 hash of the request body, using your Client Secret as the key. For GET or endpoints with no request body, use the string `\"{}\"` (canonical empty object) for the signature.\n\n#### Required Headers\n\n| Header | Description |\n|--------|-------------|\n| `x-client-id` | Your project's client ID |\n| `x-signature` | HMAC-SHA256 signature derived from your client secret |\n| `Content-Type` | `application/json` for this request |\n\n--\n\n**Important Notes:**\n- A `name` alone is **not** sufficient to create a recipient. You must also provide\n  settlement details: either `cryptoSettlementDetails`, OR both\n  `fiatSettlementDetails` and `kycInformation`. Requests with only a `name` are\n  rejected with a 400 validation error.\n- The `cryptoSettlementDetails` object contains blockchain settlement information\n- The `kycInformation` object is required for `fiatSettlementDetails`\n- Both `kycInformation` and `fiatSettlementDetails` are optional for crypto-only transactions\n- You need a project client ID to create recipients\n","tags":["Recipients"],"parameters":[{"$ref":"#/components/parameters/ClientIdHeader"},{"$ref":"#/components/parameters/SignatureHeader"},{"$ref":"#/components/parameters/TimestampHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Name of the recipient"},"cryptoSettlementDetails":{"type":"object","description":"Crypto settlement details (optional - can be added later or provided during transaction)","required":["toChain","toToken","toAddress"],"properties":{"toChain":{"type":"string","description":"Destination blockchain chain ID"},"toToken":{"type":"string","description":"Destination token contract address"},"toAddress":{"type":"string","description":"Destination wallet address"}}},"kycInformation":{"type":"object","description":"KYC information for the recipient (required for fiat settlements)","properties":{"taxId":{"type":"string","description":"Tax identification number of the recipient. For Brazil\n(`taxIdCountry: 'BRA'`), send the CPF as 11 unformatted digits or the\nCNPJ as 14 unformatted digits — no dots, dashes, or slashes.\nFormatted values such as `023.717.365-46` are rejected with a 400\nvalidation error. Non-Brazilian `taxId` values are accepted as-is.\n"},"taxIdCountry":{"type":"string","description":"ISO 3166-1 alpha-3 country code for the tax ID (e.g. `BRA` for Brazil)"},"email":{"type":"string","description":"Email address of the recipient"},"name":{"type":"string","description":"Full name of the recipient"}}},"fiatSettlementDetails":{"type":"object","description":"Bank account and fiat currency details for fiat settlement (requires kycInformation)","properties":{"toCurrency":{"type":"string","description":"Destination fiat currency code"},"bankAccount":{"type":"string","description":"Bank account number"},"bankBranch":{"type":"string","description":"Bank's identifier"},"bankAccountType":{"type":"string","description":"The current account type in target bank"},"iban":{"type":"string","description":"International bank account number"},"pixKey":{"type":"string","description":"PIX key for Brazilian recipients. Supported types:\n  - email (e.g. `user@example.com`)\n  - E.164 phone (e.g. `+5511999999999`)\n  - random UUID / EVP (e.g. `123e4567-e89b-12d3-a456-426614174000`)\n  - CPF (11 digits, unformatted — e.g. `12345678901`)\n  - CNPJ (14 digits, unformatted — e.g. `12345678000190`)\n\nCPF/CNPJ keys must be digits only. Formatted values such as\n`023.717.365-46` or `12.345.678/0001-90` are rejected with a 400\nvalidation error — strip punctuation client-side before sending.\n"},"cbuCvu":{"type":"string","description":"CBU/CVU for Argentina"}}}}}}}},"responses":{"201":{"description":"Recipient created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"recipientId":{"type":"string","description":"Generated recipient ID"}}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - Invalid client ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found - Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict - Recipient with same name already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable Entity - Invalid data format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Update recipient details

> Update an existing recipient's settlement details.\
> \### Authentication\
> \
> All API requests to orda require HMAC signatures using your project's client ID and client secret. The signature is a HMAC-SHA256 hash of the request body, using your Client Secret as the key. For GET or endpoints with no request body, use the string \`"{}"\` (canonical empty object) for the signature.\
> \
> \#### Required Headers\
> \
> \| Header | Description |\
> \|--------|-------------|\
> \| \`x-client-id\` | Your project's client ID |\
> \| \`x-signature\` | HMAC-SHA256 signature derived from your client secret |\
> \| \`Content-Type\` | \`application/json\` for this request |\
> \
> \---\
> \
> \*\*Important Notes:\*\*\
> \- The recipient ID will remain the same despite settlement details changing\
> \- The response includes previously stored settlement details for audit trail\
> \- You need the project's client ID to update recipients<br>

```json
{"openapi":"3.0.3","info":{"title":"Orda API","version":"1.1.0"},"tags":[{"name":"Recipients","description":"Operations for managing recipient accounts"}],"servers":[{"url":"https://api.orda.network/v1","description":"Default API path"}],"security":[{"ClientId":[],"Signature":[],"Timestamp":[]}],"components":{"securitySchemes":{"ClientId":{"type":"apiKey","in":"header","name":"x-client-id","description":"Your project client ID from orda dashboard"}},"parameters":{"ClientIdHeader":{"name":"x-client-id","in":"header","required":true,"description":"Your project client ID from orda dashboard","schema":{"type":"string","default":"prj_abc123def456ghi789"}},"SignatureHeader":{"name":"x-signature","in":"header","required":true,"description":"HMAC-SHA256 signature of canonical request body using your client secret","schema":{"type":"string","default":"a1b2c3d4e5f6789abc123def456ghi789abc123def456"}},"TimestampHeader":{"name":"x-timestamp","in":"header","required":false,"description":"Unix timestamp in milliseconds for replay protection (recommended)","schema":{"type":"string","default":"1704067200000"}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error type identifier"},"message":{"type":"string","description":"Human-readable error message"},"correlationId":{"type":"string","description":"Request correlation ID for debugging"}}}}},"paths":{"/update-recipient":{"put":{"summary":"Update recipient details","description":"Update an existing recipient's settlement details.\n### Authentication\n\nAll API requests to orda require HMAC signatures using your project's client ID and client secret. The signature is a HMAC-SHA256 hash of the request body, using your Client Secret as the key. For GET or endpoints with no request body, use the string `\"{}\"` (canonical empty object) for the signature.\n\n#### Required Headers\n\n| Header | Description |\n|--------|-------------|\n| `x-client-id` | Your project's client ID |\n| `x-signature` | HMAC-SHA256 signature derived from your client secret |\n| `Content-Type` | `application/json` for this request |\n\n---\n\n**Important Notes:**\n- The recipient ID will remain the same despite settlement details changing\n- The response includes previously stored settlement details for audit trail\n- You need the project's client ID to update recipients\n","tags":["Recipients"],"parameters":[{"$ref":"#/components/parameters/ClientIdHeader"},{"$ref":"#/components/parameters/SignatureHeader"},{"$ref":"#/components/parameters/TimestampHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["recipientId"],"properties":{"recipientId":{"type":"string","description":"ID of the recipient to update"},"cryptoSettlementDetails":{"type":"object","properties":{"toChain":{"type":"string"},"toToken":{"type":"string"},"toAddress":{"type":"string"}}},"kycInformation":{"type":"object","properties":{"taxId":{"type":"string","description":"Tax identification number of the recipient. For Brazil\n(`taxIdCountry: 'BRA'`), send the CPF as 11 unformatted digits or the\nCNPJ as 14 unformatted digits — no dots, dashes, or slashes.\nFormatted values such as `023.717.365-46` are rejected with a 400\nvalidation error. Non-Brazilian `taxId` values are accepted as-is.\n"},"taxIdCountry":{"type":"string","description":"ISO 3166-1 alpha-3 country code for the tax ID (e.g. `BRA` for Brazil)"},"email":{"type":"string"},"name":{"type":"string"}}},"fiatSettlementDetails":{"type":"object","properties":{"toCurrency":{"type":"string"},"bankAccount":{"type":"string"},"bankBranch":{"type":"string"},"bankAccountType":{"type":"string"},"iban":{"type":"string"},"pixKey":{"type":"string","description":"PIX key for Brazilian recipients. Supported types:\n  - email (e.g. `user@example.com`)\n  - E.164 phone (e.g. `+5511999999999`)\n  - random UUID / EVP (e.g. `123e4567-e89b-12d3-a456-426614174000`)\n  - CPF (11 digits, unformatted — e.g. `12345678901`)\n  - CNPJ (14 digits, unformatted — e.g. `12345678000190`)\n\nCPF/CNPJ keys must be digits only. Formatted values such as\n`023.717.365-46` or `12.345.678/0001-90` are rejected with a 400\nvalidation error — strip punctuation client-side before sending.\n"},"cbuCvu":{"type":"string"}}}}}}}},"responses":{"200":{"description":"Recipient updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"previousDetails":{"type":"object","description":"Snapshot of the recipient's settlement details before this update,\ncaptured for audit purposes. Only the settlement types that were\nchanged are present; unchanged sections are omitted.\n","properties":{"crypto":{"type":"object","description":"Previous crypto settlement details (present only if crypto settlement was updated)","properties":{"toChain":{"type":"string"},"toToken":{"type":"string"},"toAddress":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"}}},"fiat":{"type":"object","description":"Previous fiat settlement details (present only if fiat settlement was updated)","properties":{"toCurrency":{"type":"string","nullable":true},"bankAccount":{"type":"string","nullable":true},"bankBranch":{"type":"string","nullable":true},"bankAccountType":{"type":"string","nullable":true},"iban":{"type":"string","nullable":true},"pixKey":{"type":"string","nullable":true},"cbuCvu":{"type":"string","nullable":true,"description":"Previous CBU and CVU joined as `cbu,cvu`"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - Invalid client ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found - Recipient not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable Entity - Invalid data format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Deactivate a recipient

> \
> Deactivate a recipient to prevent it from processing further transactions.\
> Existing transactions will not be affected.\
> \### Authentication\
> \
> All API requests to orda require HMAC signatures using your project's client ID and client secret. The signature is a HMAC-SHA256 hash of the request body, using your Client Secret as the key. For GET or endpoints with no request body, use the string \`"{}"\` (canonical empty object) for the signature.\
> \
> \#### Required Headers\
> \
> \| Header | Description |\
> \|--------|-------------|\
> \| \`x-client-id\` | Your project's client ID |\
> \| \`x-signature\` | HMAC-SHA256 signature derived from your client secret |\
> \| \`Content-Type\` | \`application/json\` for this request |\
> \
> \---\
> \
> \*\*Important Notes:\*\*\
> \- Only the business can deactivate their recipients\
> \- New transactions using the deactivated recipient's ID will be rejected<br>

```json
{"openapi":"3.0.3","info":{"title":"Orda API","version":"1.1.0"},"tags":[{"name":"Recipients","description":"Operations for managing recipient accounts"}],"servers":[{"url":"https://api.orda.network/v1","description":"Default API path"}],"security":[{"ClientId":[],"Signature":[],"Timestamp":[]}],"components":{"securitySchemes":{"ClientId":{"type":"apiKey","in":"header","name":"x-client-id","description":"Your project client ID from orda dashboard"}},"parameters":{"ClientIdHeader":{"name":"x-client-id","in":"header","required":true,"description":"Your project client ID from orda dashboard","schema":{"type":"string","default":"prj_abc123def456ghi789"}},"SignatureHeader":{"name":"x-signature","in":"header","required":true,"description":"HMAC-SHA256 signature of canonical request body using your client secret","schema":{"type":"string","default":"a1b2c3d4e5f6789abc123def456ghi789abc123def456"}},"TimestampHeader":{"name":"x-timestamp","in":"header","required":false,"description":"Unix timestamp in milliseconds for replay protection (recommended)","schema":{"type":"string","default":"1704067200000"}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error type identifier"},"message":{"type":"string","description":"Human-readable error message"},"correlationId":{"type":"string","description":"Request correlation ID for debugging"}}}}},"paths":{"/deactivate-recipient":{"put":{"summary":"Deactivate a recipient","description":"\nDeactivate a recipient to prevent it from processing further transactions.\nExisting transactions will not be affected.\n### Authentication\n\nAll API requests to orda require HMAC signatures using your project's client ID and client secret. The signature is a HMAC-SHA256 hash of the request body, using your Client Secret as the key. For GET or endpoints with no request body, use the string `\"{}\"` (canonical empty object) for the signature.\n\n#### Required Headers\n\n| Header | Description |\n|--------|-------------|\n| `x-client-id` | Your project's client ID |\n| `x-signature` | HMAC-SHA256 signature derived from your client secret |\n| `Content-Type` | `application/json` for this request |\n\n---\n\n**Important Notes:**\n- Only the business can deactivate their recipients\n- New transactions using the deactivated recipient's ID will be rejected\n","tags":["Recipients"],"parameters":[{"$ref":"#/components/parameters/ClientIdHeader"},{"$ref":"#/components/parameters/SignatureHeader"},{"$ref":"#/components/parameters/TimestampHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["recipientId"],"properties":{"recipientId":{"type":"string","description":"ID of the recipient to deactivate"}}}}}},"responses":{"200":{"description":"Recipient deactivated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"recipientId":{"type":"string","description":"ID of the deactivated recipient"},"recipientName":{"type":"string"},"deactivatedAt":{"type":"string","format":"date-time"}}}}}}}},"400":{"description":"Bad Request - Missing recipient ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found - Recipient not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```


# Discovery

Operations for discovering supported chains and tokens

## List supported chains

> Discover the blockchains supported by the orda platform. Returns the\
> active chain catalog used for crypto-to-crypto, off-ramp, and on-ramp\
> flows. Results are cached for 5 minutes.\
> \
> Use the optional \`chainId\` and \`chainType\` query parameters to filter\
> the catalog. Both accept comma-separated values.<br>

```json
{"openapi":"3.0.3","info":{"title":"Orda API","version":"1.1.0"},"tags":[{"name":"Discovery","description":"Operations for discovering supported chains and tokens"}],"servers":[{"url":"https://api.orda.network/v1","description":"Default API path"}],"security":[{"ClientId":[],"Signature":[],"Timestamp":[]}],"components":{"securitySchemes":{"ClientId":{"type":"apiKey","in":"header","name":"x-client-id","description":"Your project client ID from orda dashboard"}},"parameters":{"ClientIdHeader":{"name":"x-client-id","in":"header","required":true,"description":"Your project client ID from orda dashboard","schema":{"type":"string","default":"prj_abc123def456ghi789"}},"SignatureHeader":{"name":"x-signature","in":"header","required":true,"description":"HMAC-SHA256 signature of canonical request body using your client secret","schema":{"type":"string","default":"a1b2c3d4e5f6789abc123def456ghi789abc123def456"}},"TimestampHeader":{"name":"x-timestamp","in":"header","required":false,"description":"Unix timestamp in milliseconds for replay protection (recommended)","schema":{"type":"string","default":"1704067200000"}}}},"paths":{"/chains":{"get":{"summary":"List supported chains","description":"Discover the blockchains supported by the orda platform. Returns the\nactive chain catalog used for crypto-to-crypto, off-ramp, and on-ramp\nflows. Results are cached for 5 minutes.\n\nUse the optional `chainId` and `chainType` query parameters to filter\nthe catalog. Both accept comma-separated values.\n","tags":["Discovery"],"parameters":[{"$ref":"#/components/parameters/ClientIdHeader"},{"$ref":"#/components/parameters/SignatureHeader"},{"$ref":"#/components/parameters/TimestampHeader"},{"name":"chainId","in":"query","required":false,"description":"Comma-separated list of chain IDs to filter by (positive integers).","schema":{"type":"string"}},{"name":"chainType","in":"query","required":false,"description":"Comma-separated list of chain types to filter by.","schema":{"type":"string"}}],"responses":{"200":{"description":"List of supported chains","content":{"application/json":{"schema":{"type":"object","properties":{"chains":{"type":"array","items":{"type":"object","properties":{"chainId":{"type":"integer","description":"Numeric chain identifier. EVM chains use their standard ID; non-EVM chains use the 100XXXX format."},"name":{"type":"string"},"displayName":{"type":"string"},"chainType":{"type":"string"},"nativeCurrency":{"type":"object","properties":{"name":{"type":"string"},"symbol":{"type":"string"},"decimals":{"type":"integer"}}},"blockExplorerUrl":{"type":"string","nullable":true},"logoUrl":{"type":"string","nullable":true}}}}}}}}},"401":{"description":"Authentication failed (missing or invalid credentials)"},"403":{"description":"Missing the required `chains:read` permission"}}}}}}
```

## List supported tokens

> Discover the tokens supported by the orda platform. Returns a paginated,\
> filterable list of active tokens. Results are cached for 5 minutes.\
> \
> Filter with the optional \`chainId\`, \`symbol\`, and \`featured\` query\
> parameters (\`chainId\` and \`symbol\` accept comma-separated values), and\
> page through results with \`page\` and \`limit\`.<br>

```json
{"openapi":"3.0.3","info":{"title":"Orda API","version":"1.1.0"},"tags":[{"name":"Discovery","description":"Operations for discovering supported chains and tokens"}],"servers":[{"url":"https://api.orda.network/v1","description":"Default API path"}],"security":[{"ClientId":[],"Signature":[],"Timestamp":[]}],"components":{"securitySchemes":{"ClientId":{"type":"apiKey","in":"header","name":"x-client-id","description":"Your project client ID from orda dashboard"}},"parameters":{"ClientIdHeader":{"name":"x-client-id","in":"header","required":true,"description":"Your project client ID from orda dashboard","schema":{"type":"string","default":"prj_abc123def456ghi789"}},"SignatureHeader":{"name":"x-signature","in":"header","required":true,"description":"HMAC-SHA256 signature of canonical request body using your client secret","schema":{"type":"string","default":"a1b2c3d4e5f6789abc123def456ghi789abc123def456"}},"TimestampHeader":{"name":"x-timestamp","in":"header","required":false,"description":"Unix timestamp in milliseconds for replay protection (recommended)","schema":{"type":"string","default":"1704067200000"}}}},"paths":{"/tokens":{"get":{"summary":"List supported tokens","description":"Discover the tokens supported by the orda platform. Returns a paginated,\nfilterable list of active tokens. Results are cached for 5 minutes.\n\nFilter with the optional `chainId`, `symbol`, and `featured` query\nparameters (`chainId` and `symbol` accept comma-separated values), and\npage through results with `page` and `limit`.\n","tags":["Discovery"],"parameters":[{"$ref":"#/components/parameters/ClientIdHeader"},{"$ref":"#/components/parameters/SignatureHeader"},{"$ref":"#/components/parameters/TimestampHeader"},{"name":"chainId","in":"query","required":false,"description":"Comma-separated list of chain IDs to filter by (positive integers).","schema":{"type":"string"}},{"name":"symbol","in":"query","required":false,"description":"Comma-separated list of token symbols to filter by (max 50 chars each).","schema":{"type":"string"}},{"name":"featured","in":"query","required":false,"description":"Whether to return only featured tokens, only non-featured, or all. Applied only when the token whitelist is enabled.","schema":{"type":"string","enum":["true","false","all"],"default":"true"}},{"name":"page","in":"query","required":false,"description":"Page number (1-based).","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","required":false,"description":"Number of tokens per page (max 1000).","schema":{"type":"integer","minimum":1,"maximum":1000,"default":100}}],"responses":{"200":{"description":"Paginated list of supported tokens","content":{"application/json":{"schema":{"type":"object","properties":{"tokens":{"type":"array","items":{"type":"object","properties":{"chainId":{"type":"integer"},"address":{"type":"string","description":"Token contract address. The zero/native sentinel address is used for native gas tokens."},"symbol":{"type":"string"},"name":{"type":"string"},"decimals":{"type":"integer"},"logoUrl":{"type":"string","nullable":true}}}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"},"hasNext":{"type":"boolean"},"hasPrev":{"type":"boolean"}}},"meta":{"type":"object","properties":{"filtered":{"type":"string","enum":["featured","non-featured","all"]},"totalFeatured":{"type":"integer"},"totalAll":{"type":"integer"}}}}}}}},"401":{"description":"Authentication failed (missing or invalid credentials)"},"403":{"description":"Missing the required `tokens:read` permission"}}}}}}
```


# Models

## The Error object

```json
{"openapi":"3.0.3","info":{"title":"Orda API","version":"1.1.0"},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error type identifier"},"message":{"type":"string","description":"Human-readable error message"},"correlationId":{"type":"string","description":"Request correlation ID for debugging"}}}}}}
```

## The QuoteRequest object

```json
{"openapi":"3.0.3","info":{"title":"Orda API","version":"1.1.0"},"components":{"schemas":{"QuoteRequest":{"type":"object","required":["fromChain","fromToken","fromAddress","intent"],"properties":{"fromChain":{"type":"string","description":"Source blockchain chain ID"},"fromToken":{"type":"string","description":"Source token contract address"},"fromAddress":{"type":"string","description":"Source wallet address"},"intent":{"type":"object","required":["method","value"],"properties":{"method":{"type":"string","enum":["usd","fromAmount","toAmount"],"description":"Quote calculation method"},"value":{"type":"string","description":"Amount value for the specified method"}}},"recipientId":{"type":"string","description":"The ID of an existing recipient to send funds to (provide either this OR settlementDetails)"},"settlementDetails":{"type":"object","description":"Inline settlement details (provide either this OR recipientId)","properties":{"toChain":{"type":"string","description":"Destination blockchain chain ID"},"toToken":{"type":"string","description":"Destination token contract address"},"toAddress":{"type":"string","description":"Destination wallet address"}}}}}}}}
```

## The QuoteResponse object

```json
{"openapi":"3.0.3","info":{"title":"Orda API","version":"1.1.0"},"components":{"schemas":{"QuoteResponse":{"type":"object","properties":{"message":{"type":"string","description":"Status message"},"transactionId":{"type":"string","description":"Transaction ID"},"quote":{"type":"object","nullable":true,"description":"Detailed provider quote. Returned on the routed (provider/bridge) path only; omitted on the direct-transfer path (when `providerQuoteDetails.isDirectTransfer` is `true`).","properties":{"provider":{"type":"string","description":"Provider used for the transaction"},"subProvider":{"type":"string","description":"Sub-provider used (e.g., specific DEX or bridge within an aggregator)","nullable":true},"providerRequestId":{"type":"string","description":"Provider-specific request ID"},"fromToken":{"type":"object","properties":{"address":{"type":"string","description":"Token contract address"},"decimals":{"type":"integer","description":"Token decimals"},"symbol":{"type":"string","description":"Token symbol"},"price":{"type":"number","description":"Token price in USD"},"chainId":{"type":"integer","description":"Chain ID where this token is located"}}},"toToken":{"type":"object","properties":{"address":{"type":"string","description":"Token contract address"},"decimals":{"type":"integer","description":"Token decimals"},"symbol":{"type":"string","description":"Token symbol"},"price":{"type":"number","description":"Token price in USD"},"chainId":{"type":"integer","description":"Chain ID where this token is located"}}},"fromAmount":{"type":"string","description":"Amount in source token"},"toAmount":{"type":"string","description":"Amount in destination token"},"fromAddress":{"type":"string","description":"Source wallet address"},"toAddress":{"type":"string","description":"Destination wallet address"},"estimatedDuration":{"type":"integer","description":"Estimated duration in minutes"},"fees":{"type":"object","properties":{"bridge":{"type":"object","description":"Bridge/relayer fee details","properties":{"amount":{"type":"string","description":"Fee amount in smallest token units"},"token":{"type":"string","description":"Token symbol for the fee"}}},"gas":{"type":"object","description":"Gas fee details","properties":{"amount":{"type":"string","description":"Gas fee amount in smallest token units"},"token":{"type":"string","description":"Token symbol for the gas fee"}}},"integrator":{"type":"string","description":"Integrator fee"},"maxSlippage":{"type":"number","nullable":true,"description":"Maximum slippage tolerance as a decimal (e.g., 0.01 for 1%). Null if not applicable."}}}}},"approvalTxParams":{"type":"object","nullable":true,"description":"ERC-20 approval transaction the client must sign before the main transaction. Returned on the routed (provider/bridge) path only; omitted on the direct-transfer path. May also be absent when no approval is required.","properties":{"from":{"type":"string","description":"Source address"},"to":{"type":"string","description":"Token contract address"},"gas":{"type":"string","description":"Gas limit"},"data":{"type":"string","description":"Transaction data"},"value":{"type":"string","description":"Transaction value"},"nonce":{"type":"integer","description":"Transaction nonce"}}},"transactionRequest":{"type":"object","properties":{"from":{"type":"string","description":"Source address"},"to":{"type":"string","description":"Destination address"},"data":{"type":"string","description":"Transaction data"},"value":{"type":"string","description":"Transaction value"},"chainId":{"type":"integer","description":"Chain ID"},"requestId":{"type":"string","description":"Request ID"},"gas":{"type":"string","description":"Gas limit"},"gasPrice":{"type":"string","description":"Gas price in hex wei. Present on the direct-transfer path."},"nonce":{"type":"string","description":"Sender account nonce in hex. Present on the direct-transfer path."},"maxFeePerGas":{"type":"string","description":"Maximum fee per gas"},"maxPriorityFeePerGas":{"type":"string","description":"Maximum priority fee per gas"}}},"feeTxParams":{"type":"object","nullable":true,"description":"Recipient-fee transaction the client must sign and broadcast in addition to the main transfer. Returned on the direct-transfer path only (when `providerQuoteDetails.isDirectTransfer` is `true`), and only when the organization has a non-zero recipient fee and a configured fee wallet. Null otherwise.","properties":{"from":{"type":"string","description":"Source address"},"to":{"type":"string","description":"Recipient of the transfer (fee wallet for native transfers, token contract address for ERC-20 transfers)"},"gas":{"type":"string","description":"Gas limit (hex-encoded)"},"gasPrice":{"type":"string","description":"Gas price (hex-encoded)"},"data":{"type":"string","description":"Transaction data ('0x' for native transfers, encoded ERC-20 transfer call otherwise)"},"nonce":{"type":"string","description":"Transaction nonce (hex-encoded)"},"value":{"type":"string","description":"Transaction value, hex-encoded (transfer amount for native transfers, '0x0' for ERC-20 transfers)"},"chainId":{"type":"integer","description":"Chain ID the fee transaction targets"}}},"providerQuoteDetails":{"type":"object","description":"Summary of the resolved quote, including which path produced it. Present on both the routed and direct-transfer paths.","properties":{"fromAmount":{"type":"string","description":"Resolved source amount in the source token's smallest unit"},"toAmount":{"type":"string","description":"Resolved destination amount in the destination token's smallest unit"},"isDirectTransfer":{"type":"boolean","description":"Whether the quote resolved to a same-chain direct transfer (`true`) or a routed provider/bridge transfer (`false`). When `true`, the response includes `transactionRequest` and (conditionally) `feeTxParams` but omits `quote` and `approvalTxParams`."},"provider":{"type":"string","description":"Provider that produced the quote ('Direct' on the direct-transfer path)"},"originalIntent":{"type":"object","description":"Echo of the intent supplied in the quote request","properties":{"method":{"type":"string","enum":["usd","fromAmount","toAmount"]},"value":{"type":"string"}}}}}}}}}}
```