> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grail.oro.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration Guides

> Step-by-step guides for integrating with the Oro GRAIL API.

# Integration Guides

These guides walk through every end-to-end flow GRAIL exposes, from minting your first API key to quoting a trade, co-signing the returned Solana transaction, and tracking confirmation. Each builds on the previous and includes copy-pasteable code.

## Before you begin

You'll need, from ORO:

* Your **partner ID** (UUID)
* Your **partner wallet** (Solana keypair) — whitelisted on-chain by ORO
* Confirmation that your **IntegratorV2 PDA** is initialized on-chain (ORO does this at onboarding)
* At least one **end-user wallet** registered in GRAIL, or the ability to register one yourself via [Create User](/api-reference/users/create-user)

And locally:

* **Node.js 18+** (Node 20 or 22 recommended)
* `@solana/web3.js`, `tweetnacl`, `bs58` installed in your integration project (used for message signing + transaction co-signing)
* An HTTP client — curl, Postman, etc.

## Base URL

```
https://grail-stack-dev.onrender.com
```

All examples in the guides assume this as `$BASE`.

## Guides

<CardGroup cols={2}>
  <Card title="Authentication & Setup" icon="key" href="/guides/authentication-and-setup">
    Mint a PARTNER API key via the challenge-response flow.
  </Card>

  <Card title="Creating & Managing Users" icon="users" href="/guides/creating-and-managing-users">
    Register end-users with flexible-JSON KYC under your partner.
  </Card>

  <Card title="Buying Gold" icon="coins" href="/guides/buying-gold">
    Quote, co-sign (GRAIL + partner + user), submit, and track on-chain confirmation.
  </Card>

  <Card title="Selling Gold" icon="money-bill-transfer" href="/guides/selling-gold">
    Mirror of the buy flow — quote, three-signer tx, submit, confirm.
  </Card>

  <Card title="Redeeming Physical Gold" icon="truck" href="/guides/redeeming-physical-gold">
    Convert `$GOLD` tokens to a physical-gold denomination for pickup.
  </Card>
</CardGroup>

## Recommended order

1. **[Authentication & Setup](/guides/authentication-and-setup)** — mint your partner API key
2. **[Creating & Managing Users](/guides/creating-and-managing-users)** — register your first end-user
3. **[Buying Gold](/guides/buying-gold)** — execute your first buy
4. **[Selling Gold](/guides/selling-gold)** — close the loop with a sell
5. **[Redeeming Physical Gold](/guides/redeeming-physical-gold)** — optional, for integrations that include physical fulfillment