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 CheckAllowances before the first delegated trade. If retryable targets are missing or failed, call RetryAllowances and poll again.

List and recover sub-accounts

Use ListAccounts 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:
  • CheckAllowances(ctx, profileID) calls GET /profiles/partner-accounts/:profileId/allowances
  • RetryAllowances(ctx, profileID) calls POST /profiles/partner-accounts/:profileId/allowances/retry
  • both methods require HMAC credentials with account_creation and delegated_signing
  • profileID is the child/server-wallet profile id
Recommended partner flow:
  1. Poll CheckAllowances(ctx, profileID).
  2. If Ready == true, continue.
  3. If targets are missing or failed with Retryable == true, call RetryAllowances(ctx, profileID).
  4. If retry returns submitted targets, poll CheckAllowances again after a short delay.
  5. If retry returns 429, wait retryAfterSeconds.
  6. If retry returns 409, wait briefly and call CheckAllowances 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.
AddWithdrawalAddress and DeleteWithdrawalAddress 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

  • DisplayName 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 DisplayName length locally before sending the request.