Skip to main content

​
What happened

The source wallet is missing required custody configuration — for example, the non-custodial wallet has no signing organization or suborganization set up. The payout could not be initiated and is in a terminal failed state with failureCode: CRYPTO_WALLET_MISCONFIGURED. 
{
  "type": "CRYPTO_WALLET_MISCONFIGURED",
  "title": "Wallet custody configuration error",
  "status": 422,
  "detail": "The source wallet is missing required custody configuration.",
  "resolution": "Check the wallet's custody setup in your dashboard. If the wallet was recently created or converted, ensure the custody activation step completed successfully.",
  "docs": "/errors#crypto-wallet-misconfigured",
  "instance": "/v2/transactions/txn_abc123",
  "correlationId": "corr_xyz789",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

​
Common causes

  • Incomplete custody activation — a non-custodial wallet application was approved but the custody activation step did not complete successfully
  • Wallet conversion in progress — a wallet custody conversion (custodial to non-custodial or vice versa) was started but not completed before a payout was attempted

​
Recovery

This is a terminal state. No funds were moved. The original transaction cannot be recovered; you must resolve the wallet configuration before submitting a new transaction.
1. Confirm the terminal state 
curl -X GET https://api.conduit.financial/v2/transactions/txn_abc123 \
  -H "x-api-key: YOUR_API_KEY"
The response will show status: "failed" and failureCode: "CRYPTO_WALLET_MISCONFIGURED". 2. Check the wallet status 
curl -X GET https://api.conduit.financial/v2/customers/{{customerId}}/wallets/{{walletId}} \
  -H "x-api-key: YOUR_API_KEY"
Inspect the status field. An ACTIVE wallet should have complete custody configuration. If the wallet is in a non-ACTIVE status, investigate the application or conversion flow. 3. Contact support if the wallet appears active If the wallet status is ACTIVE but payouts still fail with this code, contact support with the wallet ID and transaction ID. The custody configuration may need to be repaired by the Conduit team.

​
Prevention

  • Wait for wallet activation — do not submit payouts against a wallet until its status is ACTIVE and any pending applications or conversions have completed
  • Handle transaction.failed with this code — branch on failureCode === 'CRYPTO_WALLET_MISCONFIGURED' to surface a “wallet setup incomplete” message and direct the customer to complete the activation flow
The transaction.failed event fires when the misconfiguration is detected: 
{
  "type": "transaction.failed",
  "data": {
    "transactionId": "txn_abc123",
    "failureCode": "CRYPTO_WALLET_MISCONFIGURED"
  }
}