Skip to content

Partner messaging API examples

Resolve a VASP, deliver an encrypted message, and update its transaction data.

These examples implement the standardized Partner -> CryptoSwift flow with X-Partner-Api-Key. Complete the directory prerequisites first. For the sequence and timing choices, see the network messaging overview.

1. Resolve the Beneficiary VASP

Choose the lookup pattern that fits your integration. If your product already lets a user select the counterparty VASP by name, fetch the verified entity directory and send the message to the selected VASP. If your flow starts with wallet details, search for the verified VASP by wallet address instead.

Option A: List Verified Entities

Use GET /partners/vasps before creating a transaction so your network can resolve verified VASPs and retrieve the public key needed for encryption.

Use q to search the directory. Set _cryptoSwiftTenantOnly=true when you only want VASPs with a CryptoSwift tenant rather than the wider verified entity directory.

curl --get 'https://api-dev.cryptoswift.eu/partners/vasps' \
  --data-urlencode 'q=Acme' \
  --data-urlencode '_cryptoSwiftTenantOnly=true' \
  --header 'X-Partner-Api-Key: <partner-api-key>'

Use the entity id as beneficiaryVaspId and use publicKey as the receiver public key for the IVMS101 encryption handshake.

Option B: Search for a Verified Entity by Wallet Address

Use GET /partners/vasps/by-wallet when you have the beneficiary wallet details and want CryptoSwift to identify the verified VASP tied to that address.

Required query parameters:

ParameterTypeDescription
addressstringWallet address of the entity to find.
blockchainstringBlockchain name, for example Ethereum.
assetstringAsset symbol, for example ETH.
curl --location 'https://api-dev.cryptoswift.eu/partners/vasps/by-wallet?address=0x1234567890abcdef1234567890abcdef12345678&blockchain=Ethereum&asset=ETH' \
  --header 'X-Partner-Api-Key: <partner-api-key>'

If the wallet is not tied to a verified VASP in CryptoSwift, the endpoint returns 404.

2. Deliver Travel Rule Messages

Use POST /partners/transactions to deliver a Partner -> CryptoSwift Travel Rule message for a verified beneficiary VASP. The request contains non-PII transaction metadata at the root level and the encrypted IVMS101 payload in the root-level ivms101 field.

Required fields:

FieldTypeDescription
assetstringAsset symbol used for the transaction.
amountnumberAmount of asset transferred.
blockchainInfoobjectBlockchain transaction details. destination is required inside this object.
ivms101stringEncrypted IVMS101 data.
originatorVaspIdstringOriginator VASP ID on the partner side.
originatorVaspPubKeystringOriginator VASP public key on the partner side.
beneficiaryVaspIdstringBeneficiary VASP ID on the CryptoSwift side.
{
  "asset": "BTC",
  "amount": 0.1,
  "blockchainInfo": {
    "transactionHash": "f4184fc596403b9d638783cf57adfe4c75c605f6356fbc91338530e9831e9e16",
    "origin": "17SkEw2md5avVNyYgj6RiXuQKNwkXaxFyQ",
    "destination": "1MLh2UVHgonJY4ZtsakoXtkcXDJ2EPU6RY",
    "destinationType": "CUSTODIAL",
    "blockchain": "Bitcoin"
  },
  "ivms101": "<base64 encrypted payload>",
  "originatorVaspId": "<originator VASP id>",
  "originatorVaspPubKey": "<originator VASP public key base64>",
  "beneficiaryVaspId": "<CryptoSwift beneficiary VASP id>",
  "createdAt": "2026-05-14T12:00:00.000Z"
}

createdAt is optional and is set automatically when omitted. originatorVaspPubKey must match the private key used to encrypt the IVMS101 payload.

Prepare the encrypted payload

Build the IVMS101 plaintext wrapper and party data, then encrypt it using the Message Encryption Protocol. The top-level request field ivms101 contains the encrypted base64 string.

curl --location --request POST 'https://api-dev.cryptoswift.eu/partners/transactions' \
  --header 'X-Partner-Api-Key: <partner-api-key>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "asset": "BTC",
    "amount": 0.1,
    "blockchainInfo": {
      "transactionHash": "f4184fc596403b9d638783cf57adfe4c75c605f6356fbc91338530e9831e9e16",
      "origin": "17SkEw2md5avVNyYgj6RiXuQKNwkXaxFyQ",
      "destination": "1MLh2UVHgonJY4ZtsakoXtkcXDJ2EPU6RY",
      "destinationType": "CUSTODIAL",
      "blockchain": "Bitcoin"
    },
    "ivms101": "<base64 encrypted payload>",
    "originatorVaspId": "<originator VASP id>",
    "originatorVaspPubKey": "<originator VASP public key base64>",
    "beneficiaryVaspId": "<CryptoSwift beneficiary VASP id>"
  }'

3. Update a Travel Rule Message

Use PATCH /partners/transactions/{id} to update an existing Partner transaction from the partner side. This is commonly used when the blockchain transaction hash becomes available after the Travel Rule message was delivered, or when other request data was missing or needs correction.

For blockchainInfo, the destination address cannot be modified through this endpoint.

curl --location --request PATCH 'https://api-dev.cryptoswift.eu/partners/transactions/<transaction-id>' \
  --header 'X-Partner-Api-Key: <partner-api-key>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "beneficiaryVaspId": "<CryptoSwift beneficiary VASP id>",
    "ivms101": "<updated base64 encrypted payload>",
    "originatorVaspId": "<originator VASP id>",
    "originatorVaspPubKey": "<originator VASP public key base64>",
    "blockchainInfo": {
      "transactionHash": "f4184fc596403b9d638783cf57adfe4c75c605f6356fbc91338530e9831e9e16",
      "origin": "17SkEw2md5avVNyYgj6RiXuQKNwkXaxFyQ",
      "destinationType": "CUSTODIAL",
      "blockchain": "Bitcoin"
    }
  }'

This success response has no body. Do not parse it as JSON.

CryptoSwift returns 404 if the referenced transaction or involved VASPs do not exist, and 400 when required payload fields are missing for decrypting IVMS101 data.

Next steps