Wallet Management - Your Crypto Treasury! 💰

Example 2: Check Regular Wallet Balance

For custodial wallets.

Request:

curl https://api.zendfi.tech/api/v1/merchants/me/wallet \
  -H "Authorization: Bearer zfi_live_xyz789..."

Response:

{
  "wallet_address": "9yKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsW",
  "wallet_type": "custodial",
  "sol_balance": 2.35,
  "usdc_balance": 5678.90,
  "usdc_token_account": "AzKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsX",
  "has_mpc_wallet": false
}

What This Tells You:

• You have a custodial wallet (mnemonic or simple)
• Balance: 2.35 SOL + 5,678.90 USDC
• Key is managed by ZendFi (cannot export via API)
• Contact support for withdrawals

Example 3: Check External Wallet Balance

For your own wallet like Phantom.

Request:

curl https://api.zendfi.tech/api/v1/merchants/me/wallet \
  -H "Authorization: Bearer zfi_live_def456..."

Response:

{
  "wallet_address": "BxKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsY",
  "wallet_type": "external",
  "sol_balance": 10.5,
  "usdc_balance": 0.0,
  "usdc_token_account": "CzKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsZ",
  "has_mpc_wallet": false
}

What This Tells You:

• You're using your own wallet (Phantom, Solflare, etc.)
• Balance: 10.5 SOL + 0 USDC
• Manage funds directly in your wallet app
• No API-based withdrawals needed (you already control the wallet!)

400 Bad Request - No MPC Wallet

{
  "error": "MPC wallet not found",
  "message": "This merchant doesn't have an MPC wallet. Only MPC wallets support key export."
}

Solution: Only MPC wallets can export keys. Contact support if you need access to custodial wallet keys.

401 Unauthorized - Invalid Passkey

{
  "error": "Failed to export key: Invalid passkey signature"
}

Solution: - Ensure you completed passkey authentication correctly - Check that credential_id matches your registered passkey - Verify signature data is correct - Try authenticating again

500 Internal Server Error

{
  "error": "Failed to export key: Failed to combine shards"
}

Solution: - Internal error combining MPC shards - Contact support with the timestamp - This is rare - may indicate network issues with Lit Protocol

Example 2: Withdraw USDC to Exchange

Request:

curl -X POST https://api.zendfi.tech/api/v1/merchants/me/wallet/withdraw \
  -H "Authorization: Bearer zfi_live_xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "to_address": "BxKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsY",
    "amount": 1000.00,
    "token": "Usdc",
    "passkey_signature": {
      "credential_id": "DEF456...ABC789",
      "authenticator_data": [73, 150, 13, 229, ...],
      "signature": [48, 69, 2, 33, ...],
      "client_data_json": [123, 34, 116, 121, ...]
    }
  }'

Response:

{
  "success": true,
  "transaction_signature": "6LzZ8LWvZh7NYjJvPhHGYnNrB2rKqb2nnU6NJR4zHYQZ3k2PxMhR7vA8sB9cC0dD1eE2fF3gG4hH5iI6jJ7kK9",
  "from_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "to_address": "BxKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsY",
  "amount": 1000.00,
  "token": "Usdc",
  "explorer_url": "https://solscan.io/tx/6LzZ8LWvZh7NYjJvPhHGYnNrB2rKqb2nnU6NJR4zHYQZ..."
}

What Happened:

• 1,000 USDC withdrawn from your MPC wallet
• Sent to your exchange deposit address
• USDC token account created automatically if needed
• Ready to cash out on the exchange!

Example 3: Withdraw Small Amount for Testing

Request:

curl -X POST https://api.zendfi.tech/api/v1/merchants/me/wallet/withdraw \
  -H "Authorization: Bearer zfi_test_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "to_address": "CzKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsZ",
    "amount": 0.01,
    "token": "Usdc",
    "passkey_signature": {
      "credential_id": "GHI789...DEF012",
      "authenticator_data": [73, 150, 13, 229, ...],
      "signature": [48, 69, 2, 33, ...],
      "client_data_json": [123, 34, 116, 121, ...]
    }
  }'

Response:

{
  "success": true,
  "transaction_signature": "7LzZ8LWvZh7NYjJvPhHGYnNrB2rKqb2nnU6NJR4zHYQZ3k2PxMhR7vA8sB9cC0dD1eE2fF3gG4hH5iI6jJ7kL0",
  "from_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "to_address": "CzKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsZ",
  "amount": 0.01,
  "token": "Usdc",
  "explorer_url": "https://solscan.io/?cluster=devnet/tx/7LzZ8LWvZh7NYjJvPhHGYnNrB2rKqb2nnU6NJR4zHYQZ..."
}

What This Shows:

• Test withdrawal of $0.01 USDC
• Perfect for testing before large amounts
• Devnet explorer URL (notice ?cluster=devnet)
• Always test first!

400 Bad Request - Invalid Amount

{
  "error": "Amount must be greater than 0"
}

Solution: Use positive amounts only (no zero or negative).

400 Bad Request - Invalid Address

{
  "error": "Invalid destination address"
}

Solution: - Check that to_address is a valid Solana address - Must be base58 format - Cannot be empty or malformed

400 Bad Request - No MPC Wallet

{
  "error": "MPC wallet not found",
  "message": "This merchant doesn't have an MPC wallet."
}

Solution: Only MPC wallets support API withdrawals. Contact support for custodial wallet withdrawals.

401 Unauthorized - Invalid Passkey

{
  "error": "Withdrawal failed: Invalid passkey signature"
}

Solution: - Complete passkey authentication correctly - Ensure signature data is accurate - Try authenticating again

500 Internal Server Error - Insufficient Balance

{
  "error": "Withdrawal failed: Insufficient balance"
}

Solution: - Check your balance with GET /api/v1/merchants/me/wallet - Ensure you have enough for the withdrawal + transaction fee (~0.000005 SOL) - For USDC: need SOL for transaction fees too

1. Get Passkey Setup Page

GET /merchants/{merchant_id}/setup-passkey

Authentication: None (public URL)

What It Does:

• Displays a beautiful setup page with instructions
• Guides you through passkey registration
• Shows real-time status updates
• Automatically creates MPC wallet after passkey registration

How To Use: When you create an MPC merchant, you'll receive a passkey_setup_url like:

https://api.zendfi.tech/merchants/550e8400-e29b-41d4-a716-446655440000/setup-passkey

Just open it in a browser and follow the instructions!

2. Check Passkey Status

GET /api/merchants/{merchant_id}/passkey-status

Authentication: None (public endpoint for merchant onboarding)

Response:

{
  "has_passkey": true,
  "has_mpc_wallet": true,
  "wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
}

Use Case: Poll this endpoint to check if passkey setup is complete.

3. WebAuthn Registration (Programmatic)

For advanced users who want to integrate passkey setup into their own UI:

Start Registration

POST /api/v1/webauthn/register/start

Request:

{
  "merchant_id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "merchant@example.com",
  "display_name": "Awesome Coffee Shop"
}

Response:

{
  "challenge_id": "660e8400-e29b-41d4-a716-446655440001",
  "options": {
    "challenge": "abc123...",
    "rp": {
      "name": "ZendFi",
      "id": "api.zendfi.tech"
    },
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "merchant@example.com",
      "displayName": "Awesome Coffee Shop"
    },
    "pubKeyCredParams": [...],
    "timeout": 300000,
    "attestation": "none",
    "authenticatorSelection": {
      "residentKey": "required",
      "userVerification": "required"
    }
  }
}

Finish Registration

POST /api/v1/webauthn/register/finish

Request:

{
  "challenge_id": "660e8400-e29b-41d4-a716-446655440001",
  "credential": {
    "id": "ABC123...XYZ789",
    "rawId": "ABC123...XYZ789",
    "response": {
      "clientDataJSON": "eyJ0eXBlI...",
      "attestationObject": "o2NmbXRk..."
    },
    "type": "public-key"
  }
}

Response:

{
  "credential_id": "ABC123...XYZ789",
  "success": true
}

What Happens Next:

• Passkey is stored in database
• MPC wallet creation starts automatically (background job)
• Wallet ready in 5-10 seconds

4. WebAuthn Authentication (For Withdrawals/Exports)

When withdrawing funds or exporting keys, you'll need to authenticate with your passkey:

Start Authentication

POST /api/v1/webauthn/auth/start

Request:

{
  "merchant_id": "550e8400-e29b-41d4-a716-446655440000"
}

Response:

{
  "challenge_id": "770e8400-e29b-41d4-a716-446655440002",
  "options": {
    "challenge": "def456...",
    "rpId": "api.zendfi.tech",
    "allowCredentials": [
      {
        "type": "public-key",
        "id": "ABC123...XYZ789"
      }
    ],
    "userVerification": "required",
    "timeout": 300000
  }
}

Finish Authentication

POST /api/v1/webauthn/auth/finish

Request:

{
  "challenge_id": "770e8400-e29b-41d4-a716-446655440002",
  "credential": {
    "id": "ABC123...XYZ789",
    "rawId": "ABC123...XYZ789",
    "response": {
      "clientDataJSON": "eyJ0eXBlI...",
      "authenticatorData": "SZYN5YgOjGh0NBc...",
      "signature": "MEUCIQCqL...",
      "userHandle": "550e8400..."
    },
    "type": "public-key"
  }
}

Response:

{
  "success": true,
  "credential_id": "ABC123...XYZ789",
  "authenticator_data": [73, 150, 13, 229, ...],
  "signature": [48, 69, 2, 33, ...],
  "client_data_json": [123, 34, 116, 121, ...]
}

Use This Response: The authenticator_data, signature, and client_data_json fields become your passkey_signature for withdrawal/export requests!