> ## Documentation Index
> Fetch the complete documentation index at: https://developer.allscale.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Postman Collection

> Import the ready-to-run Postman collection with a built-in HMAC request signer.

Out-of-the-box Postman assets for partner engineers. Import, fill in
credentials, and you can hit every documented v1 endpoint with valid
HMAC-signed requests.

## Files

| File                                                   | What it is                                                                             |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| `AllScale_OpenAPI.postman_collection.json`             | Collection — all v1 endpoints + collection-level request signer + response assertions. |
| `AllScale_OpenAPI_Production.postman_environment.json` | Production environment (`https://openapi.allscale.io`).                                |

## Download

<Columns cols={3}>
  <Card title="Collection" icon="box" href="/postman/AllScale_OpenAPI.postman_collection.json">
    All v1 endpoints + request signer
  </Card>

  <Card title="Sandbox environment" icon="flask" href="/postman/AllScale_OpenAPI.postman_environment.json">
    openapi-sandbox.allscale.io
  </Card>

  <Card title="Production environment" icon="rocket" href="/postman/AllScale_OpenAPI_Production.postman_environment.json">
    openapi.allscale.io
  </Card>
</Columns>

## Import (Postman desktop or web)

1. **File → Import** → drop all three JSON files in at once.
2. Top-right environment dropdown → pick **AllScale OpenAPI — Sandbox**.
3. Open the environment, paste your `api_key` and `api_secret`, save.
   * `api_secret` is stored with Postman's `secret` type and is masked.
   * Both values are shown **once** in the merchant dashboard — keep them safe.

`base_url` and `checkout_intent_id` are already wired up; you should not need
to edit them.

## Suggested run order

1. **Test / GET `/v1/test/ping`** — confirms keys + clock + signing.
2. **Test / POST `/v1/test/post`** — confirms body hashing.
3. **Checkout Intent / Create — fiat** *or* **Create — native stable-coin**
   — creates an intent and auto-saves `checkout_intent_id` into the
   environment.
   * Fiat: send `currency` (IntEnum). Server FX-converts to the resolved
     settlement coin (USDT or USDC); use `accepted_stable_coins` to pick
     which (first entry wins; defaults to USDT when omitted).
   * Native stable-coin: send `stable_coin` — `1` (USDT) or `2` (USDC)
     are both accepted. `amount_cents` is stable-coin cents, no FX, and
     `currency_rate` will be `null`.
   * Send exactly one — both or neither returns `10001`.
4. **Checkout Intent / GET `/v1/checkout_intents/{id}/status`** — polls the
   lifecycle state.
5. **Checkout Intent / GET `/v1/checkout_intents/{id}`** — full detail.
   * For a native-stable-coin intent, the fiat fields (`currency`,
     `currency_symbol`, `amount_cents`, `currency_rate`) will be `null`;
     the authoritative amount lives in `amount_coins`.

You can also run the whole collection with Postman's **Collection Runner** —
every request has assertions attached, so the runner report is a usable QA
smoke-test.

## How signing works (for the curious)

A pre-request script lives at the **collection root**, so it runs before every
request without per-request setup. For each call it:

1. Reads `api_key` / `api_secret` from the active environment.
2. Builds the canonical string
   `METHOD\nPATH\nQUERY\nTIMESTAMP\nNONCE\nBODY_SHA256`
   (body hash = `sha256_hex(raw_body_bytes)`; empty body hashes the empty
   string).
3. Signs it with HMAC-SHA256, base64-encoded.
4. Upserts the required headers:
   `X-API-Key`, `X-Timestamp`, `X-Nonce`, `X-Signature: v1=<sig>`.

No need to touch the script for normal QA — but if a signature ever looks
wrong, uncomment the two `console.log` lines at the bottom of the
pre-request script to dump the canonical string and produced signature to
the Postman console.

## Troubleshooting

| Symptom                                  | Likely cause                                                                                                                                                                                |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `20001 missing_headers`                  | `api_key` / `api_secret` not set in the active environment.                                                                                                                                 |
| `20002 timestamp_out_of_window`          | Your machine's clock is off; sync NTP (±5 min window).                                                                                                                                      |
| `20002 signature_mismatch` on POSTs only | Body was edited after the script ran, or Content-Type isn't `application/json`. Re-send; the script re-hashes on every send.                                                                |
| `20002 replay_nonce`                     | Sending two requests with the same nonce within the replay window. The script generates a new UUID every send, so this should not happen — double-check you don't have the script disabled. |
| `30001 ip_not_allowed`                   | Your egress IP isn't on the merchant IP allowlist.                                                                                                                                          |
| `40001`                                  | Rate limited. Back off per the `retry_after` in the error details.                                                                                                                          |
| `50001`                                  | `checkout_intent_id` is unset or belongs to another merchant. Re-run **Create** to capture a fresh id.                                                                                      |
| `50002`                                  | `Create` rejected the request (e.g. `amount must be greater than 0.1 <coin>` when the order is at or below the 0.1-coin floor). Read `error.details.reason` for the specifics.              |

## Updating the package

When endpoints change, edit
`AllScale_OpenAPI.postman_collection.json` in this repo, then re-export the
matching `.json` from Postman — or just keep editing JSON directly. Try to
keep the canonical-string script in sync with
`thirdparty_api/auth/__init__.py::_canonical_request`; they must produce
byte-identical canonical strings.