Skip to main content

​
Introduction

The Oro TradeBook API provides distribution partners with a convenient interface to integrate with the Oro Gold ecosystem. The API abstracts Solana blockchain complexity while providing full access to the on-chain TradeBook program for gold token trading and user management.

​
Base URL

https://oro-tradebook-devnet.up.railway.app

​
Authentication

All endpoints (except public ones like /health and /api/trading/gold/price) require API key authentication via the x-api-key header: 
curl -X GET https://oro-tradebook-devnet.up.railway.app/api/users \
  -H "x-api-key: your-api-key"

​
API Key Scopes

ScopeDescription
ADMINSystem admin operations (partner creation)
PARTNER_EXECUTIVE_AUTHORITYTrading operations (buy, sell, user creation)
PARTNER_UPDATE_AUTHORITYPartner settings updates
PARTNER_WITHDRAWAL_AUTHORITYWithdrawal operations

​
Getting an API Key

  1. Call POST /api/auth/challenge with your wallet address
  2. Sign the challenge message with your wallet
  3. Call POST /api/auth/api-key with the signature

​
Partner Types

​
Custodial

Partner manages user funds. Users don’t have wallets - the partner holds gold on their behalf.

​
Self-Custody

Users control their own wallets. Partner facilitates transactions but users sign and own their assets.

​
Transaction Flow

Most operations return a serialized transaction that needs to be signed before submission: 
1. Call API endpoint (e.g., /api/trading/purchases/user)
     ↓
2. Receive serialized transaction + signing instructions
     ↓
3. Deserialize and sign with required wallet(s)
     ↓
4. Submit via POST /api/transactions/submit
     ↓
5. Transaction confirmed on Solana

​
Signing Instructions

Each transaction response includes: 
{
  "transaction": {
    "serializedTx": "base64-encoded-transaction",
    "signingInstructions": {
      "walletType": "user_wallet, executive_authority",
      "signers": ["WalletAddress1", "WalletAddress2"],
      "expiresAt": "2024-01-15T10:35:00.000Z"
    }
  }
}

​
Key Concepts

​
Partner PDA (Central Vault)

Each partner has a Program Derived Address (PDA) that holds their trading funds (USDC and Gold). This is the centralVaultAddress returned when creating a partner.
  • Partner purchases: USDC from PDA → Gold to PDA
  • Partner sales: Gold from PDA → USDC to PDA
  • Withdrawals: Funds from PDA → Destination wallet

​
User PDA

Each user has a compressed account (PDA) that tracks their KYC hash and balances.

​
Gold Pricing

Gold prices are sourced from Pyth Network oracle for real-time market data. Use the /api/trading/gold/price endpoint to get current prices.

​
Rate Limits

  • Authentication endpoints: 1 request per second
  • Trading endpoints: Standard rate limits apply

​
Error Handling

All errors return a consistent format: 
{
  "success": false,
  "error": "Error message description"
}
Common HTTP status codes:
  • 400 - Bad request (invalid parameters)
  • 401 - Unauthorized (missing or invalid API key)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Not found
  • 500 - Internal server error

​
API Groups

Authentication

API key management - create, list, and revoke keys

Distribution

Partner management - create and configure partners

Users

User management - create and query users

Trading

Trading operations - buy, sell, withdraw gold

Transactions

Submit signed transactions to Solana

General

Health checks and system status