API Integration

The Wallet Verification Widget is the fastest way to go live, but you can also integrate directly via the API. Every capability available in the widget is exposed through our REST endpoints, so you can build a custom UI or support native mobile flows.

Cryptographic signature proofs are the industry standard for verifying wallet ownership. The user signs an off-chain message with their private key, and you validate that signature against the blockchain address. This provides cryptographic assurance that the user controls the wallet they intend to use.

CryptoSwift advocates open-source, industry-standard solutions for signature proofs. WalletConnect (now Reown) is the most robust option, with broad wallet compatibility. It supports 450+ wallets across networks like Bitcoin, Ethereum, Solana, Optimism, Arbitrum, Base, Polygon, BNB, Avalanche, and Cosmos. See the full list here.

Visit Reown or explore the Reown docs to get started.

You can integrate directly with Reown and then store the verification result in CryptoSwift.

Also see the web-based Wallet Connect demo.

Once verification completes, send a request to the CryptoSwift API:

curl --location 'https://api-dev.cryptoswift.eu/wallet-verification/signature-proof' \
--header 'x-api-key: $API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "withdrawalAddress": "0x32Be343B94f860124dC4fEe278FDCBD38C102D88",
  "withdrawalMetadata": "be0bf82b-426e-40a6-a4e5-09800db30908",
  "asset": "ETH",
  "blockchain": "Ethereum",
  "signedMessage": "app.cryptoswift.eu:8080 wants you to sign in with your **blockchain** account:\n0x32Be343B94f860124dC4fEe278FDCBD38C102D88\n\nURI:https://app.cryptoswift.eu:8080/\nVersion: 1\nChain ID: eip155:1\nNonce: 1961\nIssued At: 2025-05-30 12:49:49",
  "signature": "q7XUz9XJbWjK9YO2iA8eW3OmEDCuqKDG12tzmPVNlDb9X6G6MxwGqv8J8B4gEZq43vU3D9VaGRKqB1wnyCrR7A=",
  "origin": "https://app.cryptoswift.eu:8080"
}'

Mandatory fields:

• withdrawalAddress: Self-hosted wallet address to verify
• asset: The virtual asset
• blockchain: The blockchain
• signedMessage: The original signed message proving wallet ownership. The message must include domain, chain id, and issued at fields as shown in the example above.
• signature: The cryptographic signature of the message
• origin: The origin <scheme>://<hostname>[:<port>] that will be used while validating the signature

Optional fields:

• withdrawalMetadata: Metadata to identify the wallet or user outside of the CryptoSwift system

More details: API documentation

A Satoshi test verifies ownership by sending a specific amount of cryptocurrency from the destination wallet within a set time frame. The CryptoSwift API supports this method.

Please ensure you set up a webhook before initiating a Satoshi test verification.

curl --location 'https://api-dev.cryptoswift.eu/wallet-verification/satoshi-test' \
--header 'x-api-key: $API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "withdrawalAddress": "BsRdeZ75szhDiGN8hJs8v8PcqwBm7KsFcp",
    "withdrawalMetadata": "505b5625-fd42-4c03-911b-2310ea14b76a",
    "depositAddress": "bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kygt080",
    "asset": "BTC"
}'

Mandatory fields:

• withdrawalAddress
• depositAddress
• asset: Must be one of BTC, DASH, DOGE, LTC
• blockchain

Optional fields:

• amount: If not provided, a random value will be generated
• withdrawalMetadata

The response includes:

• verificationRequestId
• asset, amount, withdrawalAddress, depositAddress
• status, statusReasoning, verifiedTransactionHash, createdAt, updatedAt

Share the depositAddress, asset, and amount with the wallet owner. The verification expires 48 hours after the createdAt timestamp.

Webhook header: X-Event-Type: 'wallet-verification'

Example success payload:

{
    ...
    "verificationRequestId": "53c8264f-5632-4ed2-b93e-42aa0bcd5830",
    "status": "VERIFIED",
    "verifiedTransactionHash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
    ...
}

More details: API documentation

This method involves uploading a screenshot as proof of ownership.

curl --location 'https://api-dev.cryptoswift.eu/wallet-verification/visual-proof' \
--header 'x-api-key: $API_KEY' \
--form 'file=@"../Visual Proof.pdf"' \
--form 'withdrawalAddress="bc1q7jxz3fgnzm9wp6t8qn8ekq09l8gwux5zft90je"' \
--form 'asset="BTC"'

Mandatory fields:

• file: JPEG, PNG, JPG, or PDF up to 5MB
• withdrawalAddress
• asset
• blockchain

Optional fields:

• withdrawalMetadata

curl --location --request PATCH 'https://api-dev.cryptoswift.eu/wallet-verification/2770f7b9-3397-44d7-88c7-d7642be38329' \
--header 'x-api-key: $API_KEY' \
--header 'Content-Type: application/json' \
--data '{"status":"VERIFIED", "statusReasoning": "Manual approval", "withdrawalMetadata": "Any related metadata" }'

Mandatory fields:

• status: PENDING, VERIFIED, FAILED, or DELETED

Optional fields:

• statusReasoning, withdrawalMetadata

More details: API documentation

This method allows users to self-declare wallet ownership with a checkbox.

curl --location 'https://api-dev.cryptoswift.eu/wallet-verification/self-declared' \
--header 'x-api-key: $API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "withdrawalAddress": "BsRdeZ75szhDiGN8hJs8v8PcqwBm7KsFcp",
    "withdrawalMetadata": "05b5625-fd42-4c03-911b-2310ea14b76a",
    "approved": true,
    "asset": "BTC"
}'

Mandatory fields:

• withdrawalAddress
• asset
• blockchain
• approved: Must be true

Optional fields:

• withdrawalMetadata

The request will be verified immediately.

More details: API documentation

• Wallet verification widget
• Webhooks
• Get started