curl -X POST https://grail-stack-dev.onrender.com/v1/users \
-H "x-api-key: grail_partner_<hex>" \
-H "Content-Type: application/json" \
-d '{
"user_id": "partner_internal_user_001",
"wallet_address": "2u7vVGJCTtsijCqWJNCEknVkuLjeU7Rd4PMg4dXuTZGx",
"kyc": {
"country": "PK",
"full_name": "Alice Example",
"kyc_provider": "manual",
"kyc_level": "full",
"kyc_verified_at": "2026-04-17T00:00:00Z",
"kyc_data": {
"id_type": "CNIC",
"id_number": "12345-1234567-1"
}
}
}'
{
"grail_user_id": "gu_6b60956e-a8ee-4de2-8128-04c7fdf633c3",
"user_id": "partner_internal_user_001",
"wallet_address": "2u7vVGJCTtsijCqWJNCEknVkuLjeU7Rd4PMg4dXuTZGx",
"created_at": "2026-04-17T10:15:30.000Z"
}
Users
Create User
Registers an end-user under the authenticated partner. KYC is flexible JSON — core fields are required, provider-specific data lives in kyc_data.
POST
/
v1
/
users
curl -X POST https://grail-stack-dev.onrender.com/v1/users \
-H "x-api-key: grail_partner_<hex>" \
-H "Content-Type: application/json" \
-d '{
"user_id": "partner_internal_user_001",
"wallet_address": "2u7vVGJCTtsijCqWJNCEknVkuLjeU7Rd4PMg4dXuTZGx",
"kyc": {
"country": "PK",
"full_name": "Alice Example",
"kyc_provider": "manual",
"kyc_level": "full",
"kyc_verified_at": "2026-04-17T00:00:00Z",
"kyc_data": {
"id_type": "CNIC",
"id_number": "12345-1234567-1"
}
}
}'
{
"grail_user_id": "gu_6b60956e-a8ee-4de2-8128-04c7fdf633c3",
"user_id": "partner_internal_user_001",
"wallet_address": "2u7vVGJCTtsijCqWJNCEknVkuLjeU7Rd4PMg4dXuTZGx",
"created_at": "2026-04-17T10:15:30.000Z"
}
Overview
Registers an end-user under the authenticated partner and stores their KYC record. The user must havekyc_level: "full" before they can quote trades or redemptions.
Core KYC fields (country, full_name, kyc_provider, kyc_level, kyc_verified_at) are structured columns; provider-specific data goes in the free-form kyc_data object. If kyc_data includes id_type and id_number, GRAIL validates the id_number against the regex registered for that country/ID-type pair (advisory — absent regex means no validation is enforced).
Headers
Request Body
Your internal identifier for this user. Unique within your partner (two users cannot share the same
user_id). Stored as partner_user_id in GRAIL.The user’s Solana wallet address. Must be a valid pubkey, and globally unique across all GRAIL users.
The user’s KYC record.
Show properties
Show properties
ISO-3166-1 alpha-2 country code. Must match an active country in GRAIL’s country list (e.g.,
PK, AE, SA).Label identifying the KYC provider you used (e.g.,
"sumsub", "manual"). Free-form string — stored verbatim.Response
GRAIL’s identifier for the user, prefixed
gu_. Use this in all subsequent trade and redemption calls.Errors
| HTTP | error | When |
|---|---|---|
| 400 | invalid_request | Missing required fields, bad timestamp, bad full_name, kyc_data.id_number doesn’t match the regex |
| 400 | invalid_wallet | wallet_address is not a valid Solana pubkey |
| 400 | kyc_level_insufficient | kyc.kyc_level is not "full" |
| 409 | user_already_exists | wallet_address is already registered, or user_id is already registered for this partner |
curl -X POST https://grail-stack-dev.onrender.com/v1/users \
-H "x-api-key: grail_partner_<hex>" \
-H "Content-Type: application/json" \
-d '{
"user_id": "partner_internal_user_001",
"wallet_address": "2u7vVGJCTtsijCqWJNCEknVkuLjeU7Rd4PMg4dXuTZGx",
"kyc": {
"country": "PK",
"full_name": "Alice Example",
"kyc_provider": "manual",
"kyc_level": "full",
"kyc_verified_at": "2026-04-17T00:00:00Z",
"kyc_data": {
"id_type": "CNIC",
"id_number": "12345-1234567-1"
}
}
}'
{
"grail_user_id": "gu_6b60956e-a8ee-4de2-8128-04c7fdf633c3",
"user_id": "partner_internal_user_001",
"wallet_address": "2u7vVGJCTtsijCqWJNCEknVkuLjeU7Rd4PMg4dXuTZGx",
"created_at": "2026-04-17T10:15:30.000Z"
}