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

Access

Server wallet mode

Set create_server_wallet to create a managed wallet for the sub-account. This enables delegated signing:
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 == 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

For externally-owned accounts, pass ownership-verification headers:

Validation

  • display_name is optional and capped at 44 characters
  • when create_server_wallet is not Some(true), EOA headers are required
  • the SDK validates display_name length locally before sending the request
  • 409 Conflict is returned if a profile already exists for the target address
Server-wallet sub-accounts and EOA sub-accounts use different signing models. Use server-wallet mode for delegated signing, and EOA mode when the end user will sign orders themselves.