Skip to content
openusd.dev

Privy OUSD integration

Privy provides wallet infrastructure for applications, including embedded wallets, external-wallet connections and custodial wallets backed by Bridge. Its wallet model determines who can authorize transactions; its custodial transfer guide explicitly includes OUSD. [1] [2] [3]

Holding OUSD

Privy can expose a Bridge-custodied OUSD wallet and its balance inside an application. [2] [3]

After provisioning, fund through the supported deposit address or an approved Bridge virtual-account or transfer route. Confirm the actual OUSD asset and chain with Bridge before sending; these funding methods are not universal asset support. [4] [2]

Subscribe to balance notifications and reconcile movements. Use bridge_metadata to distinguish deposits from refunds of failed off-ramps. Enterprise enablement and the custodian’s beneficiary and regional requirements apply before funding. [5] [6]

General workflow: Holding OUSD

Sending payouts from OUSD

Privy documents custodial OUSD transfers, including an OUSD-on-Tempo example. This is a wallet-to-wallet transfer, not a bank-payout API. [3]

Prerequisites: Privy Enterprise, custodial-wallet enablement, Bridge onboarding and beneficiary KYC. Use an existing funded Tempo mainnet custodial wallet. Setup uses a Bridge production integration; the example below is documentation, not a sandbox transfer or an independently executed payment. Confirm route, fees and limits before use. [6] [7] [3]

  1. Before submission, persist an application payment ID, app/environment, wallet ID, Bridge customer ID, approved recipient, asset, chain and exact amount. Store one immutable request fingerprint, reference_id and idempotency key for that attempt. These are recommended application records, not additional Privy API fields. [3] [8] [9]

  2. The request uses amount in standard units: 10.0 means ten OUSD. Supply the authorization signature when an owner or additional signer requires it; include custody_options.initiation when required by the wallet’s strong-customer-authentication flow. The destination must be the approved recipient’s address, never the OUSD token contract. [3] [10]

  3. Save the returned action id, wallet_id, type, status, transfer fields and observation time. If the response is lost, recover with GET /v1/actions?reference_id=invoice-1042-attempt-1. reference_id is unique per app, at most 64 characters, and is not an idempotency key. [8] [11]

  4. Retrieve GET /v1/wallets/{wallet_id}/actions/{action_id}?include=steps. Poll with backoff until terminal; a local timeout remains unresolved work. For this custodial flow, succeeded reports onchain confirmation; rejected has no onchain effect; failed can include prior effects and needs inspection before retrying. [11] [12]

  5. Verify webhook signatures before use. Transfer events identify wallet_action_id, while the action resource uses id; neither is the delivery ID used for deduplication. Treat events as triggers to retrieve authoritative state. Compare wallet, exact amount, asset, chain and recipient against the approved intent, then post a matching succeeded effect once in the ledger. Preserve mismatches and failed steps for review. [13] [14] [12]

Keep returned evidence and any available settlement receipt. The documented custodian_transaction step exposes status and failure_reason, but does not guarantee a transaction_hash field; do not invent one. Fees are separate reconciliation fields, not assumed to be zero. [15] [3]

Retry boundary: reuse the same privy-idempotency-key and identical request body within its 24-hour window; expired keys can execute a new operation. For /transfer, synchronous 5xx responses delete the idempotency record, so the same key can retry a fresh attempt. POLICY_VIOLATION also clears the record; correct the policy issue before retrying. These exceptions do not make an ambiguous timeout or asynchronously failed action safe to repeat: reconcile through reference/action lookup before another payment. [9] [8] [12]

Worked request: ten OUSD on Tempo

Documentation-only HTTP request with placeholders. It has not been submitted. Use it only inside an authorized server integration; keep secrets out of browser code and logs. Required signing and initiation context depend on the wallet configuration.

POST https://api.privy.io/v1/wallets/{wallet_id}/transfer
Content-Type: application/json
privy-app-id: {app_id}
Authorization: Basic {base64(app_id:app_secret)}
privy-idempotency-key: {persisted_uuid_for_this_attempt}
privy-authorization-signature: {required_authorization_signature}


{
  "reference_id": "invoice-1042-attempt-1",
  "amount": "10.0",
  "source": { "asset": "ousd", "chain": "tempo" },
  "destination": { "address": "{approved_recipient_hex_address}" }
}

Sources: [3] Privy: Send funds from custodial wallets · [8] Privy: Wallet action reference IDs · [9] Privy: Idempotency keys · [10] Privy: Transfer API request and response

General workflow: Sending payouts from OUSD

Creating OUSD wallets

Privy offers embedded wallets and a separate Bridge-backed custodial route with documented OUSD transfers. [1] [3]

  1. For the custodial route, obtain a Privy Enterprise plan and app enablement. Complete Bridge onboarding and beneficiary KYC. [6]

  2. Register the Bridge production API key under Configuration → Integrations, then enable Custodial wallets under Wallets → Advanced and select Bridge. [6]

  3. Create the wallet with POST /v1/custodial_wallets. Set provider to bridge and provider_user_id to the beneficiary’s Bridge customer ID. Configure the chain, owner and policies, then save the returned wallet ID and address. [7]

Custodial creation lists Tempo, Base and Solana mainnet; the explicit OUSD transfer example is on Tempo. Confirm other asset/chain combinations and regional access with Bridge rather than combining separate asset and chain lists. [7] [3]

For an embedded wallet, choose user or application control, configure the owner and policies, then use the documented client or server SDK creation flow. The owner controls authorization; an entity association does not grant control. This general wallet flow does not establish every OUSD payment or issuer service. [16] [1]

General workflow: Creating OUSD wallets

Managing OUSD custody

Bridge is the custodian for Privy custodial wallets; Privy configures who may request actions. [2] [17]

Complete the Enterprise and Bridge setup, then assign the owner, policies and additional signers needed for the application. A custodial wallet owner cannot export private keys or transact without custodian approval. [6] [17]

Bridge screens transactions before execution. Enforce the beneficiary’s geographic and route restrictions, track each action, and inspect failed steps before retrying because partial onchain effects are possible. Fees and transaction limits remain to be confirmed for the account. [12] [3]

General workflow: Managing OUSD custody

Related references

References and last updated

Reviewed 2026-10-12 · Updated 2026-10-26. This profile summarizes provider documentation. No live integration independently tested.

  1. Privy: wallet types ↗
    Published date not provided · Reviewed 2026-10-11
  2. Privy: Custodial wallets overview ↗
    Published date not provided · Reviewed 2026-10-11
  3. Privy: Send funds from custodial wallets ↗
    Published date not provided · Reviewed 2026-10-12
  4. Privy: Fund custodial wallets ↗
    Published date not provided · Reviewed 2026-10-11
  5. Privy: Custodial wallet events ↗
    Published date not provided · Reviewed 2026-10-12
  6. Privy: Set up custodial wallets ↗
    Published date not provided · Reviewed 2026-10-12
  7. Privy: Create a custodial wallet ↗
    Published date not provided · Reviewed 2026-10-12
  8. Privy: Wallet action reference IDs ↗
    Published date not provided · Reviewed 2026-10-12
  9. Privy: Idempotency keys ↗
    Published date not provided · Reviewed 2026-10-26
  10. Privy: Transfer API request and response ↗
    Published date not provided · Reviewed 2026-10-12
  11. Privy: Get action status ↗
    Published date not provided · Reviewed 2026-10-12
  12. Privy: Custodial transaction lifecycle ↗
    Published date not provided · Reviewed 2026-10-12
  13. Privy: Transfer succeeded webhook ↗
    Published date not provided · Reviewed 2026-10-12
  14. Privy: Verify and test webhooks ↗
    Published date not provided · Reviewed 2026-10-12
  15. Privy: Official wallet action types ↗
    Published date not provided · Reviewed 2026-10-12
  16. Privy: Create a wallet ↗
    Published date not provided · Reviewed 2026-10-11
  17. Privy: Custodial authorization controls ↗
    Published date not provided · Reviewed 2026-10-11
  18. Stripe: Open USD product integration overview ↗
    Published date not provided · Reviewed 2026-10-12

Claim-level sources, product review dates and evidence status are retained in the downloadable dataset.