Skip to main content
The PartnerAccountService creates sub-account profiles linked to the authenticated partner. Requires HMAC authentication with the account_creation scope.

Access

Server wallet mode

Creates a managed Privy wallet for the sub-account. Enables delegated signing — the partner submits unsigned orders and the server signs them.
New server wallets should be checked with check_allowances() before the first delegated trade. If retryable targets are missing or failed, call retry_allowances() and poll again.

List and recover sub-accounts

Use list_accounts() to list partner-owned sub-accounts or recover a specific child profile by wallet address. This calls GET /profiles/partner-accounts and requires HMAC credentials with the account_creation scope.
Do not send x-on-behalf-of to this endpoint. Results are always scoped to the authenticated partner behind the HMAC token.

Allowance recovery

Server-wallet sub-accounts need delegated-trading approvals before they can trade. The partner allowance helpers use the Partner API only:
  • check_allowances(profile_id) calls GET /profiles/partner-accounts/:profileId/allowances
  • retry_allowances(profile_id) calls POST /profiles/partner-accounts/:profileId/allowances/retry
  • both methods require HMAC credentials with account_creation and delegated_signing
  • profile_id is the child/server-wallet profile id
Recommended partner flow:
  1. Poll check_allowances(profile_id).
  2. If ready is True, continue.
  3. If targets are missing or failed with retryable=True, call retry_allowances(profile_id).
  4. If retry returns submitted targets, poll check_allowances() again after a short delay.
  5. If retry returns 429, wait retryAfterSeconds.
  6. If retry returns 409, wait briefly and call check_allowances() again.

Withdrawal address allowlist

Explicit treasury destinations for server-wallet withdrawals must be allowlisted on the authenticated partner profile unless the destination is already the partner account or partner smart wallet. Allowlist management uses a Privy identity token, not API-token/HMAC auth.
add_withdrawal_address() and delete_withdrawal_address() call POST /portfolio/withdrawal-addresses and DELETE /portfolio/withdrawal-addresses/:address with the identity: Bearer <token> header. POST /portfolio/withdraw still uses HMAC auth with the withdrawal scope.

EOA mode

Creates a profile for an externally-owned address. The end user manages their own keys and signs orders themselves. EOA mode requires wallet ownership verification headers:

Validation

  • display_name is optional, max 44 characters. Defaults to the wallet address if omitted.
  • Returns 409 Conflict if a profile already exists for the target address.
  • Cannot create a sub-account for the partner’s own address.
  • The SDK validates display_name length locally before sending the request.