Transactions API Reference

:::warning Submitted is not accepted A 200 from any write endpoint on this page means the transaction was handed to a node, while it does not mean the network accepted it. Confirm it with Get Transaction until blockHeight is set and output is SUCCESS, because a transaction that never shows up there was not accepted. See Always confirm for the full explanation. :::

Register Wallet

Registers a wallet on a blockchain so it can sign and submit transactions. Do this once per wallet per blockchain before submitting any transactions.

Request

POST /api/v1/transactions/register-wallet

Headers

X-AccessKey — Your entity access key
Content-Type: application/json

Body

walletAddress (required) — The wallet address to register
blockchain (required) — The blockchain ID to register on
passphrase (optional) — Only needed if the wallet was created with a passphrase

Response

Returns the transaction result from the node on success.

cURL
TypeScript

curl -X POST \
'https://your-tms-url/api/v1/transactions/register-wallet' \
-H 'X-AccessKey: your-entity-access-key' \
-H 'Content-Type: application/json' \
-d '{
"walletAddress": "54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585",
"blockchain": "08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2"
}'

const res = await fetch('https://your-tms-url/api/v1/transactions/register-wallet', {
method: 'POST',
headers: {
  'X-AccessKey': 'your-entity-access-key',
  'Content-Type': 'application/json',
},
body: JSON.stringify({
  walletAddress: '54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585',
  blockchain: '08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2',
}),
});

const data = await res.json();
console.log(data);

Create Transaction

Submits a transaction to a blockchain. The wallet must already be registered on the target blockchain before calling this. The TMS picks an available node from your access key's allowed nodes and forwards the transaction.

Request

POST /api/v1/transactions

Headers

X-AccessKey — Your entity access key
Content-Type: application/json

Body

blockchainId (required) — Target blockchain ID
to (required) — Recipient wallet address
walletAddress — Signing wallet address
from — Sender wallet address
payload — The data to store
payloadType — text or json
passphrase — Only if the wallet was created with one
metadata — Optional key-value pairs

Response

Returns the transaction object including transactionId on success.

Example response

{
"transactionId": "a1b2c3d4e5f6...",
"blockchainId": "08c28f29...",
"status": "pending",
"payload": "hello blockchain",
"payloadType": "text",
"from": "54677be3...",
"to": "54677be3..."
}

cURL
TypeScript

curl -X POST \
'https://your-tms-url/api/v1/transactions' \
-H 'X-AccessKey: your-entity-access-key' \
-H 'Content-Type: application/json' \
-d '{
"blockchainId": "08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2",
"from": "54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585",
"to": "54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585",
"walletAddress": "54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585",
"payload": "hello blockchain",
"payloadType": "text"
}'

const res = await fetch('https://your-tms-url/api/v1/transactions', {
method: 'POST',
headers: {
  'X-AccessKey': 'your-entity-access-key',
  'Content-Type': 'application/json',
},
body: JSON.stringify({
  blockchainId: '08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2',
  from: '54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585',
  to: '54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585',
  walletAddress: '54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585',
  payload: 'hello blockchain',
  payloadType: 'text',
}),
});

const tx = await res.json();
console.log('Transaction ID:', tx.transactionId);

Get Transaction

:::note How to read the result output is the outcome: SUCCESS is confirmed, an error value means it committed but failed, and an empty output means pending. status stays ACCEPTED either way. If this call does not return the transaction after a reasonable wait, it was not accepted, so do not treat it as pending. :::

Retrieves the payload and metadata of a specific transaction by its ID and blockchain. Useful for verifying a transaction landed correctly.

Request

GET /api/v1/transactions/{blockchainId}/{transactionId}

Headers

X-AccessKey — Your entity access key

Path parameters

blockchainId — The blockchain the transaction was submitted to
transactionId — The ID returned when the transaction was created

Response

Returns the full transaction object including payload, status, block height, and timestamps.

Example response

{
"transactionId": "a1b2c3d4e5f6...",
"blockchainId": "08c28f29...",
"payload": "hello blockchain",
"payloadType": "text",
"status": "confirmed",
"blockHeight": 2301,
"from": "54677be3...",
"to": "54677be3...",
"timestamp": {
  "exactTime": "2026-05-25T19:00:00Z"
}
}

cURL
TypeScript

curl -X GET \
'https://your-tms-url/api/v1/transactions/{blockchainId}/{transactionId}' \
-H 'X-AccessKey: your-entity-access-key' \
-H 'Accept: application/json'

const blockchainId = '08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2';
const transactionId = 'your-transaction-id';

const res = await fetch(
`https://your-tms-url/api/v1/transactions/${blockchainId}/${transactionId}`,
{
  headers: {
    'X-AccessKey': 'your-entity-access-key',
    'Accept': 'application/json',
  },
}
);

const tx = await res.json();
console.log('Status:', tx.status);
console.log('Block height:', tx.blockHeight);
console.log('Payload:', tx.payload);

Create JSON Transaction

Submits a transaction whose payload is a structured JSON object. The TMS serializes the object to the blockchain. Use this when you want to store machine-readable records rather than plain text.

Request

POST /api/v1/transactions/json

Headers

X-AccessKey — Your entity access key
Content-Type: application/json

Body

blockchainId (required) — Target blockchain ID
to (required) — Recipient wallet address
payload (required) — A JSON object to store on-chain, scalars and arrays are rejected
walletAddress (optional) — Signing wallet (defaults to from)
from (optional) — Sender wallet address
passphrase (optional) — Only if the wallet was created with one
metadata (optional) — Key-value string pairs

Payload constraints

The payload must be a JSON object, so a value such as 42,"text", true, null or [1, 2, 3] is rejected with a 400, because this endpoint stores structured records and the scalar and array forms are outside its scope. The error body reads{"error": "invalid request body"}, which refers to the payload even though it sounds like the whole request is malformed, so check the payload type first when you see it.

Numbers are handled as IEEE-754 doubles, so any integer larger than 2^53 − 1 (9007199254740991) is rounded when it is stored, yet the write still succeeds with a 200, which means you only notice by reading the transaction back. Send such values as strings, {"orderId": "1234567890123456789"}, and they round-trip exactly, whether that is a 19-digit id, a nanosecond timestamp or a token amount in base units.

The payload is also re-serialized on the way in, so 100.0 is stored as100 and characters such as <, > and& may be stored in their escaped form. The values stay equivalent as JSON, yet the stored bytes are not guaranteed to match what you sent.

Response

{
"transactionId": "a1b2c3d4e5f6...",
"blockchainId": "08c28f29...",
"status": "pending",
"payloadType": "json"
}

cURL
TypeScript

curl -X POST \
'https://your-tms-url/api/v1/transactions/json' \
-H 'X-AccessKey: your-entity-access-key' \
-H 'Content-Type: application/json' \
-d '{
"blockchainId": "08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2",
"to": "54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585",
"walletAddress": "54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585",
"payload": { "event": "invoice_paid", "amount": 1500, "currency": "USD" }
}'

const res = await fetch('https://your-tms-url/api/v1/transactions/json', {
method: 'POST',
headers: {
  'X-AccessKey': 'your-entity-access-key',
  'Content-Type': 'application/json',
},
body: JSON.stringify({
  blockchainId: '08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2',
  to: '54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585',
  walletAddress: '54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585',
  payload: { event: 'invoice_paid', amount: 1500, currency: 'USD' },
}),
});

const tx = await res.json();
console.log('Transaction ID:', tx.transactionId);

Create Text Transaction

Submits a transaction whose payload is a plain text string. Identical toPOST /api/v1/transactions but explicitly typed — use this when you want to be clear in your code that the payload is text.

Request

POST /api/v1/transactions/text

Headers

X-AccessKey — Your entity access key
Content-Type: application/json

Body

blockchainId (required) — Target blockchain ID
to (required) — Recipient wallet address
walletAddress (required) — Signing wallet address
from — Sender wallet address
payload — The text string to store
payloadType — Should be "text"
passphrase (optional) — Only if the wallet was created with one
metadata (optional) — Key-value string pairs

Response

{
"transactionId": "a1b2c3d4e5f6...",
"blockchainId": "08c28f29...",
"status": "pending",
"payload": "hello blockchain",
"payloadType": "text"
}

cURL
TypeScript

curl -X POST \
'https://your-tms-url/api/v1/transactions/text' \
-H 'X-AccessKey: your-entity-access-key' \
-H 'Content-Type: application/json' \
-d '{
"blockchainId": "08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2",
"from": "54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585",
"to": "54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585",
"walletAddress": "54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585",
"payload": "hello blockchain",
"payloadType": "text"
}'

const res = await fetch('https://your-tms-url/api/v1/transactions/text', {
method: 'POST',
headers: {
  'X-AccessKey': 'your-entity-access-key',
  'Content-Type': 'application/json',
},
body: JSON.stringify({
  blockchainId: '08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2',
  from: '54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585',
  to: '54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585',
  walletAddress: '54677be320b0bd704a99ee1f3d60c7309dfdee4810b1846d7b66ddbe0e84f585',
  payload: 'hello blockchain',
  payloadType: 'text',
}),
});

const tx = await res.json();
console.log('Transaction ID:', tx.transactionId);

Get Transaction History

Returns a paginated list of transactions submitted through the TMS by your entity. Supports filtering by status, flow type, blockchain, sender, and recipient.

Request

GET /api/v1/transactions/history

Headers

X-AccessKey — Your entity access key

Query parameters

status (optional) — Filter by status, e.g. pending, confirmed
flow_type (optional) — Filter by flow type
blockchain_id (optional) — Filter to a specific blockchain
from (optional) — Filter by sender wallet address
to (optional) — Filter by recipient wallet address
page (optional) — Page number (default: 0)
pageSize (optional) — Results per page (default: 20)

Response

{
"items": [
  {
    "id": 1,
    "transactionId": "a1b2c3...",
    "blockchainId": "08c28f29...",
    "status": "confirmed",
    "payloadType": "text",
    "from": "54677be3...",
    "to": "54677be3...",
    "createdAt": "2026-05-25T19:00:00Z"
  }
],
"total": 1,
"page": 0,
"pageSize": 20
}

cURL
TypeScript

curl -X GET \
'https://your-tms-url/api/v1/transactions/history?status=confirmed&pageSize=10' \
-H 'X-AccessKey: your-entity-access-key' \
-H 'Accept: application/json'

const params = new URLSearchParams({
status: 'confirmed',
blockchain_id: '08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2',
page: '0',
pageSize: '20',
});

const res = await fetch(
`https://your-tms-url/api/v1/transactions/history?${params}`,
{
  headers: {
    'X-AccessKey': 'your-entity-access-key',
    'Accept': 'application/json',
  },
}
);

const history = await res.json();
console.log('Total:', history.total);
history.items.forEach(tx => console.log(tx.transactionId, tx.status));

Get History Entry by ID

Retrieves a single transaction history record by its internal TMS ID (the id field returned in the history list). This is separate from the on-chain transactionId.

Request

GET /api/v1/transactions/history/{id}

Headers

X-AccessKey — Your entity access key

Path parameters

id — The internal TMS history record ID

Response

{
"id": 42,
"transactionId": "a1b2c3...",
"blockchainId": "08c28f29...",
"status": "confirmed",
"payloadType": "text",
"from": "54677be3...",
"to": "54677be3...",
"createdAt": "2026-05-25T19:00:00Z"
}

cURL
TypeScript

curl -X GET \
'https://your-tms-url/api/v1/transactions/history/42' \
-H 'X-AccessKey: your-entity-access-key' \
-H 'Accept: application/json'

const id = 42;

const res = await fetch(
`https://your-tms-url/api/v1/transactions/history/${id}`,
{
  headers: {
    'X-AccessKey': 'your-entity-access-key',
    'Accept': 'application/json',
  },
}
);

const entry = await res.json();
console.log('Transaction ID:', entry.transactionId);
console.log('Status:', entry.status);

Get Queued Transaction Status

Checks the status of a transaction currently in the submission queue for a given blockchain. Use this to poll for confirmation when the TMS returns a message ID instead of a finalized transaction ID.

Request

GET /api/v1/transactions/{blockchainId}/queue/{msgId}

Headers

X-AccessKey — Your entity access key

Path parameters

blockchainId — The blockchain the transaction was submitted to
msgId — The queue message ID returned during submission

Response

{
"msgId": "msg-abc123",
"status": "pending",
"transactionId": "a1b2c3...",
"blockchainId": "08c28f29..."
}

cURL
TypeScript

curl -X GET \
'https://your-tms-url/api/v1/transactions/08c28f29.../queue/msg-abc123' \
-H 'X-AccessKey: your-entity-access-key' \
-H 'Accept: application/json'

const blockchainId = '08c28f29a62819120958984b761ddf8ccb45951612731409873994958fd150a2';
const msgId = 'msg-abc123';

const res = await fetch(
`https://your-tms-url/api/v1/transactions/${blockchainId}/queue/${msgId}`,
{
  headers: {
    'X-AccessKey': 'your-entity-access-key',
    'Accept': 'application/json',
  },
}
);

const queueEntry = await res.json();
console.log('Status:', queueEntry.status);
console.log('Transaction ID:', queueEntry.transactionId);

Register Wallet​

Request

Headers

Body

Response

Create Transaction​

Request

Headers

Body

Response

Example response

Get Transaction​

Request

Headers

Path parameters

Response

Example response

Create JSON Transaction​

Request

Headers

Body

Payload constraints

Response

Create Text Transaction​

Request

Headers

Body

Response

Get Transaction History​

Request

Headers

Query parameters

Response

Get History Entry by ID​

Request

Headers

Path parameters

Response

Get Queued Transaction Status​

Request

Headers

Path parameters

Response

Register Wallet

Create Transaction

Get Transaction

Create JSON Transaction

Create Text Transaction

Get Transaction History

Get History Entry by ID

Get Queued Transaction Status