Get User

curl https://grail-stack-dev.onrender.com/v1/users/gu_6b60956e-a8ee-4de2-8128-04c7fdf633c3 \
  -H "x-api-key: grail_partner_<hex>"

{
  "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",
  "kyc": {
    "country": "PK",
    "full_name": "Alice Example",
    "kyc_level": "full",
    "kyc_provider": "manual",
    "kyc_verified_at": "2026-04-17T00:00:00.000Z",
    "kyc_data": {
      "id_type": "CNIC",
      "id_number": "12345-1234567-1"
    }
  }
}

GET

users

{grail_user_id}

curl https://grail-stack-dev.onrender.com/v1/users/gu_6b60956e-a8ee-4de2-8128-04c7fdf633c3 \
  -H "x-api-key: grail_partner_<hex>"

{
  "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",
  "kyc": {
    "country": "PK",
    "full_name": "Alice Example",
    "kyc_level": "full",
    "kyc_provider": "manual",
    "kyc_verified_at": "2026-04-17T00:00:00.000Z",
    "kyc_data": {
      "id_type": "CNIC",
      "id_number": "12345-1234567-1"
    }
  }
}

Overview

Returns the user’s profile plus their KYC record. Partner-scoped — if the grail_user_id belongs to a different partner, the request is rejected with 403 partner_mismatch.

Headers

string

required

A valid PARTNER scope key.

Path Parameters

string

required

GRAIL’s identifier for the user, prefixed gu_. Returned from Create User.

Response

string

GRAIL’s user identifier.

string

Your internal identifier (the partner_user_id supplied at creation time).

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.

object

The user’s KYC record. Omitted if no KYC record exists (shouldn’t happen for users created via Create User).

Show properties

string

ISO-3166-1 alpha-2 country code.

string

Full legal name as supplied at creation.

string

"full" for users able to trade / redeem.

string

Label of the KYC provider.

string

ISO-8601 timestamp of when KYC was verified.

object

Free-form JSON with provider-specific fields, as supplied at creation.

Errors

HTTP	`error`	When
401	`unauthorized`	Missing or invalid `x-api-key`
403	`partner_mismatch`	User belongs to a different partner
404	`user_not_found`	No user with the given `grail_user_id`

curl https://grail-stack-dev.onrender.com/v1/users/gu_6b60956e-a8ee-4de2-8128-04c7fdf633c3 \
  -H "x-api-key: grail_partner_<hex>"

{
  "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",
  "kyc": {
    "country": "PK",
    "full_name": "Alice Example",
    "kyc_level": "full",
    "kyc_provider": "manual",
    "kyc_verified_at": "2026-04-17T00:00:00.000Z",
    "kyc_data": {
      "id_type": "CNIC",
      "id_number": "12345-1234567-1"
    }
  }
}

List Users List Denominations

API Reference

General

Authentication

Partner

Users

Denominations

Trades

Redemptions

Overview

Headers

Path Parameters

Response

Errors

​Overview

​Headers

​Path Parameters

​Response

​Errors

Overview

Headers

Path Parameters

Response

Errors