LifecycleReadService

List Flows By Tx

List lifecycle flows that reference a transaction hash.

Method

GET

Path

/v1/chain/flows/by-tx/{tx_hash}/matches

Visibility

Public endpoint

GET

/v1/chain/flows/by-tx/{tx_hash}/matches

Request

Testnet

curl --request GET \ \
  --url 'https://api.testnet.polyester.com/v1/chain/flows/by-tx/0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890/matches?limit=100&lookupKind=SOURCE&pageToken=eyJvZmZzZXQiOjEwMH0' \
  --header 'Accept: */*'

Responses

{
  "matches": [
    {
      "amountE18": {
        "hi": "1",
        "lo": "1"
      },
      "assetIds": {
        "unifiedAssetId": 100,
        "zippedAssetId": 100
      },
      "currentStep": "SOURCE",
      "destinationAddress": "0x3333333333333333333333333333333333333333",
      "destinationDomain": "EXTERNAL_CHAIN",
      "flowId": "flow_7YWHMfk9JZeLMgZauHuiSxhI",
      "flowKind": "DEPOSIT",
      "isOpen": false,
      "isTerminal": false,
      "lastActivityAtUnixMs": "1",
      "latestTxRef": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890",
      "lifecycleReason": "ZIPPER_VALIDATION_REJECTED",
      "ownerAccountId": "7563897446546",
      "polyesterChainId": 1,
      "smartAccountAddress": "0x2222222222222222222222222222222222222222",
      "sourceAddress": "0x4444444444444444444444444444444444444444",
      "sourceDomain": "EXTERNAL_CHAIN",
      "sourceTxHash": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890",
      "txOccurrenceIndex": "1",
      "zipperReason": {
        "code": "DEPOSIT_WAIT_EXPIRED",
        "message": "value",
        "reasonId": "value"
      }
    }
  ],
  "nextPageToken": "eyJvZmZzZXQiOjIwMH0",
  "txHash": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890"
}

tx_hash string required

Chain transaction identifier to search for. Accepts a 0x-prefixed 32-byte EVM hash or a printable chain-native transaction id such as a Solana signature, Bitcoin txid, Litecoin txid, Dogecoin txid, or XRP transaction hash.

limit integer ≤ 500

Maximum number of matches to return. Defaults to 100 when omitted; maximum is 500.

lookupKind enum must be defined value

Lookup mode that determines which transaction references are searched.

pageToken string max 512 chars

Opaque keyset cursor returned by a previous response. The cursor is exclusive and bound to the transaction hash and lookup mode.

txHash string

Transaction hash searched by the request.

Example 0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890

20 fields

flowId string

Public, URL-safe lifecycle identifier for display, URLs, and user search.

Example flow_7YWHMfk9JZeLMgZauHuiSxhI

flowKind enum

Product flow family.

KIND_DEPOSIT KIND_WITHDRAW KIND_TRANSFER

Example DEPOSIT

sourceTxHash string

First observed source transaction hash for the flow when known.

Example 0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890

latestTxRef string

Latest transaction reference associated with the current visible state.

Example 0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890

txOccurrenceIndex string (uint64)

Stable occurrence discriminator within a transaction. For source-chain deposits this is the batched leg index; for on-chain facts it is the log or equivalent per-tx occurrence index when available.

Example 1

sourceDomain enum

Product domain where the overall flow starts.

DOMAIN_EXTERNAL_CHAIN DOMAIN_ZIPPER DOMAIN_FUNDING DOMAIN_TRADING DOMAIN_LENDING

Example EXTERNAL_CHAIN

destinationDomain enum

Product domain where the overall flow ends or currently settles.

DOMAIN_EXTERNAL_CHAIN DOMAIN_ZIPPER DOMAIN_FUNDING DOMAIN_TRADING DOMAIN_LENDING

Example EXTERNAL_CHAIN

currentStep enum

Current user-facing progress step for this flow.

FLOW_STEP_SOURCE FLOW_STEP_TRANSFER FLOW_STEP_REQUEST FLOW_STEP_VALIDATION FLOW_STEP_EXECUTION FLOW_STEP_BRIDGE_FULFILLMENT FLOW_STEP_DROPPED FLOW_STEP_FAILED FLOW_STEP_REFUNDED FLOW_STEP_FULFILLING FLOW_STEP_SETTLEMENT

Example SOURCE

isOpen boolean

True when this flow is still progressing.

Example false

isTerminal boolean

True when this flow reached a final state.

Example false

2 fields

polyesterChainId integer (int32)

Polyester Chain id associated with this flow.

Example 1

2 fields

sourceAddress string

Source address to show for this flow.

Example 0x4444444444444444444444444444444444444444

destinationAddress string

Destination address to show for this flow.

Example 0x3333333333333333333333333333333333333333

lifecycleReason enum

Product-facing reason for failed, dropped, or otherwise notable flows.

ZIPPER_VALIDATION_REJECTED ZIPPER_EXECUTION_REJECTED ZIPPER_WITHDRAW_EXECUTION_FAILED ZIPPER_DEPOSIT_REFUND_FAILED LEDGER_MIRROR_REJECTED LEDGER_MIRROR_TRANSFER_EXCEEDS_CREDITS LEDGER_MIRROR_TRANSFER_EXISTS LEDGER_MIRROR_PENDING_TRANSFER_NOT_FOUND LEDGER_MIRROR_TRANSFER_ID_ALREADY_FAILED TRADING_WITHDRAW_POLICY_DENIED TRADING_WITHDRAW_CONTRACT_REVERTED TRADING_WITHDRAW_EXECUTION_FAILED

Example ZIPPER_VALIDATION_REJECTED

lastActivityAtUnixMs string (uint64)

Timestamp used for list ordering in milliseconds since epoch (UTC).

Example 1

ownerAccountId string (fixed64)

Public account or subaccount identifier that owns this flow.

Example 7563897446546

smartAccountAddress string

Smart account address on Polyester Chain when known.

Example 0x2222222222222222222222222222222222222222

3 fields

nextPageToken string

Opaque cursor for the next page. Empty when no more results exist.

Example eyJvZmZzZXQiOjIwMH0

Possible errors: 5

Key	Status	Error	When
unauthenticated	401	Unauthenticated	Authentication required.
permission-denied	403	Permission Denied	Permission denied.
invalid-argument	400	Invalid Argument	Invalid argument.
not-found	404	Not Found	Not found.
unavailable	503	Unavailable	Service unavailable.

GET

/v1/chain/flows/by-tx/{tx_hash}/matches

Request

Testnet

curl --request GET \ \
  --url 'https://api.testnet.polyester.com/v1/chain/flows/by-tx/0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890/matches?limit=100&lookupKind=SOURCE&pageToken=eyJvZmZzZXQiOjEwMH0' \
  --header 'Accept: */*'

Responses

{
  "matches": [
    {
      "amountE18": {
        "hi": "1",
        "lo": "1"
      },
      "assetIds": {
        "unifiedAssetId": 100,
        "zippedAssetId": 100
      },
      "currentStep": "SOURCE",
      "destinationAddress": "0x3333333333333333333333333333333333333333",
      "destinationDomain": "EXTERNAL_CHAIN",
      "flowId": "flow_7YWHMfk9JZeLMgZauHuiSxhI",
      "flowKind": "DEPOSIT",
      "isOpen": false,
      "isTerminal": false,
      "lastActivityAtUnixMs": "1",
      "latestTxRef": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890",
      "lifecycleReason": "ZIPPER_VALIDATION_REJECTED",
      "ownerAccountId": "7563897446546",
      "polyesterChainId": 1,
      "smartAccountAddress": "0x2222222222222222222222222222222222222222",
      "sourceAddress": "0x4444444444444444444444444444444444444444",
      "sourceDomain": "EXTERNAL_CHAIN",
      "sourceTxHash": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890",
      "txOccurrenceIndex": "1",
      "zipperReason": {
        "code": "DEPOSIT_WAIT_EXPIRED",
        "message": "value",
        "reasonId": "value"
      }
    }
  ],
  "nextPageToken": "eyJvZmZzZXQiOjIwMH0",
  "txHash": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890"
}

Polyester is best experienced on desktop.

Request

Responses