API Integration
Build custom self-hosted verification flows with the REST API
The Wallet Verification Widget is the fastest way to go live, but you can also integrate directly via the API. Use the API when you want to build your own UI, support native mobile flows, or control each verification step from your backend.
A custom integration follows this sequence:
- Create a verification, optionally requesting additional steps or reusable ownership evidence.
- Read the create response. If ownership is already
VERIFIEDthrough reuse, skip the ownership challenge. Otherwise, submit proof for the selected flow. - Collect and submit any requested additional evidence. Review documents manually, and handle Selfie liveness analysis according to your settings.
- Reconcile the latest result on your backend. Check both wallet ownership and each required additional step before treating the case as complete.
1. Create a Verification
Create the wallet verification before collecting proof from the wallet owner.
curl --location 'https://api-dev.cryptoswift.eu/wallet-verification' \
--header "x-api-key: $API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"asset": "ETH",
"blockchain": "Ethereum",
"address": "0x32Be343B94f860124dC4fEe278FDCBD38C102D88",
"metadata": "customer-123",
"allowedFlows": ["SIGNATURE_PROOF", "VISUAL_PROOF", "SELF_DECLARED"],
"origin": "https://app.example.com",
"expiresInHours": 24
}'
{
"id": "9f3dc458-a2be-4a34-bcb7-f1f677a0864c",
"token": "<widget-token>",
"url": "https://wallet-dev.cryptoswift.eu/?token=<widget-token>",
"asset": "ETH",
"blockchain": "Ethereum",
"address": "0x32Be343B94f860124dC4fEe278FDCBD38C102D88",
"metadata": "customer-123",
"status": "PENDING",
"flow": null,
"allowedFlows": [
"SIGNATURE_PROOF",
"VISUAL_PROOF",
"SELF_DECLARED"
],
"reuse": null,
"expiresAt": "2026-11-12T09:00:00.000Z",
"createdAt": "2026-11-11T09:00:00.000Z",
"satoshiFlow": {
"amount": null,
"depositAddress": null
},
"statusReasoning": null,
"riskScore": null,
"warnings": [],
"origin": "https://app.example.com",
"redirectUrl": null
}
Mandatory fields:
asset: The virtual asset, for exampleETHorBTCblockchain: The blockchain name or supported EVM chain IDaddress: Self-hosted wallet address to verify
Optional fields:
metadata: Your own wallet, user, or case referenceallowedFlows: Restrict which proof methods can be usedorigin: Required when validating browser-origin-bound signature messagesexpiresInHours: Expiration for the entire verification flow, from 1 to 100 hours; defaults to 48satoshiFlow: Required when you allowSATOSHI_TEST; includedepositAddressand optionalamountadditionalSteps: Request Source of Funds / Source of Wealth or Selfie / Liveness checksreuse: Reusable ownership evidence, including the owner name hash and matching policy
Use id for all later status checks, proof submissions, manual updates, and webhook reconciliation.
Reusable Verification
Reusable verification can automatically complete a new verification by matching it with a previous eligible verified wallet verification for the same address and blockchain. Reuse matching is cross-tenant.
For a full explanation of matching policies, flow, and storage, see Reusable Wallet Verification.
curl --location 'https://api-dev.cryptoswift.eu/wallet-verification' \
--header "x-api-key: $API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"asset": "ETH",
"blockchain": "Ethereum",
"address": "0x32Be343B94f860124dC4fEe278FDCBD38C102D88",
"allowedFlows": ["SIGNATURE_PROOF"],
"reuse": {
"subject": {
"type": "NATURAL",
"nameHash": "608bf001fdc28154e03218bd08f86c83edd9bae125c6dd3044390caeff266608"
},
"policy": {
"minimumMatchLevel": "MEDIUM",
"maxReuseAgeDays": 180
}
}
}'
{
"id": "9f3dc458-a2be-4a34-bcb7-f1f677a0864c",
"asset": "ETH",
"blockchain": "Ethereum",
"address": "0x32Be343B94f860124dC4fEe278FDCBD38C102D88",
"status": "VERIFIED",
"statusReasoning": "Verification completed using reusable wallet verification",
"reuse": {
"matchLevel": "HIGH",
"matchedAttributes": [
"nameHash",
"type"
],
"policy": {
"minimumMatchLevel": "MEDIUM",
"maxReuseAgeDays": 180
}
},
"flow": "SIGNATURE_PROOF",
"metadata": null,
"createdAt": "2026-11-11T09:00:00.000Z",
"expiresAt": "2026-11-13T09:00:00.000Z",
"satoshiFlow": {
"amount": null,
"depositAddress": null
},
"riskScore": null,
"warnings": []
}
nameHash is required for reusable verification. Hash the owner's full name after NFKC normalization, trimming, lowercasing, and collapsing repeated whitespace to one space. Send the lowercase 64-character SHA-256 hex digest, not the plain-text name.
Matching levels:
LOW: Address, blockchain, and subject type matchMEDIUM: Address, blockchain, and name hash matchHIGH: Address, blockchain, subject type, and name hash match
Handle both create outcomes:
| Create response | What your integration does next |
|---|---|
status: "VERIFIED" with reuse details | Ownership is complete. No proof submission or Widget token is needed. |
status: "PENDING" and reuse: null | Collect and submit ownership proof using one of the allowed flows. |
reuse cannot be combined with a non-empty additionalSteps list. Requests containing both return 400 Bad Request before a verification is created. Omit reuse when fresh additional evidence is required.
Additional Steps
Add additionalSteps to the create request to collect supporting evidence after the ownership interaction. For example, include these fields alongside asset, blockchain, address, and your allowed ownership flows:
{
"additionalSteps": [
{
"type": "SOURCE_OF_FUNDS_WEALTH",
"settings": {
"customerMessage": "Please provide bank statements covering the last three months."
}
},
{
"type": "SELFIE",
"settings": { "autoConfirm": true }
}
]
}
You can request either step or both. Each step starts as PENDING. Omit reuse when requesting additional steps; the API rejects that combination.
| Step | What your custom integration must handle |
|---|---|
SOURCE_OF_FUNDS_WEALTH | Collect documents, submit multipart files, and have your team accept or decline the evidence. |
SELFIE | Follow the API-generated capture actions, submit images, video, and metadata, then read the backend liveness result. With autoConfirm: true, a passing result verifies the step automatically. Otherwise, manual review is required. |
API requests default autoConfirm to false. A custom Selfie UI must follow the returned action sequence; the Widget provides this capture experience ready to use.
Use these endpoints from your backend:
| Action | Endpoint |
|---|---|
| Submit evidence | POST /wallet-verification/{id}/additional-steps/{type} |
| Read step statuses and Selfie analysis | GET /wallet-verification/{id} |
| Retrieve temporary evidence URLs | GET /wallet-verification/{id}/additional-steps/{type}/signed-urls |
| Accept or decline a step | PATCH /wallet-verification/{id}/additional-steps/{type} |
The top-level status records ownership only. For example, status: "VERIFIED" with a Source of Funds / Source of Wealth step still at ACTION_REQUIRED means documents still need review. Updating ownership through the manual-update endpoint does not approve the additional steps.
See Additional Steps for complete submission examples, file limits, capture metadata, analysis statuses, and review requests. See the Additional steps workflow for the customer and reviewer journey.
2. Submit Proof of Ownership
Submit proof to the existing verification:
POST {{apiBaseUrl}}/wallet-verification/{id}/verification
This endpoint does not create a wallet verification. It operates on the existing verification identified by {id}. The verificationFlow value selects and initiates the method to use:
| Verification flow | Primary request format | What submission does |
|---|---|---|
SIGNATURE_PROOF | application/json | Verifies the submitted message and signature against the wallet address. A valid proof completes the flow with VERIFIED. |
SELF_DECLARED | application/json | Records the wallet owner's declaration and immediately completes the flow with VERIFIED. |
SATOSHI_TEST | application/json | Starts monitoring for the configured transaction. The verification remains PENDING until CryptoSwift detects a match. |
VISUAL_PROOF | multipart/form-data | Uploads evidence and sets the verification to ACTION_REQUIRED for manual review. |
Multipart is also supported for SIGNATURE_PROOF, SELF_DECLARED, and SATOSHI_TEST, but it is not required. VISUAL_PROOF requires multipart because it uploads files.
The Submit proof of ownership endpoint (Sandbox) may describe this shared endpoint as multipart/form-data because VISUAL_PROOF accepts file uploads. That endpoint-level annotation does not mean JSON is unsupported for the non-file flows listed above.
Authenticate with the X-Api-Key header, following the API authentication instructions. Collect the signature in the user's wallet, but submit it to CryptoSwift from your backend. Never expose an API key in browser or mobile code.
Cryptographic Signature Proof
Cryptographic signature proofs verify that the user controls the wallet by signing an off-chain message with the wallet's private key.
For SIGNATURE_PROOF, submit these request fields:
verificationFlow:SIGNATURE_PROOFmessage: The exact, non-empty plain-text message signed by the walletsignature: The resulting cryptographic signature
CryptoSwift verifies the signature and the address associated with the wallet-verification request. A successful proof sets the verification status to VERIFIED.
EVM Signature Scheme
For Ethereum and other supported EVM wallets, use EIP-191 plain-message signing, such as personal_sign or a wallet library's signMessage. The recovered signer must match the verification address. EIP-712 typed-data signatures and token-transfer authorizations are not accepted as ownership proof.
Generate a unique challenge containing the verification ID, a random nonce, and an issued-at timestamp. Submit the exact message that was signed. See EVM signature proof for message requirements, viem, ethers, browser-provider examples, and troubleshooting.
Submit the Signature as JSON with curl
Send the proof from your backend as application/json. Use the exact message and signature returned by the signing step.
API_KEY='<api-key>'
VERIFICATION_ID='<verification-id>'
curl --location --request POST \
'https://api-dev.cryptoswift.eu/wallet-verification/'"$VERIFICATION_ID"'/verification' \
--header "X-Api-Key: $API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"verificationFlow": "SIGNATURE_PROOF",
"message": "CryptoSwift wallet ownership verification | verificationId: <verification-id> | nonce: <cryptographically-random-nonce> | issuedAt: <ISO-8601-timestamp>",
"signature": "<0x-prefixed-signature>"
}'
{
"id": "9f3dc458-a2be-4a34-bcb7-f1f677a0864c",
"token": "<widget-token>",
"url": "https://wallet-dev.cryptoswift.eu/?token=<widget-token>",
"asset": "ETH",
"blockchain": "Ethereum",
"address": "0x32Be343B94f860124dC4fEe278FDCBD38C102D88",
"metadata": "customer-123",
"status": "VERIFIED",
"flow": "SIGNATURE_PROOF",
"allowedFlows": [
"SIGNATURE_PROOF",
"VISUAL_PROOF",
"SELF_DECLARED"
],
"reuse": null,
"expiresAt": "2026-11-12T09:00:00.000Z",
"createdAt": "2026-11-11T09:00:00.000Z",
"satoshiFlow": {
"amount": null,
"depositAddress": null
},
"statusReasoning": null,
"riskScore": null,
"warnings": [],
"origin": "https://app.example.com",
"redirectUrl": null,
"signature": "<0x-prefixed-signature>",
"message": "CryptoSwift wallet ownership verification | verificationId: <verification-id> | nonce: <cryptographically-random-nonce> | issuedAt: <ISO-8601-timestamp>"
}
Micro Transactions
A Satoshi Test verifies ownership by asking the wallet owner to send a specific amount of native asset from the self-hosted wallet to your deposit address.
Please ensure you set up a webhook before initiating a Satoshi Test verification.
Create the verification with SATOSHI_TEST allowed and provide satoshiFlow.depositAddress.
curl --location 'https://api-dev.cryptoswift.eu/wallet-verification' \
--header "x-api-key: $API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"asset": "BTC",
"blockchain": "Bitcoin",
"address": "17SkEw2md5avVNyYgj6RiXuQKNwkXaxFyQ",
"metadata": "customer-123",
"allowedFlows": ["SATOSHI_TEST"],
"satoshiFlow": {
"depositAddress": "1MLh2UVHgonJY4ZtsakoXtkcXDJ2EPU6RY"
}
}'
{
"id": "9f3dc458-a2be-4a34-bcb7-f1f677a0864c",
"token": "<widget-token>",
"url": "https://wallet-dev.cryptoswift.eu/?token=<widget-token>",
"asset": "BTC",
"blockchain": "Bitcoin",
"address": "17SkEw2md5avVNyYgj6RiXuQKNwkXaxFyQ",
"metadata": "customer-123",
"status": "PENDING",
"flow": null,
"allowedFlows": [
"SATOSHI_TEST"
],
"reuse": null,
"expiresAt": "2026-11-13T09:00:00.000Z",
"createdAt": "2026-11-11T09:00:00.000Z",
"satoshiFlow": {
"amount": 5e-08,
"depositAddress": "1MLh2UVHgonJY4ZtsakoXtkcXDJ2EPU6RY"
},
"statusReasoning": null,
"riskScore": null,
"warnings": [],
"origin": null,
"redirectUrl": null
}
If satoshiFlow.amount is omitted, CryptoSwift generates a random amount. Share the returned satoshiFlow.depositAddress, asset, and satoshiFlow.amount with the wallet owner.
Then select SATOSHI_TEST and start transaction monitoring:
curl --location 'https://api-dev.cryptoswift.eu/wallet-verification/9f3dc458-a2be-4a34-bcb7-f1f677a0864c/verification' \
--header "x-api-key: $API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"verificationFlow": "SATOSHI_TEST"
}'
{
"id": "9f3dc458-a2be-4a34-bcb7-f1f677a0864c",
"token": "<widget-token>",
"url": "https://wallet-dev.cryptoswift.eu/?token=<widget-token>",
"asset": "BTC",
"blockchain": "Bitcoin",
"address": "17SkEw2md5avVNyYgj6RiXuQKNwkXaxFyQ",
"metadata": "customer-123",
"status": "PENDING",
"flow": "SATOSHI_TEST",
"allowedFlows": [
"SATOSHI_TEST"
],
"reuse": null,
"expiresAt": "2026-11-13T09:00:00.000Z",
"createdAt": "2026-11-11T09:00:00.000Z",
"satoshiFlow": {
"amount": 5e-08,
"depositAddress": "1MLh2UVHgonJY4ZtsakoXtkcXDJ2EPU6RY"
},
"statusReasoning": null,
"riskScore": null,
"warnings": [],
"origin": null,
"redirectUrl": null
}
This submission does not create or configure the Satoshi Test; those details come from the existing wallet verification. It starts monitoring for the expected transaction. The verification stays PENDING until CryptoSwift detects a match, then changes to VERIFIED. Monitoring accepts matches until the verification's expiresAt. Set expiresInHours when creating the verification to choose a lifetime from 1 to 100 hours; the default is 48 hours. Older records without expiresAt use a 48-hour fallback from createdAt.
Visual Proof
Visual Proof lets a user upload visual proof of wallet ownership for manual review.
Send the media files as multipart files fields in the same proof-submission request:
POST {{apiBaseUrl}}/wallet-verification/{id}/verification
CryptoSwift receives the file contents from this request and stores them with the wallet verification. The verification then changes to ACTION_REQUIRED so your team can review the evidence.
Mandatory fields:
verificationFlow:VISUAL_PROOFfiles: One to three files, using a separatefilespart for each file
File limits:
- Images and PDFs:
jpeg,jpg,png, orpdf, max 5MB each - Videos:
mp4,webm,mov,avi,wmv,mkv,mpeg,m4v, or3gp, max 50MB each
Test a Local File with curl
The curl example is intended for manual testing. The @ prefix tells curl to read and upload a file that already exists on the machine running the command. Replace the path with the absolute path to your test file.
API_KEY='<api-key>' VERIFICATION_ID='<verification-id>' curl --location --request POST \ 'https://api-dev.cryptoswift.eu/wallet-verification/'"$VERIFICATION_ID"'/verification' \ --header "X-Api-Key: $API_KEY" \ --form 'verificationFlow=VISUAL_PROOF' \ --form 'files=@/absolute/path/to/wallet-screenshot.png'
{
"id": "9f3dc458-a2be-4a34-bcb7-f1f677a0864c",
"token": "<widget-token>",
"url": "https://wallet-dev.cryptoswift.eu/?token=<widget-token>",
"asset": "ETH",
"blockchain": "Ethereum",
"address": "0x32Be343B94f860124dC4fEe278FDCBD38C102D88",
"metadata": "customer-123",
"status": "ACTION_REQUIRED",
"flow": "VISUAL_PROOF",
"allowedFlows": [
"SIGNATURE_PROOF",
"VISUAL_PROOF",
"SELF_DECLARED"
],
"reuse": null,
"expiresAt": "2026-11-12T09:00:00.000Z",
"createdAt": "2026-11-11T09:00:00.000Z",
"satoshiFlow": {
"amount": null,
"depositAddress": null
},
"statusReasoning": "Please review the uploaded visual proof",
"riskScore": null,
"warnings": [],
"origin": "https://app.example.com",
"redirectUrl": null
}
For multiple files, repeat the files field:
--form 'files=@/absolute/path/to/wallet-screenshot.png' \ --form 'files=@/absolute/path/to/second-proof.pdf'
Upload a Customer-Selected File
In a production integration, the file usually comes from a file picker in your application. The browser sends the selected File objects to your backend. Your backend then forwards the multipart request to CryptoSwift with the API key.
Customer selects files in your UI
↓
Browser sends multipart data to your backend
↓
Your backend streams the multipart body to CryptoSwift
↓
CryptoSwift stores the files and returns the updated verification
Visual proof sets status to ACTION_REQUIRED. Review the uploaded proof and manually update the verification to VERIFIED or DECLINED.
Self-Declaration
Self-declaration lets the user declare wallet ownership without an on-chain transaction, screenshot, or signature.
curl --location 'https://api-dev.cryptoswift.eu/wallet-verification/9f3dc458-a2be-4a34-bcb7-f1f677a0864c/verification' \
--header "x-api-key: $API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"verificationFlow": "SELF_DECLARED"
}'
{
"id": "9f3dc458-a2be-4a34-bcb7-f1f677a0864c",
"token": "<widget-token>",
"url": "https://wallet-dev.cryptoswift.eu/?token=<widget-token>",
"asset": "ETH",
"blockchain": "Ethereum",
"address": "0x32Be343B94f860124dC4fEe278FDCBD38C102D88",
"metadata": "customer-123",
"status": "VERIFIED",
"flow": "SELF_DECLARED",
"allowedFlows": [
"SIGNATURE_PROOF",
"VISUAL_PROOF",
"SELF_DECLARED"
],
"reuse": null,
"expiresAt": "2026-11-12T09:00:00.000Z",
"createdAt": "2026-11-11T09:00:00.000Z",
"satoshiFlow": {
"amount": null,
"depositAddress": null
},
"statusReasoning": null,
"riskScore": null,
"warnings": [],
"origin": "https://app.example.com",
"redirectUrl": null
}
Submitting SELF_DECLARED records the wallet owner's declaration and ends the flow immediately by setting status to VERIFIED. No transaction, signature, file, or later monitoring step is required.
3. Receive Notification via Webhook
When a verification is updated or processed, CryptoSwift sends an HTTP POST to your tenant's configured webhook URL. The JSON body represents the current wallet-verification object.
Relevant request headers:
Content-Type: application/jsonX-Event-Type: wallet-verificationCryptoSwift-Signature: t=<timestamp>,s=<signature>
Always verify the CryptoSwift-Signature header before processing the body.
Example SIGNATURE_PROOF payload:
{
"id": "9f3dc458-a2be-4a34-bcb7-f1f677a0864c",
"address": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
"asset": "ETH",
"blockchain": "Ethereum",
"flow": "SIGNATURE_PROOF",
"metadata": "customer-123",
"status": "VERIFIED",
"statusReasoning": null,
"signature": "0xba467b233bba2bfc76cab7fc684924bc455ccdf75f91ed6e0129ca0527f5585c5992f0efdf8f53eeacc2204fd5c609aac1a149472643c92313d5cbdd6c64b5a11c",
"message": "CryptoSwift wallet ownership verification | verificationId: 9f3dc458-a2be-4a34-bcb7-f1f677a0864c | nonce: 7f9c2a6d8e41b305 | issuedAt: 2026-07-28T10:15:30.000Z",
"createdAt": "2026-07-28T10:14:52.381Z",
"expiresAt": "2026-07-30T10:14:52.381Z",
"updatedAt": "2026-07-28T10:15:34.127Z",
"verifiedTransactionHash": null,
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImMzZDJjZjUzLWIzNDEtNGM5YS1hMzliLTY2NTU3OTVmYmU3MiIsIm9yaWdpbiI6Imh0dHBzOi8vYXBwLmV4YW1wbGUuY29tIiwiaWF0IjoxNzg1MjMzNjkyLCJleHAiOjE3ODU0MDY0OTJ9.yli42pzTZoNSB8E5QIrvTA8dHOA7TQnNwJWnXwumqh0",
"origin": "https://app.example.com",
"allowedFlows": [
"SIGNATURE_PROOF",
"VISUAL_PROOF",
"SELF_DECLARED"
],
"redirectUrl": null,
"url": "https://wallet.cryptoswift.eu/?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImMzZDJjZjUzLWIzNDEtNGM5YS1hMzliLTY2NTU3OTVmYmU3MiIsIm9yaWdpbiI6Imh0dHBzOi8vYXBwLmV4YW1wbGUuY29tIiwiaWF0IjoxNzg1MjMzNjkyLCJleHAiOjE3ODU0MDY0OTJ9.yli42pzTZoNSB8E5QIrvTA8dHOA7TQnNwJWnXwumqh0",
"riskScore": 12,
"warnings": [],
"riskSeverity": "low",
"satoshiFlow": {
"amount": null,
"depositAddress": null
},
"reuse": null
}
Fields such as message, signature, verifiedTransactionHash, satoshiFlow, risk results, and reuse details depend on the selected flow and available analysis. Optional fields can be null or omitted.
Notifications can also describe additional-step submissions or review decisions. Retrieve the latest verification and inspect additionalSteps and, for Selfie, additionalStepResults.SELFIE; do not rely on the ownership status alone.
Process deliveries idempotently: do not assume that each update arrives only once or in order. Treat the webhook as a notification and retrieve the latest verification by id before making compliance decisions.
curl --location 'https://api-dev.cryptoswift.eu/wallet-verification/9f3dc458-a2be-4a34-bcb7-f1f677a0864c' \ --header "x-api-key: $API_KEY"
{
"id": "9f3dc458-a2be-4a34-bcb7-f1f677a0864c",
"token": "<widget-token>",
"url": "https://wallet-dev.cryptoswift.eu/?token=<widget-token>",
"asset": "ETH",
"blockchain": "Ethereum",
"address": "0x32Be343B94f860124dC4fEe278FDCBD38C102D88",
"metadata": "customer-123",
"status": "VERIFIED",
"flow": "SIGNATURE_PROOF",
"allowedFlows": [
"SIGNATURE_PROOF",
"VISUAL_PROOF",
"SELF_DECLARED"
],
"reuse": null,
"expiresAt": "2026-11-12T09:00:00.000Z",
"createdAt": "2026-11-11T09:00:00.000Z",
"satoshiFlow": {
"amount": null,
"depositAddress": null
},
"statusReasoning": null,
"riskScore": null,
"warnings": [],
"origin": "https://app.example.com",
"redirectUrl": null,
"signature": "<0x-prefixed-signature>",
"message": "CryptoSwift wallet ownership verification | verificationId: <verification-id> | nonce: <cryptographically-random-nonce> | issuedAt: <ISO-8601-timestamp>"
}
4. Manual Updates
For manual review flows, update the verification after your compliance team makes a decision.
curl --location --request PATCH 'https://api-dev.cryptoswift.eu/wallet-verification/9f3dc458-a2be-4a34-bcb7-f1f677a0864c' \
--header "x-api-key: $API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"status": "VERIFIED",
"statusReasoning": "Manual approval",
"metadata": "case-456"
}'
HTTP/1.1 204 No Content
This success response has no body. Do not parse it as JSON.
Read the updated record:
curl --location 'https://api-dev.cryptoswift.eu/wallet-verification/9f3dc458-a2be-4a34-bcb7-f1f677a0864c' \ --header "X-Api-Key: $API_KEY"
{
"id": "9f3dc458-a2be-4a34-bcb7-f1f677a0864c",
"token": "<widget-token>",
"url": "https://wallet-dev.cryptoswift.eu/?token=<widget-token>",
"asset": "ETH",
"blockchain": "Ethereum",
"address": "0x32Be343B94f860124dC4fEe278FDCBD38C102D88",
"metadata": "case-456",
"status": "VERIFIED",
"flow": "VISUAL_PROOF",
"allowedFlows": [
"SIGNATURE_PROOF",
"VISUAL_PROOF",
"SELF_DECLARED"
],
"reuse": null,
"expiresAt": "2026-11-12T09:00:00.000Z",
"createdAt": "2026-11-11T09:00:00.000Z",
"satoshiFlow": {
"amount": null,
"depositAddress": null
},
"statusReasoning": "Manual approval",
"riskScore": null,
"warnings": [],
"origin": "https://app.example.com",
"redirectUrl": null
}
Supported statuses:
PENDING: Verification has been created and is waiting for proof or completionVERIFIED: Ownership is verifiedACTION_REQUIRED: Manual VASP action is requiredDECLINED: Manual review rejected the proofFAILED: Automated verification failedDELETED: Verification was deleted
5. Search and delete verifications
Use GET /wallet-verification to build operational views or reconcile webhook processing. It supports free-text q, _flow, _status, _sort, _order, _start, and _end parameters. Pages can contain at most 100 records, and X-Total-Count contains the total number of matches.
curl --get 'https://api-dev.cryptoswift.eu/wallet-verification' \ --header "X-Api-Key: $API_KEY" \ --data-urlencode '_status=VERIFIED' \ --data-urlencode '_flow=SIGNATURE_PROOF' \ --data-urlencode '_start=0' \ --data-urlencode '_end=100' \ --data-urlencode '_sort=createdAt' \ --data-urlencode '_order=DESC'
[
{
"id": "9f3dc458-a2be-4a34-bcb7-f1f677a0864c",
"token": "<widget-token>",
"url": "https://wallet-dev.cryptoswift.eu/?token=<widget-token>",
"asset": "ETH",
"blockchain": "Ethereum",
"address": "0x32Be343B94f860124dC4fEe278FDCBD38C102D88",
"metadata": "customer-123",
"status": "VERIFIED",
"flow": "SIGNATURE_PROOF",
"allowedFlows": [
"SIGNATURE_PROOF",
"VISUAL_PROOF",
"SELF_DECLARED"
],
"reuse": null,
"expiresAt": "2026-11-12T09:00:00.000Z",
"createdAt": "2026-11-11T09:00:00.000Z",
"satoshiFlow": {
"amount": null,
"depositAddress": null
},
"statusReasoning": null,
"riskScore": null,
"warnings": [],
"origin": "https://app.example.com",
"redirectUrl": null,
"signature": "<0x-prefixed-signature>",
"message": "CryptoSwift wallet ownership verification | verificationId: <verification-id> | nonce: <cryptographically-random-nonce> | issuedAt: <ISO-8601-timestamp>"
}
]
Delete a verification with DELETE /wallet-verification/{id}. A successful deletion returns 204 No Content; the record is represented with the DELETED lifecycle status rather than being available for further verification work.
Next steps
- Wallet verification widget
- Reusable wallet verification
- Additional steps
- Supported blockchains
- Webhooks
- Self-hosted wallet verification endpoints (Sandbox)