Skip to main content
POST /api/v1/builder/users Creates a new end-user under your builder account. Idempotent — calling again with the same external_id returns the existing user.
All builder requests use impersonation: your builder API key authenticates the request, and the X-Builder-Customer-Id header identifies the end-user. Your users never see your builder key — authentication happens entirely on your backend.

​
Parameters

​
external_id
string
required
Your app’s internal user ID. Creates a new user if not found (idempotent).
​
email
string
User’s email (used for Privy account creation).
​
qps_limit
number
Per-user rate limit (must be >= 1, draws from your QPS pool).
​
eoa_address
string
User’s external wallet address (42-char hex, 0x-prefixed). Validated on create but no wallet record is written — pass it again during onboard to create a Safe wallet.

​
Response

​
customer_id
string
Parsec customer UUID.
​
external_id
string
Your app’s internal user ID (echoed back).
​
api_key
string
End-user’s Parsec API key. Store this securely — it is returned on every call (idempotent).
​
status
string
"complete" on success.
​
linked_exchanges
string[]
Exchanges the user is onboarded to (empty for new users).
​
wallet
object | null
Wallet info. Present if user has a wallet.
​
fee_escrow_enabled
boolean
Whether fee escrow is active.
​
fee_bps
number | null
Fee basis points (builder-level setting).
​
affiliate_address
string | null
Fee recipient address (builder-level setting).
curl -X POST "https://api.parsecapi.com/api/v1/builder/users" \
  -H "X-API-Key: pk_live_YOUR_BUILDER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "user_001",
    "email": "alice@example.com",
    "eoa_address": "0x1234567890abcdef1234567890abcdef12345678"
  }'

{
  "customer_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_id": "user_001",
  "api_key": "pk_live_abc123def456",
  "status": "complete",
  "linked_exchanges": [],
  "wallet": null,
  "fee_escrow_enabled": false
}