List Token Transactions

Retrieves a paginated list of blockchain transactions associated with a specific token. This is the primary mechanism partners use to observe asynchronous state changes — most admin token endpoints (create, list, delist, passive, burn, public transfer, rent, update, open-to-otc, document add) return HTTP 200 immediately while a token_transaction row is enqueued for the wallet pipeline. Polling this endpoint (or Get Token Transaction By ID) is how you tell whether the on-chain operation has settled.

For the user-visible side-effects of confirmed transactions, see Token History By ID — once the wallet cron flips a transaction to Done, the corresponding token_histories row is written and the user overlay starts surfacing the new state.

Request

POST /v2/admin/tokens/{token_id}/transactions/search

Parameters

Name	Type	In	Description
token_id	string	path	Required. The ID of the token to search transactions for.
page	number	body	Optional. Page number for pagination (default: 1).
per_page	number	body	Optional. Number of items per page (default: 20).

Headers

Name	Description
Authorization	Required. Bearer token for authentication.
Content-Type	Required. Must be application/json.

Example

curl --request POST \
  --url '\{\{baseUrl\}\}/v2/admin/tokens/67d8774e903bfcbe7eb5d93e/transactions/search' \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  --header 'Content-Type: application/json' \
  --data '{
	"page": 1,
	"per_page": 20
}'

Response

{
	"data": [
		{
			"id": "67d8774f903bfcbe7eb5d941",
			"node_id": "67d6c447f47ff3adafda700d",
			"user_id": "665b372f3a72d7d0791596ba",
			"token_id": "67d8774e903bfcbe7eb5d93e",
			"external_id": "wallet-req-9a82",
			"type": 1,
			"status": 3,
			"environment": 0,
			"hash": "0x998a217061da05cf1bf1998470613a488b10908f0964e76a123c4063f91d77c4",
			"error": null,
			"message": null,
			"data": null,
			"is_api": true,
			"created_at": "2025-03-17T19:26:07.042Z",
			"updated_at": "2025-03-17T19:26:42.180Z"
		}
	],
	"total": 1,
	"page": 1,
	"per_page": 20
}

Response Fields

Field	Type	Description
id	string	Transaction ObjectID.
node_id	string	Node the transaction was issued under.
user_id	string	Supervisor (or system user) that triggered the transaction.
token_id	string	Target token.
external_id	string	Wallet API request ID — correlates with the wallet service's own logs.
type	integer	Transaction kind (see enum below).
status	integer	Lifecycle status (see enum below).
environment	integer	0 = default, 1 = otc, 2 = secondary_market.
hash	string | null	On-chain transaction hash. Populated once the wallet sends the transaction.
error	string | null	Error message — populated when status = Error.
message	string | null	Informational message attached by the consumer.
data	object | null	Type-specific structured payload (e.g. document_id for AddDocumentToToken).
is_api	boolean	true when the request originated from the integration API (vs. internal tooling).
created_at	string	ISO 8601 creation timestamp.
updated_at	string	ISO 8601 last-update timestamp (status flips bump this).

Status Codes

Status Code	Description
200	Success.
400	Bad Request - Invalid parameters.
401	Unauthorized - Invalid or missing authentication token.
404	Not Found - Token ID does not exist.
500	Internal Server Error.

type Enum

token_transactions covers all blockchain operations the integration enqueues against a token. Not every type is producible through the public integration API — deploy-related types are emitted by internal infrastructure code but the wallet pipeline writes them onto the same collection.

Type ID	Name	Producer	Description
1	CreateTokenization	Create Token	Deploying the token contract for a newly-created token.
2	TokenListing	List Token	Listing the token for primary-market sale.
3	TokenRent	Rent Token	Enabling rental income distribution.
4	UpdateTokenSupply	Internal supply re-sync flow	Adjusting the token's on-chain supply ceiling.
5	UpdateToken	Update Token, Update Token Metric	On-chain edit of total_value / supply / purchase bounds while status = listed.
6	DelistToken	Delist Token	Removing the token from the listing.
7	PassiveToken	Passive Token	Putting the token into a passive (read-only) state.
8	PublicTransferToken	Public Transfer	Enabling/disabling holder-to-holder transfers.
9	ChangeTokenLaunchpadAddress	Internal launchpad migration	Migrating the token to a new launchpad contract.
10	BurnToken	Burn Token, user burn	Burning supply from a holder.
11	OpenToSecondaryMarket	Open to Secondary Market	Tracked in secondary_market_transactions, not token_transactions. Listed here for completeness — the same Type constant is shared.
12	OpenToOtc	Open to OTC	Opening the token for OTC trading.
13	AcceptOtcOffer	Admin OTC accept-deal	Accepting an OTC counter-offer (tracked separately in OTC transactions for some flows).
14	CancelOtcOffer	Admin / user OTC cancel-deal	Cancelling an OTC deal.
15	UpdateRulesOnSecondaryMarket	Secondary-market rule update	Pushing updated OTC / secondary-market rules to the contract.
16	AddDocumentToToken	Update Token (document add on listed tokens)	Anchoring a document hash on-chain. data.document_id carries the document reference.
17	DeployTokenImpl	Wallet infra	Deploying the token implementation contract.
18	DeployMCImpl	Wallet infra	Deploying the master copy implementation.
19	DeployTREXAuthority	Wallet infra	Deploying the TREX claim authority.
20	TREXAddAndUseVersion	Wallet infra	Bumping the active TREX version on the network.
21	DeployMCProxy	Wallet infra	Deploying the master copy proxy.
22	DeployTokenProxy	Wallet infra	Deploying the token proxy.

Earlier docs were incomplete

Previous revisions of this page listed only types 1-11. Types 12-22 were already in production (the wallet service writes them to the same collection) but were silently ignored by partner parsers. Any switch / mapping table in your client should be a default fall-through to "unknown async event" rather than throwing on unrecognised values.

status Enum

Status ID	Name	Meaning
1	Started	Transaction request has been queued. The wallet pipeline has not yet picked it up.
2	InProgress	Transaction is being prepared / signed by the wallet pipeline.
3	Done	Transaction confirmed on-chain. The corresponding token_histories snapshot (where applicable) has been written and user reads will surface the new state.
4	Error	Transaction failed. The error field carries a human-readable cause.
5	PendingReceipt	Transaction has been broadcast on-chain (hash populated) but the receipt-confirmation cron is still waiting for inclusion. Treat as "not yet final"; the cron flips this to Done or Error.

Started, InProgress, and PendingReceipt all count as not yet completed (status.IsNotCompleted() on the server side). Only Done is success; only Error is terminal failure.

Polling Pattern

1. Trigger a state-transition endpoint (e.g. POST /v2/admin/tokens/{id}/listing). Capture the calling time — there is no transaction ID returned synchronously.
2. Call POST /v2/admin/tokens/{id}/transactions/search?page=1&per_page=10 and look for the most recent record of the expected type whose created_at post-dates step 1.
3. Once you know the transaction ID, switch to Get Token Transaction By ID for cheaper single-record polling.
4. Poll every 5-15 seconds until status reaches Done (success) or Error (with error populated).
5. After Done, user-facing reads of the token will overlay from the new token_histories row.