chain.lifecycle.v1.LifecycleReadService

ListFlowsByTx

ListFlowsByTx lists lifecycle flows that reference a transaction hash.

Method

POST

Path

chain.lifecycle.v1.LifecycleReadService/ListFlowsByTx

Service

chain.lifecycle.v1.LifecycleReadService

Visibility

Public endpoint

POST

chain.lifecycle.v1.LifecycleReadService/ListFlowsByTx

Request

Testnet

curl --request POST \ \
  --url 'https://api.testnet.polyester.com/chain.lifecycle.v1.LifecycleReadService/ListFlowsByTx' \
  --header 'Content-Type: application/json' \
  --header 'Connect-Protocol-Version: 1' \
  --data '{
  "limit": 100,
  "lookupKind": "TX_SOURCE",
  "pageToken": "eyJvZmZzZXQiOjEwMH0",
  "txHash": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890"
}'

Responses

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

Request

chain.lifecycle.v1.ListFlowsByTxRequest

Response

chain.lifecycle.v1.ListFlowsByTxResponse

txHash string

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.

lookupKind enum must be defined value

Lookup mode that determines which transaction references are searched.

limit integer (int32) ≤ 500

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

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.

20 fields

flowId string

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

flowKind enum

Product flow family.

KIND_DEPOSIT KIND_WITHDRAW KIND_TRANSFER

sourceTxHash string

First observed source transaction hash for the flow when known.

latestTxRef string

Latest transaction reference associated with the current visible state.

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.

sourceDomain enum

Product domain where the overall flow starts.

DOMAIN_EXTERNAL_CHAIN DOMAIN_ZIPPER DOMAIN_FUNDING DOMAIN_TRADING DOMAIN_LENDING

destinationDomain enum

Product domain where the overall flow ends or currently settles.

DOMAIN_EXTERNAL_CHAIN DOMAIN_ZIPPER DOMAIN_FUNDING DOMAIN_TRADING DOMAIN_LENDING

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

isOpen boolean

True when this flow is still progressing.

isTerminal boolean

True when this flow reached a final state.

2 fields

polyesterChainId integer (int32)

Polyester Chain id associated with this flow.

2 fields

sourceAddress string

Source address to show for this flow.

destinationAddress string

Destination address to show for this flow.

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 DEPOSIT_SOURCE_NOT_CONFIRMED

lastActivityAtUnixMs string (uint64)

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

ownerAccountId string (fixed64)

Public account or subaccount identifier that owns this flow.

smartAccountAddress string

Smart account address on Polyester Chain when known.

3 fields

nextPageToken string max 512 chars

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

Possible errors: 5

Key	HTTP status	Connect code	Error	When
unauthenticated	401	unauthenticated	Unauthenticated	Authentication required.
permission-denied	403	permission_denied	Permission Denied	Permission denied.
invalid-argument	400	invalid_argument	Invalid Argument	Invalid argument.
not-found	404	not_found	Not Found	Not found.
unavailable	503	unavailable	Unavailable	Service unavailable.

POST

chain.lifecycle.v1.LifecycleReadService/ListFlowsByTx

Request

Testnet

curl --request POST \ \
  --url 'https://api.testnet.polyester.com/chain.lifecycle.v1.LifecycleReadService/ListFlowsByTx' \
  --header 'Content-Type: application/json' \
  --header 'Connect-Protocol-Version: 1' \
  --data '{
  "limit": 100,
  "lookupKind": "TX_SOURCE",
  "pageToken": "eyJvZmZzZXQiOjEwMH0",
  "txHash": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890"
}'

Responses

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