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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.orda.network/developers/guides/postman-workspace.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.