Transactions: API examples

Generated from the public OpenAPI. Examples illustrate the contract and are not live results. Use your assigned gateway, credentials and identifiers. The snippets do not execute automatically.

Use Node.js 22 or later. Copy the setup below into an .mjs file, set QFP_BASE_URL and QFP_ACCESS_TOKEN, then append the operation snippet you need. No repository checkout or downloaded client is required. Keep secrets in your backend and persist each write key and body before sending.

Request setup

const required = name => {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name} before running this example`);
  return value;
};
const baseUrl = required('QFP_BASE_URL').replace(/\/$/, '');
if (!/^https:\/\//.test(baseUrl)) throw new Error('Use your assigned HTTPS gateway');
const token = required('QFP_ACCESS_TOKEN');
const segment = value => encodeURIComponent(value);
async function request(method, path, body, key) {
  const headers = { Authorization: `Bearer ${token}`, 'API-Version': '1.0.0', Accept: 'application/json' };
  if (key) headers['Idempotency-Key'] = key;
  const multipart = body instanceof FormData;
  if (body !== undefined && !multipart) headers['Content-Type'] = 'application/json';
  const response = await fetch(baseUrl + path, {
    method, headers, body: body === undefined ? undefined : multipart ? body : JSON.stringify(body),
    signal: AbortSignal.timeout(30_000), redirect: 'error',
  });
  const text = await response.text();
  const data = text && response.headers.get('content-type')?.includes('json') ? JSON.parse(text) : text || null;
  if (!response.ok) {
    const error = new Error(`HTTP ${response.status}`);
    Object.assign(error, { status: response.status, data, headers: response.headers });
    throw error;
  }
  return { status: response.status, data };
}

submitTransaction

Submit a token operation. API Reference · Integration guide

POST /api/transactions

Parameter	Location	Required
`API-Version`	header	Yes
`Idempotency-Key`	header	Yes

Request body: mint

{
  "txType": "MINT",
  "assetId": "GBP",
  "accountRef": "ACC-0001",
  "amount": "10.50"
}

Request body: burn

{
  "txType": "BURN",
  "assetId": "GBP",
  "accountRef": "ACC-0001",
  "amount": "40.00"
}

Request body: transfer

{
  "txType": "TRANSFER",
  "assetId": "GBP",
  "accountRef": "ACC-0001",
  "counterpartyRef": "ACC-0002",
  "amount": "250.00"
}

Request body: twoPartyLock

{
  "txType": "LOCK",
  "assetId": "GBP",
  "accountRef": "ACC-0001",
  "counterpartyRef": "ACC-0002",
  "amount": "100.00",
  "params": {
    "expiry": "2027-01-01T00:00:00Z",
    "lockRef": "INV-88421"
  }
}

Request body: release

{
  "txType": "RELEASE",
  "params": {
    "lockId": "b28f1a4c-9d3e-4f27-8a56-1e0c7b9d42a1"
  }
}

Request body: cancel

{
  "txType": "CANCEL",
  "params": {
    "lockId": "b28f1a4c-9d3e-4f27-8a56-1e0c7b9d42a1"
  }
}

const body = {
  "txType": "MINT",
  "assetId": "GBP",
  "accountRef": "ACC-0001",
  "amount": "10.50"
};
const result = await request('POST', '/api/transactions', body, required('QFP_IDEMPOTENCY_KEY'));
console.log(result.status, result.data);

Replace angle-bracket placeholders before calling. Persist any idempotency key with the business instruction.

Potential responses

Documented statuses: 200, 202, 400, 401, 404, 500.

Example 200 (default); see the reference for other outcomes.

{
  "transactionId": "9c4d2f18-73ba-4e6c-8f05-2d17ab903e64",
  "txType": "LOCK",
  "assetId": "GBP",
  "accountRef": "ACC-0001",
  "customerRef": "CUST-0001",
  "counterpartyRef": "ACC-0002",
  "amount": "100.00",
  "params": {
    "expiry": "2027-01-01T00:00:00Z",
    "lockRef": "INV-88421",
    "lockId": "b28f1a4c-9d3e-4f27-8a56-1e0c7b9d42a1",
    "chainLockId": "0x00000000000000000000000000000000b28f1a4c9d3e4f278a561e0c7b9d42a1",
    "destination": "0x8B1cA3D5e07F2b94aC61d8E30f5A7b249C0e6D18"
  },
  "state": "BATCHED",
  "createdAt": "2026-08-06T09:29:10.285Z",
  "updatedAt": "2026-08-06T09:31:02.117Z"
}

For CSV/download endpoints, the response may be text rather than JSON. The request helper preserves that distinction.

listTransactions

List token operations. API Reference · Integration guide

GET /api/transactions

Parameter	Location	Required
`API-Version`	header	Yes
`state`	query	No
`accountRef`	query	No
`txType`	query	No
`page`	query	No
`size`	query	No
`cursor`	query	No
`limit`	query	No

const body = undefined;
const result = await request('GET', '/api/transactions', body, undefined);
console.log(result.status, result.data);

Replace angle-bracket placeholders before calling. Persist any idempotency key with the business instruction.

Potential responses

Documented statuses: 200, 400, 401, 500.

Example 200 (offsetPage); see the reference for other outcomes.

{
  "content": [
    {
      "transactionId": "9c4d2f18-73ba-4e6c-8f05-2d17ab903e64",
      "txType": "LOCK",
      "assetId": "GBP",
      "accountRef": "ACC-0001",
      "customerRef": "CUST-0001",
      "counterpartyRef": "ACC-0002",
      "amount": "100.00",
      "params": {
        "expiry": "2027-01-01T00:00:00Z",
        "lockId": "b28f1a4c-9d3e-4f27-8a56-1e0c7b9d42a1",
        "chainLockId": "0x00000000000000000000000000000000b28f1a4c9d3e4f278a561e0c7b9d42a1"
      },
      "state": "CONFIRMED",
      "txHash": "0x9f2c1d5e4b8a37c06d1e5f9a2b4c7d8e0f1a2b3c4d5e6f708192a3b4c5d6e7f8",
      "blockNumber": 18446744,
      "createdAt": "2026-08-06T09:31:02.117Z",
      "updatedAt": "2026-08-06T09:33:41.229Z"
    },
    {
      "transactionId": "3f7c1a90-5d2e-4b08-9a41-6c2b8e5d7f13",
      "txType": "MINT",
      "assetId": "GBP",
      "accountRef": "ACC-0001",
      "customerRef": "CUST-0001",
      "counterpartyRef": null,
      "amount": "10.50",
      "params": {},
      "state": "POLICY_PENDING",
      "createdAt": "2026-08-06T09:29:10.285Z",
      "updatedAt": "2026-08-06T09:29:10.285Z"
    }
  ],
  "page": 0,
  "size": 20,
  "totalElements": 2,
  "totalPages": 1
}

For CSV/download endpoints, the response may be text rather than JSON. The request helper preserves that distinction.

listOutstandingBreaks

List the operations that failed or stalled. API Reference · Integration guide

GET /api/transactions/breaks

Parameter	Location	Required
`API-Version`	header	Yes
`reason`	query	No
`accountRef`	query	No
`from`	query	No
`to`	query	No
`page`	query	No
`size`	query	No

const body = undefined;
const result = await request('GET', '/api/transactions/breaks', body, undefined);
console.log(result.status, result.data);

Replace angle-bracket placeholders before calling. Persist any idempotency key with the business instruction.

Potential responses

Documented statuses: 200, 400, 401, 500.

Example 200 (default); see the reference for other outcomes.

{
  "content": [
    {
      "transactionId": "9c4d2f18-73ba-4e6c-8f05-2d17ab903e64",
      "reasonCode": "RECON",
      "occurredAt": "2026-09-18T09:02:00.000Z",
      "txType": "MINT",
      "state": "SUBMITTED",
      "accountRef": "ACC-0001",
      "assetId": "GBP",
      "txHash": "0x9f2c1d5e4b8a37c06d1e5f9a2b4c7d8e0f1a2b3c4d5e6f708192a3b4c5d6e7f8",
      "breakId": "5e1b7c92-0a34-4d18-b6f7-2c9e4a8d3b51",
      "breakStatus": "OPEN",
      "detail": {
        "reason": "no chain transaction found within the search window",
        "nonce": 41
      }
    },
    {
      "transactionId": "3f7c1a90-5d2e-4b08-9a41-6c2b8e5d7f13",
      "reasonCode": "CHAIN_FAILED",
      "occurredAt": "2026-09-18T09:01:00.000Z",
      "txType": "BURN",
      "state": "FAILED",
      "accountRef": "ACC-0001",
      "assetId": "GBP",
      "txHash": "0x4b81e0c7a2d93f16580ea7c4b39d2f85a61c07be3d49128f0a5c6b2e4d17f903",
      "breakId": "c73a2f45-8e1d-4906-a2b8-7f0c5d31e9a4",
      "breakStatus": "INVESTIGATING",
      "detail": {
        "failure": "CONTRACT_REVERTED",
        "reasonDetail": "execution reverted: balance below amount",
        "attempts": 1
      }
    }
  ],
  "page": 0,
  "size": 20,
  "totalElements": 2,
  "totalPages": 1
}

For CSV/download endpoints, the response may be text rather than JSON. The request helper preserves that distinction.

getTransaction

Get one token operation. API Reference · Integration guide

GET /api/transactions/{transactionId}

Parameter	Location	Required
`API-Version`	header	Yes
`transactionId`	path	Yes

const body = undefined;
const result = await request('GET', '/api/transactions/' + encodeURIComponent('<transactionId>') + '', body, undefined);
console.log(result.status, result.data);

Replace angle-bracket placeholders before calling. Persist any idempotency key with the business instruction.

Potential responses

Documented statuses: 200, 400, 401, 404, 500.

Example 200 (confirmedLock); see the reference for other outcomes.

{
  "transactionId": "9c4d2f18-73ba-4e6c-8f05-2d17ab903e64",
  "txType": "LOCK",
  "assetId": "GBP",
  "accountRef": "ACC-0001",
  "customerRef": "CUST-0001",
  "counterpartyRef": "ACC-0002",
  "amount": "100.00",
  "params": {
    "expiry": "2027-01-01T00:00:00Z",
    "lockRef": "INV-88421",
    "lockId": "b28f1a4c-9d3e-4f27-8a56-1e0c7b9d42a1",
    "chainLockId": "0x00000000000000000000000000000000b28f1a4c9d3e4f278a561e0c7b9d42a1",
    "destination": "0x8B1cA3D5e07F2b94aC61d8E30f5A7b249C0e6D18"
  },
  "state": "CONFIRMED",
  "txHash": "0x9f2c1d5e4b8a37c06d1e5f9a2b4c7d8e0f1a2b3c4d5e6f708192a3b4c5d6e7f8",
  "blockNumber": 18446744,
  "createdAt": "2026-08-06T09:29:10.285Z",
  "updatedAt": "2026-08-06T09:31:47.902Z"
}

For CSV/download endpoints, the response may be text rather than JSON. The request helper preserves that distinction.