Non-Custodial Wallets

Overview

For sandbox lifecycle prose + copy-paste recipes (cosign approved and declined), see withdrawals.mdx Step 4. Conduit supports two custody models for crypto wallets:

Model	Who controls the key	How funds are moved
Custodial	Conduit	Conduit signs and broadcasts autonomously
Non-custodial	Customer (end-user passkey)	Conduit and the customer co-sign; Conduit broadcasts after both signatures land

In the non-custodial model, every customer has a dedicated key set that requires two cryptographic signatures to move funds: one from Conduit, and one from the customer. The customer’s signature is generated on-device using a WebAuthn passkey — Conduit never sees the private key. Conduit alone cannot move non-custodial funds.

Signing modes

The customer’s signature doesn’t have to come from a human. Every customer has a signing mode, configured by Conduit out of band as an organization-wide default with per-customer overrides (the customer-level setting wins) — ask your Conduit representative; there is no API to set it.

Mode	Who signs payouts	Who governs the roster
Passkey required	Human passkey holders; `api_key` roster members are rejected	Passkey admins
Programmatic	Machine (API-key) signers may hold `role: "signer"` and vote	Admins must still be passkey holders
Programmatic unattended	Machine signers, fully server-driven	Machine keys may be admins (enabled only after an additional Conduit review)

Everything below on this page — the verify page, WebAuthn, verificationUrl — describes the passkey-required mode. In a programmatic mode, machine signers seat active at claim time with no enrollment step, the transaction.awaiting_signature webhook carries a signingRequestId (plus a verificationUrl only when the roster has an active passkey signer, who may approve on the verify page alongside the machine signers), and your backend reads the request via GET /v2/signing-requests/{id} and resolves it via POST /v2/signing-requests/{id}/approve or .../reject. Conduit’s compliance co-approval is still always required — a machine can never move money alone. See Programmatic payout signing.

Enabling crypto for a customer

Before a customer can claim a non-custodial wallet roster, they need an approved CRYPTO_WALLET feature on file:

POST /v2/customers/:id/features  { "type": "crypto_wallet" }
       │
       ▼
 Application enters the review queue:
   • In sandbox the default is auto-approve (status: "approved" returned synchronously)
   • In live the default is manual review (status: "processing") until ops approves
   • Customers in restricted jurisdictions get 422 CRYPTO_NOT_AVAILABLE_IN_JURISDICTION
       │
       ▼
 Once the application's status is "approved", call claim-non-custodial.
 Calling claim-non-custodial before the feature is approved returns 422 CRYPTO_FEATURE_NOT_APPROVED.

The review gate is per-customer, distinct from the customer’s KYB. A KYB-approved customer is not automatically crypto-enabled — feature approval is a separate decision that can also flag tier/plan gating, additional crypto-specific risk review, or per-bank-partner restrictions.

Two-signature model

Moving funds from a non-custodial wallet always requires both:

The customer’s signature — produced when the customer approves on the Conduit-hosted verify page using their passkey (Face ID, Touch ID, or a hardware security key).
Conduit’s compliance signature — applied automatically once the customer quorum is collected. Compliance and Travel Rule screening already ran before the signature was requested, so this final stamp applies that cleared result rather than re-deciding it — a payout that passed screening is not re-screened after signing. Conduit cannot broadcast without this stamp.

Both signatures must land before Conduit broadcasts. The security guarantee is cryptographic, not application-level: there is no code path in which Conduit can bypass the customer’s signature requirement, and no code path in which a payout that failed compliance can be signed.

Withdrawal Flow

A non-custodial payout is screened for compliance and Travel Rule first. Only once it clears does Conduit request the customer’s signatures (transaction.processing fires and the payout’s status becomes processing). After the quorum is collected, Conduit adds its own compliance stamp and broadcasts. Because screening runs before signing, a payout that fails compliance is rejected before any signer is asked to approve — the customer never signs a payment that then fails screening.

POST /v2/payouts  →  202 Accepted (status: "pending")
       │
       ▼
 Compliance + Travel Rule screening — no client action.
 A payout that fails here is rejected before any signature is requested.
       │
       ▼
 transaction.processing fires (status becomes "processing").
 Payout enters the per-(wallet, chain) signing queue
 — it may report a queuePosition while it waits its turn.
       │
       ▼
 transaction.awaiting_signature fires
       • data.verificationUrl  ← route the customer here
       • data.expiresAt        ← sign before this time
       • data.attempt          ← increments if the window is rebuilt
       │
       ▼
 Customer approves on the verify page (passkey).
 Quorum met (M business-signer stamps collected).
       │
       ▼
 Conduit adds its compliance stamp and broadcasts on-chain.
       │
       ▼
 transaction.completed fires when the chain confirms.

If the customer doesn’t approve in time, or declines, transaction.failed fires with the matching failureCode (see Failures below).

Verify Page

The verify page is a Conduit-hosted UI served at https://app.conduit.financial/verify/<token>. It is:

Branding-aware — displays your organization’s logo and colors.
Information-rich — shows the transfer asset, amount, and destination address so the customer knows exactly what they are approving.
WebAuthn-native — uses the customer’s registered passkey (no password, no SMS OTP).

Flow

Your backend receives transaction.awaiting_signature with verificationUrl on the webhook payload.
Route your customer to that URL (deep link, redirect, or in-app WebView).
The customer taps “Approve” — their device presents a biometric prompt (Face ID, Touch ID, or hardware key).
Conduit receives the passkey approval and resumes the payout.
The customer sees a confirmation screen. The payout proceeds to broadcast.

Branding Customization

The verify page respects your organization’s branding configuration (logo URL, primary color). Contact Conduit support to configure or update your branding.

Timeout and Decline Behavior

Scenario	What happens	Customer-facing message
Customer approves within the signing window	Withdrawal proceeds to compliance checks, then broadcast	Confirmation screen on the verify page
Signing window expires (attempts remaining)	Conduit rebuilds the request with a fresh link; `transaction.awaiting_signature` re-fires with an incremented `attempt`	Route the customer to the new `verificationUrl`
All signing attempts exhausted	Payout fails; no funds moved; `transaction.failed` fires with `failureCode: "user_signature_expired"`	”The signing window expired. Start a new payout when the customer is ready.”
Customer clicks “Decline” on the verify page	Payout fails; no funds moved; `transaction.failed` fires with `failureCode: "user_signature_declined"`	”The customer declined the payout.”
Invalid passkey stamp (retryable)	Verify page shows an error; customer can retry	Verify page error — same session, no new payout needed

The signing deadline for each attempt is the expiresAt delivered on the transaction.awaiting_signature event — always drive your timers off that value, never a fixed duration. The window is not 15 minutes: in production it runs up to roughly 23 hours on EVM chains and 12 hours on Tron. The link-expiry (verificationUrl) and the signing timer are separate — the signing timer is the one that governs the payout, and it is the expiresAt on the webhook. This window and its rebuild behaviour are the same for a wallet in a programmatic signing mode: a machine request also carries an expiresAt, is rebuilt with an incremented attempt (a new signingRequestId) when the window closes, and fails with user_signature_expired only after the final attempt. Always treat the latest attempt as authoritative and discard prior links.

Webhook Integration

Subscribe to transaction.awaiting_signature to know when a non-custodial payout is awaiting approval. See the Webhooks reference for the full payload schema.

The verificationUrl on this webhook applies to a wallet in the passkey signing mode — the human-signer, verify-page model this page describes. A wallet in a programmatic signing mode carries a signingRequestId on the same webhook — plus an optional verificationUrl when its roster has an active passkey signer who may also approve on the verify page; a machine integration reads the request via GET /v2/signing-requests/{signingRequestId} and resolves it via POST .../approve or .../reject. See Machine-signer stamping.

Recommended flow on your backend:

Receive transaction.awaiting_signature
   │
   ├── Store verificationUrl and expiresAt (from the webhook payload) against the transactionId
   │
   └── Notify the customer (push notification, email, in-app alert)
         → Deep-link to verificationUrl before expiresAt

The verify URL and expiry are delivered only on the webhook — they are not exposed on GET /v2/payouts/:id. Persist the webhook payload (or its essential fields) so you can surface the verify URL to the customer on demand.

`GET /v2/payouts/:id` Response

While a payout is awaiting the customer’s signature, the response continues to report requiresUserSignature: true and, if the payout is queued behind earlier signing work on the same wallet+chain, a queuePosition:

{
  "id": "txn_2xKjF9mQb7vN4hL1pR3w8t",
  "status": "pending",
  "requiresUserSignature": true,
  "queuePosition": 2
}

queuePosition is the payout’s slot in the per-(wallet, chain) signing queue. Waiting payouts (queued behind a payout already in the signing step) expose this as a positive integer. The active payout (currently being signed) has the field absent from the response. The field is also absent once the payout advances past the queue gate or reaches a terminal status. The value is eventual — it may not appear on the initial POST response; read it via GET /v2/payouts/:id. requiresUserSignature is a present-tense gate: true while the payout is awaiting the end-user’s signature, false once status reaches completed, failed, or cancelled. It is also present on the POST /v2/payouts response (derived from the wallet’s custody model at submission) so your frontend can immediately prepare the user-routing flow without waiting for the webhook. After the response goes terminal, expect false regardless of the source wallet’s custody model — don’t keep waiting on a settled row.

Sandbox Testing

In the sandbox environment, the real signing flow is bypassed. Resolve the cosign gate via one of two endpoints. They produce the same outcome a real customer action on the verify page would, and the payout reaches completed or failed automatically — no follow-up simulate/confirm is required.

Simulate endpoints

Recommended: resolve by payout ID — most integrators should use this variant. Drive any specific payout end-to-end keyed by the id returned from POST /v2/payouts. Each call casts one signer’s vote: omit signerId and repeated calls auto-advance through the roster one signer at a time until the threshold is met, or pass a signerId to cast a specific signer’s vote. A single declined vote terminalizes the whole quorum as declined.

POST /v2/sandbox/payouts/:id/simulate/cosign
Content-Type: application/json

{ "outcome": "approved" | "declined", "signerId": "wsg_..." }

Returns 200 with the payout at its current state; signerId is optional. Calling again after the gate has already resolved is safe — it returns the payout at its current state rather than an error. Per-signer variant — records one named signer’s stamp against a payout, so a test can walk quorum progress signer by signer (while the signing request is still pending, re-stamping by the same signer is idempotent):

POST /v2/sandbox/payouts/:id/simulate-stamp
Content-Type: application/json

{ "walletSignerId": "wsg_...", "outcome": "approved" | "declined" }

Returns 200 with the payout at its current state; 404 if the payout is not awaiting a signature or the signer is not on the wallet’s roster. Note the contrast with simulate/cosign above: once the quorum has resolved, a repeat call here returns 404 NOT_IN_AWAITING_SIGNATURE rather than the payout’s current state. See the Multi-signer wallets recipe and the Custody sandbox guide for full walkthroughs.

Failures

Once POST /v2/payouts returns 202 Accepted, any failure during the signing flow arrives on the transaction.failed webhook. When the failure has a cause your integration can act on, the payload carries a failureCode:

`failureCode`	What happened	What to do
`user_signature_timeout`	The payout waited too long in the signing queue without reaching the signing step (queue max-residence timeout).	No funds were moved. Submit a new payout when the customer is ready to sign.
`user_signature_expired`	Every signing window was offered to the customer but quorum was not reached; all rebuild attempts were exhausted.	No funds were moved. Submit a new payout when the customer is ready to sign.
`user_signature_declined`	The customer declined the payout from the approval page.	No funds were moved. Submit a new payout if the decline was unintentional.
`user_signature_rejected_by_provider`	The customer’s passkey approval could not be accepted.	No funds were moved. Submit a new payout. If the same customer or wallet hits this repeatedly, contact support.
`crypto_wallet_misconfigured`	The wallet’s configuration prevents Conduit from moving funds from it.	No funds were moved. Conduit is investigating automatically. Contact support if the wallet is needed for a time-sensitive payout.

The webhook reason field is a human-readable version of the failureCode. The same failureCode is surfaced on GET /v2/transactions/:id and GET /v2/payouts/:id, so a fresh GET reconciles 1:1 with the webhook. If transaction.failed arrives without a failureCode, the payout could not be completed and the cause is not something your integration can act on. Treat the transaction as terminal and contact support if the customer needs help understanding why.

Getting Started

How Conduit Works

Concepts

How-To Guides

Webhooks

Non-Custodial Wallets

Overview

Signing modes

Enabling crypto for a customer

Two-signature model

Withdrawal Flow

Verify Page

Flow

Branding Customization

Timeout and Decline Behavior

Webhook Integration

`GET /v2/payouts/:id` Response

Sandbox Testing

Simulate endpoints

Failures

​Overview

​Signing modes

​Enabling crypto for a customer

​Two-signature model

​Withdrawal Flow

​Verify Page

​Flow

​Branding Customization

​Timeout and Decline Behavior

​Webhook Integration

​GET /v2/payouts/:id Response

​Sandbox Testing

​Simulate endpoints

​Failures

Overview

Signing modes

Enabling crypto for a customer

Two-signature model

Withdrawal Flow

Verify Page

Flow

Branding Customization

Timeout and Decline Behavior

Webhook Integration

`GET /v2/payouts/:id` Response

Sandbox Testing

Simulate endpoints

Failures