List Users

curl "https://grail-stack-dev.onrender.com/v1/users?status=active" \
  -H "x-api-key: grail_partner_<hex>"

{
  "users": [
    {
      "grail_user_id": "gu_6b60956e-a8ee-4de2-8128-04c7fdf633c3",
      "user_id": "partner_internal_user_001",
      "wallet_address": "2u7vVGJCTtsijCqWJNCEknVkuLjeU7Rd4PMg4dXuTZGx",
      "status": "active",
      "created_at": "2026-04-17T10:15:30.000Z"
    }
  ]
}

GET

users

curl "https://grail-stack-dev.onrender.com/v1/users?status=active" \
  -H "x-api-key: grail_partner_<hex>"

{
  "users": [
    {
      "grail_user_id": "gu_6b60956e-a8ee-4de2-8128-04c7fdf633c3",
      "user_id": "partner_internal_user_001",
      "wallet_address": "2u7vVGJCTtsijCqWJNCEknVkuLjeU7Rd4PMg4dXuTZGx",
      "status": "active",
      "created_at": "2026-04-17T10:15:30.000Z"
    }
  ]
}

Overview

Returns a partner-scoped list of users in reverse-chronological order (newest first). All filters are optional; omit them to list every user belonging to the partner. The list response is intentionally minimal — it does not include KYC detail. For full KYC data on a specific user, call Get User.

Headers

string

required

A valid PARTNER scope key.

Query Parameters

string

Filter by user status: "active" or "suspended".

string

Reverse-lookup by your own user_id (the partner_user_id supplied at creation). Since this pair is unique per partner, the response contains at most one user.

Response

array

Array of user objects. Each object:

Show properties

string

GRAIL’s identifier for the user, prefixed gu_.

string

Your internal identifier (the partner_user_id supplied at creation).

string

The user’s Solana wallet address.

string

"active" or "suspended". Suspended users cannot quote trades or redemptions.

string

ISO-8601 timestamp of user creation.

Errors

HTTP	`error`	When
401	`unauthorized`	Missing or invalid `x-api-key`

curl "https://grail-stack-dev.onrender.com/v1/users?status=active" \
  -H "x-api-key: grail_partner_<hex>"

{
  "users": [
    {
      "grail_user_id": "gu_6b60956e-a8ee-4de2-8128-04c7fdf633c3",
      "user_id": "partner_internal_user_001",
      "wallet_address": "2u7vVGJCTtsijCqWJNCEknVkuLjeU7Rd4PMg4dXuTZGx",
      "status": "active",
      "created_at": "2026-04-17T10:15:30.000Z"
    }
  ]
}

Create User Get User

API Reference

General

Authentication

Partner

Users

Denominations

Trades

Redemptions

Overview

Headers

Query Parameters

Response

Errors

​Overview

​Headers

​Query Parameters

​Response

​Errors

Overview

Headers

Query Parameters

Response

Errors