Skip to main content

​
What Is a Transfer Offer?

On Canton, asset transfers are modeled as transfer offers rather than immediate, unilateral transactions like those found on most public blockchains. A transfer offer represents a two-step, consent-based transfer:
  1. The sender creates an offer specifying the recipient and amount.
  2. The recipient explicitly accepts or rejects the offer.
This design enables privacy-preserving, compliant, and deterministic settlement between known parties—an important distinction from public blockchains where transactions are typically broadcast and finalized immediately.

​
Transfer Offer Lifecycle

1

Sender creates a transfer offer

The sender creates a transfer offer specifying the recipient Canton wallet, token, and amount. The specified amount of the asset is locked and cannot be used while the offer is pending.
2

Offer is received by destination wallet

The transfer offer becomes visible to the recipient’s Canton wallet
3

Accept or reject the offer

The recipient explicitly accepts or rejects the offer. Accepting executes the transfer, while rejecting declines it with no asset movement.

​
Create Transfer Offer

A transfer offer is created by the sender to propose transferring a specified amount of token to a Canton wallet. The offer remains pending until the recipient takes action. Creating a transfer offer utilizes the existing on-chain transfer functionality. For more details please checkout Creating Single Transfers
The transaction remains in a PENDING state until the recipient accepts or rejects the transfer offer.

​
Retrieving Transfer Offers

HIFI provides endpoints to retrieve transfer offers for a wallet, including all incoming offers or a specific offer.

​
Get All Incoming Transfer Offers

Retrieve all transfer offers for a specific wallet using wallet id. Request 
curl -X GET "https://api.hifibridge.com/v2/wallets/:walletId/offers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
Response 
{
  "count": 1,
  "records": [
    {
      "id": "3b6f7b9a-1f3a-4c8c-9c51-82f3e1c9a111",
      "status": "RECEIVED",
      "amount": "100.00",
      "currency": "usdcx",
      "source": { 
		"party": "HIFI-validator-1::1220c44096409d3244021ae82992ccae3a1208fa79cacf450760b6f2cd9dfee2daa6" 
	  },
      "destination": {
        "userId": "7c91b1e0-0a43-4f7c-9c88-3eaa9f41c9dd",
        "userWalletId": "9d1f1a0e-2d84-4e3b-9c92-6a9b6a7e1f23",
        "party": "HIFI-validator-1::1220e636b510224be2c15b4436c0eb72558fdd6a93268b3605fad7f27f58192910e6"
      },
      "creationTransactionHash": "122095966f1d10cbf4de93e55fd0ecca745b7aba0ae48647c9ae298dbc6f57de9ef8",
      "executionTransactionHash": null,
      "createdAt": "2026-02-02T18:21:00Z",
      "updatedAt": "2026-02-02T18:21:00Z",
      "expiresAt": "2026-02-03T18:21:00Z"
    },
  ],
  "nextCursor": "2026-02-02T18:22:00Z"
}

​
Get a Specific Transfer Offer

Retrieve details for a single transfer offer by ID. Request 
curl -X GET "https://api.hifibridge.com/v2/wallets/:walletId/offers/:offerId" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
Response 
{
  "id": "3b6f7b9a-1f3a-4c8c-9c51-82f3e1c9a111",
  "status": "RECEIVED",
  "amount": "100.00",
  "currency": "usdcx",
  "source": { 
	"party": "HIFI-validator-1::1220c44096409d3244021ae82992ccae3a1208fa79cacf450760b6f2cd9dfee2daa6" 
  },
  "destination": {
    "userId": "7c91b1e0-0a43-4f7c-9c88-3eaa9f41c9dd",
    "userWalletId": "9d1f1a0e-2d84-4e3b-9c92-6a9b6a7e1f23",
    "party": "HIFI-validator-1::1220e636b510224be2c15b4436c0eb72558fdd6a93268b3605fad7f27f58192910e6"
  },
  "creationTransactionHash": "122095966f1d10cbf4de93e55fd0ecca745b7aba0ae48647c9ae298dbc6f57de9ef8",
  "executionTransactionHash": null,
  "createdAt": "2026-02-02T18:21:00Z",
  "updatedAt": "2026-02-02T18:21:00Z",
  "expiresAt": "2026-02-03T18:21:00Z"
}

​
Action Transfer Offer

Once a transfer offer has been received, the recipient can accept or reject the offer. The choice determines whether the asset will be credited into recipient’s wallet or not.
A transfer offer must be accepted or rejected by the recipient before it expires. Once the expiration time passes, the offer is no longer valid.

​
Accept a Transfer Offer

Accepting a transfer offer executes the asset transfer and finalizes the transaction.
  • The transfer moves the locked asset to the recipient’s wallet.
  • The offer status will terminiate at ACCEPTED.
Request 
curl -X POST "https://api.hifibridge.com/v2/wallets/<walletId>/offers/<offerId>/accept" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "id": "3b6f7b9a-1f3a-4c8c-9c51-82f3e1c9a111",
  "status": "PENDING",
  "amount": "100.00",
  "currency": "usdcx",
  "source": { 
	"party": "HIFI-validator-1::1220c44096409d3244021ae82992ccae3a1208fa79cacf450760b6f2cd9dfee2daa6" 
  },
  "destination": {
    "userId": "7c91b1e0-0a43-4f7c-9c88-3eaa9f41c9dd",
    "userWalletId": "9d1f1a0e-2d84-4e3b-9c92-6a9b6a7e1f23",
    "party": "HIFI-validator-1::1220e636b510224be2c15b4436c0eb72558fdd6a93268b3605fad7f27f58192910e6"
  },
  "creationTransactionHash": "122095966f1d10cbf4de93e55fd0ecca745b7aba0ae48647c9ae298dbc6f57de9ef8",
  "executionTransactionHash": null,
  "createdAt": "2026-02-02T18:21:00Z",
  "updatedAt": "2026-02-02T18:21:00Z",
  "expiresAt": "2026-02-03T18:21:00Z"
}
Behavior
  • Transaction status changes from PENDING → ACCEPTED
  • executionTransactionHash is set once the transfer is executed
  • Your system can listen to the WALLET.OFFER.ACCEPTED webhook to trigger downstream actions

​
Reject a Transfer Offer

Rejecting a transfer offer declines the proposed transfer.
  • The locked asset is released back to the sender.
  • The offer status updates to REJECTED.

​
Request

curl -X POST "https://api.hifibridge.com/v2/wallets/<walletId>/offers/<offerId>/reject" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "id": "3b6f7b9a-1f3a-4c8c-9c51-82f3e1c9a111",
  "status": "PENDING",
  "amount": "100.00",
  "currency": "usdcx",
  "source": { 
	"party": "HIFI-validator-1::1220c44096409d3244021ae82992ccae3a1208fa79cacf450760b6f2cd9dfee2daa6" 
  },
  "destination": {
    "userId": "7c91b1e0-0a43-4f7c-9c88-3eaa9f41c9dd",
    "userWalletId": "9d1f1a0e-2d84-4e3b-9c92-6a9b6a7e1f23",
    "party": "HIFI-validator-1::1220e636b510224be2c15b4436c0eb72558fdd6a93268b3605fad7f27f58192910e6"
  },
  "creationTransactionHash": "122095966f1d10cbf4de93e55fd0ecca745b7aba0ae48647c9ae298dbc6f57de9ef8",
  "executionTransactionHash": null,
  "createdAt": "2026-02-02T18:21:00Z",
  "updatedAt": "2026-02-02T18:21:00Z",
  "expiresAt": "2026-02-03T18:21:00Z"
}

​
Behavior

  • Transaction status changes from PENDING → REJECTED
  • executionTransactionHash is set once the rejection is recorded
  • Your system can listen to the WALLET.OFFER.REJECTED webhook to trigger downstream actions

​
Offer Statuses

Each Canton transfer offer has a status that reflects its current state:
StatusDescription
RECEIVEDThe offer has been received by the destination wallet and is ready to be acted upon.
PENDINGThe offer is currently in the process of being accepted or rejected.
ACCEPTEDThe recipient has accepted the offer. The transfer has been executed and the asset has been moved.
REJECTEDThe recipient has rejected the offer. No transfer occurred, and the locked asset has been released back to the sender.

​
Webhook Notifications

HIFI sends webhook events to notify your system of transfer offer state changes.
Webhook EventDescription
WALLET.OFFER.RECEIVEDA new transfer offer has been received by the destination wallet and is ready to be acted upon.
WALLET.OFFER.PENDINGThe transfer offer is currently being accepted or rejected.
WALLET.OFFER.ACCEPTEDThe recipient has accepted the offer. The transfer has been executed and the asset moved.
WALLET.OFFER.REJECTEDThe recipient has rejected the offer. No transfer occurred, and the locked asset is released.
Listen to the WALLET.OFFER.RECEIVED webhook events to be notified whenever a new incoming transfer offer is available for action.

​
Getting Help