Transactions — Nuvanté developers

Endpoints

Transaction endpoints

Method	Path	Purpose
POST	`/api/v1/transactions`	Initiate a redeem or swap transaction.
GET	`/api/v1/transactions`	List the transactions you can see, with filters and pagination.
GET	`/api/v1/transactions/{id}`	Poll one transaction and its saga summary.
POST	`/api/v1/transactions/{id}/cancel`	Ask to cancel, as long as data.actions.cancel.allowed is true.

Initiating and cancelling need the transactions:write scope. Listing and reading need transactions:read, and transactions:write covers them too.

Initiate a redemption

Set useCase to redeem or swap. The source and target amounts are nested money objects. A successful request returns 201.

curl --request POST 'https://sandbox-api.nuvante.io/api/v1/transactions' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: redeem-20260730-0001' \
  --data '{
  "paymentReference": "DVP-REDEEM-0001",
  "source": {
    "amount": "250000.00",
    "asset": {
      "code": "GBPC",
      "issuer": "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJUWDA"
    }
  },
  "target": {
    "amount": "250000.00",
    "asset": {
      "code": "GBP"
    }
  },
  "useCase": "redeem"
}'

Try in sandbox

For a redemption, send the same stated amount for source and target. The engine adds the fee to the on-chain burn, so debitAmount = receiveAmount + platformFeeAmount under the active FeePolicy (10 bps today). For a stated 250,000.00, that gives receiveAmount=250000.00, platformFeeAmount=250.00 and debitAmount=250250.00.

Request schema

Fields
Field	Type	Required	Description
paymentReference	string (1–64)	Yes	Your own business reference. It has to be unique for your participant, and reusing one causes a conflict.
source.amount	positive decimal string	Yes	Up to seven decimal places. The issuer's precision may allow fewer, and fiat settlement allows two.
source.asset.code	string (1–12)	Yes	The source asset code.
source.asset.issuer	string	Yes	Always required, because every supported source asset is a chain-issued stablecoin.
target.amount	positive decimal string	Yes	The target amount. The same precision limits apply.
target.asset.issuer	string	No	Required for a swap. Leave it out for a redemption, where the target code must be GBP.
useCase	redeem or swap	Yes	The full list of public use cases.

Poll one transaction

curl 'https://sandbox-api.nuvante.io/api/v1/transactions/123e4567-e89b-42d3-a456-426614174000' \
  --header 'Authorization: Bearer <api-key>'

Try in sandbox

Stop polling automatically as soon as data.terminal is true. A parked transaction shows lifecycleStatus: "failed", parked: true and terminal: true on purpose. It won't move again until an operator steps in.

List and poll

You can filter the list by lifecycleStatus, assetCode, amount range and date range, and page through it with page and pageSize. Pages hold 50 items by default and up to 200.

curl 'https://sandbox-api.nuvante.io/api/v1/transactions?lifecycleStatus=in-flight&page=1&pageSize=50' \
  --header 'Authorization: Bearer <api-key>'

Try in sandbox

The list meta contains commandId, page, pageSize, total and totalPages. You can also filter with from, to, assetCode, participantId, amountMin, amountMax and q.

Cancel

curl --request POST 'https://sandbox-api.nuvante.io/api/v1/transactions/123e4567-e89b-42d3-a456-426614174000/cancel' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: cancel-20260730-0001'

Try in sandbox

You can only cancel before the source burn, and before settlement has started. Check actions.cancel before you offer a cancel button. A cancellation that comes too late, is repeated, or isn't allowed for any other reason returns 409 conflict.

Settlement model

Understand derived settlement modes →