> For the complete documentation index, see [llms.txt](https://docs.orda.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.orda.network/developers/guides/postman-workspace.md).

# 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.