Skip to content

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:

  1. Create a verification, optionally requesting additional steps or reusable ownership evidence.
  2. Read the create response. If ownership is already VERIFIED through reuse, skip the ownership challenge. Otherwise, submit proof for the selected flow.
  3. Collect and submit any requested additional evidence. Review documents manually, and handle Selfie liveness analysis according to your settings.
  4. 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
}'
Always double-check you are using the correct environment when integrating. Using the wrong base URL or API key will result in authentication errors.

Mandatory fields:

  • asset: The virtual asset, for example ETH or BTC
  • blockchain: The blockchain name or supported EVM chain ID
  • address: Self-hosted wallet address to verify

Optional fields:

  • metadata: Your own wallet, user, or case reference
  • allowedFlows: Restrict which proof methods can be used
  • origin: Required when validating browser-origin-bound signature messages
  • expiresInHours: Expiration for the entire verification flow, from 1 to 100 hours; defaults to 48
  • satoshiFlow: Required when you allow SATOSHI_TEST; include depositAddress and optional amount
  • additionalSteps: Request Source of Funds / Source of Wealth or Selfie / Liveness checks
  • reuse: 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
    }
  }
}'

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 match
  • MEDIUM: Address, blockchain, and name hash match
  • HIGH: Address, blockchain, subject type, and name hash match

Handle both create outcomes:

Create responseWhat your integration does next
status: "VERIFIED" with reuse detailsOwnership is complete. No proof submission or Widget token is needed.
status: "PENDING" and reuse: nullCollect 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.

StepWhat your custom integration must handle
SOURCE_OF_FUNDS_WEALTHCollect documents, submit multipart files, and have your team accept or decline the evidence.
SELFIEFollow 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:

ActionEndpoint
Submit evidencePOST /wallet-verification/{id}/additional-steps/{type}
Read step statuses and Selfie analysisGET /wallet-verification/{id}
Retrieve temporary evidence URLsGET /wallet-verification/{id}/additional-steps/{type}/signed-urls
Accept or decline a stepPATCH /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 flowPrimary request formatWhat submission does
SIGNATURE_PROOFapplication/jsonVerifies the submitted message and signature against the wallet address. A valid proof completes the flow with VERIFIED.
SELF_DECLAREDapplication/jsonRecords the wallet owner's declaration and immediately completes the flow with VERIFIED.
SATOSHI_TESTapplication/jsonStarts monitoring for the configured transaction. The verification remains PENDING until CryptoSwift detects a match.
VISUAL_PROOFmultipart/form-dataUploads 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.

OpenAPI content type

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.

Keep your API key on the server

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_PROOF
  • message: The exact, non-empty plain-text message signed by the wallet
  • signature: 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>"
  }'
Always double-check you are using the correct environment when integrating. Using the wrong base URL or API key will result in authentication errors.

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"
  }
}'

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"
}'

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_PROOF
  • files: One to three files, using a separate files part for each file

File limits:

  • Images and PDFs: jpeg, jpg, png, or pdf, max 5MB each
  • Videos: mp4, webm, mov, avi, wmv, mkv, mpeg, m4v, or 3gp, 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'
Always double-check you are using the correct environment when integrating. Using the wrong base URL or API key will result in authentication errors.

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"
}'

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/json
  • X-Event-Type: wallet-verification
  • CryptoSwift-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"

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"
}'

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"

Supported statuses:

  • PENDING: Verification has been created and is waiting for proof or completion
  • VERIFIED: Ownership is verified
  • ACTION_REQUIRED: Manual VASP action is required
  • DECLINED: Manual review rejected the proof
  • FAILED: Automated verification failed
  • DELETED: 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'

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