Skip to main content
GET
/
v1
/
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

​
x-api-key
string
required
A valid PARTNER scope key.

​
Path Parameters

​
grail_user_id
string
required
GRAIL’s identifier for the user, prefixed gu_. Returned from Create User.

​
Response

​
grail_user_id
string
GRAIL’s user identifier.
​
user_id
string
Your internal identifier (the partner_user_id supplied at creation time).
​
wallet_address
string
The user’s Solana wallet address.
​
status
string
"active" or "suspended". Suspended users cannot quote trades or redemptions.
​
created_at
string
ISO-8601 timestamp of user creation.
​
kyc
object
The user’s KYC record. Omitted if no KYC record exists (shouldn’t happen for users created via Create User).

​
Errors

HTTPerrorWhen
401unauthorizedMissing or invalid x-api-key
403partner_mismatchUser belongs to a different partner
404user_not_foundNo 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"
    }
  }
}