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"
}
}
}
Users
Get User
Fetches a user’s profile and KYC record. Only users belonging to the authenticated partner are accessible.
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 thegrail_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
Show properties
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"
}
}
}