chain.lifecycle.v1.LifecycleReadService
ListFlows
ListFlows lists lifecycle flows with optional filters and keyset pagination.
Request
curl --request POST \ \
--url 'https://api.testnet.polyester.com/chain.lifecycle.v1.LifecycleReadService/ListFlows' \
--header 'Content-Type: application/json' \
--header 'Connect-Protocol-Version: 1' \
--data '{
"flowKind": "KIND_DEPOSIT",
"flowState": "STATE_PENDING_SOURCE",
"limit": 100,
"orderBy": "ORDER_BY_LAST_ACTIVITY",
"ownerAccountId": "7563897446546",
"pageToken": "eyJvZmZzZXQiOjEwMH0",
"polyesterChainIds": [
1
],
"scope": "LIST_ALL",
"sort": "SORT_NEWEST",
"txRef": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890",
"unifiedAssetIds": [
100
],
"zippedAssetIds": [
100
]
}'Responses
{
"flows": [
{
"amountE18": {
"hi": "1",
"lo": "1"
},
"assetIds": {
"unifiedAssetId": 100,
"zippedAssetId": 100
},
"currentProgress": {
"approveCount": 1,
"currentConfirmations": 1,
"currentStepExpectedDurationMs": "1",
"currentStepStartedAtUnixMs": "1",
"rejectCount": 1,
"requiredApprovals": 1,
"requiredConfirmations": 1,
"requiredRejections": 1,
"validatorCount": 1
},
"currentStep": "FLOW_STEP_SOURCE",
"currentStepSequence": 1,
"destinationAddress": "0x3333333333333333333333333333333333333333",
"destinationDomain": "DOMAIN_EXTERNAL_CHAIN",
"estimatedCompletionUnixMs": "1",
"flowId": "flow_7YWHMfk9JZeLMgZauHuiSxhJ",
"flowKind": "KIND_DEPOSIT",
"isDelayed": false,
"isOpen": false,
"isTerminal": false,
"lastActivityAtUnixMs": "1",
"latestLifecycleSource": "SOURCE_RELAYER",
"latestTxRef": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890",
"lifecycleReason": "ZIPPER_VALIDATION_REJECTED",
"ownerAccountId": "7563897446546",
"polyesterChainId": 1,
"progressTimeline": [
{
"expectedDurationMs": "1",
"sequence": 1,
"status": "TIMELINE_STATUS_COMPLETED",
"step": "FLOW_STEP_SOURCE"
}
],
"requestFee": {
"amountE18": {
"hi": "1",
"lo": "1"
},
"assetIds": {
"unifiedAssetId": 100,
"zippedAssetId": 100
},
"recipientAddress": "0x3333333333333333333333333333333333333333",
"status": "REQUEST_FEE_STATUS_LOCKED"
},
"smartAccountAddress": "0x2222222222222222222222222222222222222222",
"sourceAddress": "0x4444444444444444444444444444444444444444",
"sourceDomain": "DOMAIN_EXTERNAL_CHAIN",
"sourceTxHash": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890",
"startedAtUnixMs": "1",
"terminalAtUnixMs": "1",
"txOccurrenceIndex": "1",
"updatedAtUnixMs": "1",
"zipperReason": {
"code": "DEPOSIT_WAIT_EXPIRED",
"message": "value",
"reasonId": "value"
}
}
],
"nextPageToken": "eyJvZmZzZXQiOjIwMH0"
}chain.lifecycle.v1.ListFlowsRequestchain.lifecycle.v1.ListFlowsResponseMaximum number of flows to return. Defaults to 100 when omitted; maximum is 500.
Sort direction for the selected ordering timestamp.
Optional product flow kind filter. Unspecified includes all kinds.
Optional lifecycle state filter. Unspecified includes all states permitted by the selected scope.
Optional transaction reference filter. Matches source or latest activity transaction identifiers across supported chains.
Selects open, terminal, or all lifecycle flows.
Public account identifier for a main account or subaccount.
Smart account address on Polyester Chain.
Optional Polyester Chain ids to include. Maximum 100 unique ids.
Optional chain asset mapping ids to include. Maximum 100 unique ids.
Optional unified asset ids to include. Maximum 100 unique ids.
Opaque keyset cursor returned by a previous response. The cursor is exclusive and bound to the caller, filters, account selector, sort direction, and ordering timestamp.
Timestamp used for ordering and pagination. Defaults to last activity.
Public account identifier for the root account or subaccount the flow belongs to.
Smart-account address for the account the flow belongs to. This is the stable address selector equivalent of `owner_account_id`; do not derive it from source or destination display addresses.
Public, URL-safe lifecycle identifier for display, URLs, and user search.
Product flow family.
Current user-facing progress step for this flow. This may be derived from the flow state before a matching factual observed step exists.
Zipped asset identifier for the chain-specific asset mapping row. This is the canonical id from `chain_zipped_assets`, which already represents the source-chain asset metadata plus its mapped zToken relationship when relevant.
Unified asset identifier for the uAsset used by funding or trading flows when relevant. This is the canonical Polyester asset identity used by FundingAccount, TradingGateway, Lending, and other downstream product domains.
Polyester Chain id associated with this flow when known.
Most significant 64 bits.
Least significant 64 bits.
Zipped asset identifier for the chain-specific asset mapping row. This is the canonical id from `chain_zipped_assets`, which already represents the source-chain asset metadata plus its mapped zToken relationship when relevant.
Unified asset identifier for the uAsset used by funding or trading flows when relevant. This is the canonical Polyester asset identity used by FundingAccount, TradingGateway, Lending, and other downstream product domains.
Most significant 64 bits.
Least significant 64 bits.
Fee recipient address when settled on chain.
Current state of the fee snapshot.
First observed source transaction hash for the flow when known.
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.
Source address to show for the overall flow. For internal transfers this is the source smart account address.
Destination address to show for the overall flow. For internal transfers this is the destination smart account address.
Latest transaction reference associated with the current visible state.
Product domain where the overall flow starts. Use with `destination_domain` for route labels such as Funding to Trading.
Product domain where the overall flow ends or currently settles. Do not derive route labels from per-step settlement activity.
Provenance of the latest meaningful lifecycle activity reflected in this summary. This is not necessarily the source of the entire flow.
Product-facing reason for failed, dropped, or otherwise notable flows.
Stable code assigned to the specific outcome.
Stable reason identifier suitable for localization lookup.
User-displayable English explanation of the outcome.
First observed business timestamp in milliseconds since epoch (UTC).
Last summary update timestamp in milliseconds since epoch (UTC).
Terminal timestamp in milliseconds since epoch (UTC), or zero while open.
Timestamp used for list ordering in milliseconds since epoch (UTC).
True when the flow is still progressing.
True when the flow reached a final state.
One-based sequence of `current_step` in `progress_timeline`.
Timestamp when the current visible step started, in milliseconds since epoch (UTC).
Expected duration for the current visible step in milliseconds.
Current source confirmation count when confirmations apply.
Required source confirmation count when confirmations apply.
Current approval count when validation applies.
Current rejection count when validation applies.
Validator set size when validation applies.
Approval count required for the current validation step.
Rejection count that would fail the current validation step.
One-based sequence within the expected timeline.
Visible lifecycle step.
Progress status for this timeline item.
Expected duration of this visible step in milliseconds, derived from recent observed timing data for the same flow type.
Estimated Unix completion timestamp in milliseconds. Zero while `is_delayed` is true, because no reliable estimate exists then.
True when an open flow has made no progress for well beyond the expected time of its current step. Show the flow as delayed instead of an ETA; it still completes normally once progress resumes. Always false for terminal flows.
Opaque cursor for the next page. Empty when no more results exist.
| 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. |