Skip to main content

​
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
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

Authentication & Setup

Mint a PARTNER API key via the challenge-response flow.

Creating & Managing Users

Register end-users with flexible-JSON KYC under your partner.

Buying Gold

Quote, co-sign (GRAIL + partner + user), submit, and track on-chain confirmation.

Selling Gold

Mirror of the buy flow — quote, three-signer tx, submit, confirm.

Redeeming Physical Gold

Convert $GOLD tokens to a physical-gold denomination for pickup.
  1. Authentication & Setup — mint your partner API key
  2. Creating & Managing Users — register your first end-user
  3. Buying Gold — execute your first buy
  4. Selling Gold — close the loop with a sell
  5. Redeeming Physical Gold — optional, for integrations that include physical fulfillment