Privy Wallet Provider

OverviewCopy Anchor Link

Both effects come from one setup in one Privy app. Privy sign-in is not available on its own, because sufwan-local-test finds a user's Privy wallets through the Privy identity that sign-in records.

Quick startCopy Anchor Link

flowchart TD
  A[Privy SDK in your app] -->|access token| B[sufwan-local-test session]
  B --> C[Deposit addresses on Funding]
  C --> D[Fund and trade]

PrerequisitesCopy Anchor Link

The key is accepted in any of the shapes Privy hands out: the wallet-auth:MIGH... form, a bare base64 PKCS#8 body, or a full -----BEGIN PRIVATE KEY----- PEM block.

How it worksCopy Anchor Link

1. Sign-in. Your frontend gets an access token from Privy and posts it to sufwan-local-test. sufwan-local-test verifies it against your Privy app's public keys and returns an sufwan-local-test session. There is no callback URL: Privy never redirects.
2. Wallet setup. The first time a user's deposit addresses are requested, sufwan-local-test finds that user's Ethereum and Solana wallets in your Privy app and links them. If you opted in, it creates any that are missing.
3. Execution. Every trade, bridge and transfer is signed through Privy with the authorization key you saved, with no user present.

Wallet ownershipCopy Anchor Link

sufwan-local-test can only use a wallet it can sign with on its own:

A user-owned wallet with your server signer looks like this in Privy:

{
  "owner": { "user_id": "did:privy:…" },
  "additional_signers": [{ "signer_id": "<your key quorum id>" }]
}

Wallet discoveryCopy Anchor Link

sufwan-local-test looks for a user's wallets in two places, so either ownership model works without extra configuration:

Of the wallets found, sufwan-local-test uses the first one per chain that it can actually sign with, proven by signing a harmless message.

Wallet creationCopy Anchor Link

By default sufwan-local-test never creates a wallet — it uses the ones your onboarding already made.

If your users can reach trading before a wallet exists, turn on Create wallets for users who have none and enter your Signer ID. sufwan-local-test then creates the missing wallet as a user-owned wallet with your signer attached:

{
  "chain_type": "ethereum",
  "owner": { "user_id": "did:privy:…" },
  "additional_signers": [{ "signer_id": "<your signer id>" }]
}

Use the key quorum your backend already attaches to your users' wallets, so your signer policies and key rotation also cover wallets sufwan-local-test creates. sufwan-local-test never creates an app-owned wallet, and the setting cannot be saved without a Signer ID.

Unlike the wallet provider itself, this setting can be changed at any time. A change applies the next time a user's wallets are set up.

Existing wallets without your signerCopy Anchor Link

Embedded wallets that Privy created at signup are owned by the user. If your key quorum was never added to them, sufwan-local-test cannot sign with them, and GET /execution/deposit-addresses answers 409 with code: "PRIVY_WALLET_NOT_SIGNABLE".

Create wallets for users who have none does not help here — it only fills a chain with no wallet, and never replaces one your user may already have funded.

Only the wallet's owner can change its signers, so your server key cannot add the signer on its own. Add it from your frontend, with the user's Privy session, using Privy's useSigners hook:

import { usePrivy, useSigners } from "@privy-io/react-auth";

// YOUR Privy key quorum ID — the same value you entered as "Signer ID" under
// Settings → Wallet Provider in sufwan-local-test. It is not issued by sufwan-local-test: it comes from
// your Privy dashboard, and the quorum must contain the authorization key
// you saved in sufwan-local-test.
const YOUR_PRIVY_SIGNER_ID = "<your-privy-key-quorum-id>";

export function useAddSignerToWallets() {
  const { user } = usePrivy();
  const { addSigners } = useSigners();

  return async function addSignerToWallets() {
    // Your users' Privy embedded wallets, on both chains — sufwan-local-test signs on each.
    const wallets = (user?.linkedAccounts ?? []).filter(
      (account) =>
        account.type === "wallet" &&
        account.walletClientType === "privy",
    );

    for (const wallet of wallets) {
      try {
        await addSigners({
          address: wallet.address,
          signers: [{ signerId: YOUR_PRIVY_SIGNER_ID }],
        });
      } catch (err) {
        // Privy rejects adding a signer the wallet already has. That means this
        // wallet is already set up — skip it and continue with the next one.
        if (String((err as Error)?.message).includes("Duplicate signer")) continue;
        throw err;
      }
    }
  };
}

Call it after sign-in, before you request deposit addresses, or when that request returns PRIVY_WALLET_NOT_SIGNABLE. Deposit address hooks surface the same code as error. The request itself is on Funding & withdrawals.

What to expectCopy Anchor Link

Users who have no wallet yet do not need this: with Create wallets for users who have none turned on, sufwan-local-test creates their wallets with your signer already attached.

Configure Privy in sufwan-local-testCopy Anchor Link

Authenticate usersCopy Anchor Link

Get the user's access token from Privy's client SDK, then exchange it for an sufwan-local-test session with POST /auth/verify and { "kind": "privy", "privyToken" }. There is no Privy setting on the Auth tab — saving Privy as the wallet provider enables it, and there is no callback URL. See Authentication & sessions.

sufwan-local-test verifies the token with Privy's published public keys at https://auth.privy.io/api/v1/apps/{appId}/jwks.json. The Privy DID (sub) becomes the user's identity, so the same person signing in to two of your apps gets one identity across both.

Sign-in errorsCopy Anchor Link

Every failure is a 401:

Initialize user walletsCopy Anchor Link

For a Privy wallet-provider app, the deposit address is the authorized Privy wallet: evmAddress on EVM and svmAddress on Solana. Other apps get a managed deposit address. Follow the polling example in Funding & withdrawals until provisioning is ready.

A 409 means the Privy wallet does not grant Agg's authorization key signing rights. Add your signer, then request addresses from Funding. See Existing wallets without your signer.

The wallets.ready webhook fires once a user's wallets are set up.

Provider lockCopy Anchor Link

Errors & troubleshootingCopy Anchor Link