LifecycleReadService

List Flows

List lifecycle flows with optional account, chain, asset, and state filters.

Method

GET

Path

/v1/chain/flows

Visibility

Public endpoint

GET

/v1/chain/flows

Request

Testnet

curl --request GET \ \
  --url 'https://api.testnet.polyester.com/v1/chain/flows?flowKind=DEPOSIT&flowState=PENDING_SOURCE&limit=100&orderBy=LAST_ACTIVITY&ownerAccountId=7563897446546&pageToken=eyJvZmZzZXQiOjEwMH0&polyesterChainIds=1&scope=ALL&sort=NEWEST&txRef=0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890&unifiedAssetIds=100&zippedAssetIds=100' \
  --header 'Accept: */*'

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": "SOURCE",
      "currentStepSequence": 1,
      "destinationAddress": "0x3333333333333333333333333333333333333333",
      "destinationDomain": "EXTERNAL_CHAIN",
      "estimatedCompletionUnixMs": "1",
      "flowId": "flow_7YWHMfk9JZeLMgZauHuiSxhI",
      "flowKind": "DEPOSIT",
      "isOpen": false,
      "isTerminal": false,
      "lastActivityAtUnixMs": "1",
      "latestLifecycleSource": "RELAYER",
      "latestTxRef": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890",
      "lifecycleReason": "ZIPPER_VALIDATION_REJECTED",
      "ownerAccountId": "7563897446546",
      "polyesterChainId": 1,
      "progressTimeline": [
        {
          "expectedDurationMs": "1",
          "sequence": 1,
          "status": "COMPLETED",
          "step": "SOURCE"
        }
      ],
      "requestFee": {
        "amountE18": {
          "hi": "1",
          "lo": "1"
        },
        "assetIds": {
          "unifiedAssetId": 100,
          "zippedAssetId": 100
        },
        "recipientAddress": "0x3333333333333333333333333333333333333333",
        "status": "LOCKED"
      },
      "smartAccountAddress": "0x2222222222222222222222222222222222222222",
      "sourceAddress": "0x4444444444444444444444444444444444444444",
      "sourceDomain": "EXTERNAL_CHAIN",
      "sourceTxHash": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890",
      "startedAtUnixMs": "1",
      "terminalAtUnixMs": "1",
      "txOccurrenceIndex": "1",
      "updatedAtUnixMs": "1",
      "zipperReason": {
        "code": "DEPOSIT_WAIT_EXPIRED",
        "message": "value",
        "reasonId": "value"
      }
    }
  ],
  "nextPageToken": "eyJvZmZzZXQiOjIwMH0"
}

flowKind enum must be defined value

Optional product flow kind filter. Unspecified includes all kinds.

flowState enum must be defined value

Optional lifecycle state filter. Unspecified includes all states permitted by the selected scope.

limit integer ≤ 500

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

orderBy enum must be defined value

Timestamp used for ordering and pagination. Defaults to last activity.

ownerAccountId string (int64) > 0

Public account identifier for a main account or subaccount.

pageToken string max 512 chars

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.

polyesterChainIds array max 100 items, unique

Optional Polyester Chain ids to include. Maximum 100 unique ids.

scope enum must be defined value

Selects open, terminal, or all lifecycle flows.

smartAccountAddress string

Smart account address on Polyester Chain.

sort enum must be defined value

Sort direction for the selected ordering timestamp.

txRef string

Optional transaction reference filter. Matches source or latest activity transaction identifiers across supported chains.

unifiedAssetIds array max 100 items, unique

Optional unified asset ids to include. Maximum 100 unique ids.

zippedAssetIds array max 100 items, unique

Optional chain asset mapping ids to include. Maximum 100 unique ids.

29 fields

ownerAccountId string (fixed64)

Public account identifier for the root account or subaccount the flow belongs to.

Example 7563897446546

smartAccountAddress string

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.

Example 0x2222222222222222222222222222222222222222

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

currentStep enum

Current user-facing progress step for this flow. This may be derived from the flow state before a matching factual observed step exists.

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

2 fields

polyesterChainId integer (int32)

Polyester Chain id associated with this flow when known.

Example 1

2 fields

4 fields

sourceTxHash string

First observed source transaction hash for the flow when known.

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

sourceAddress string

Source address to show for the overall flow. For internal transfers this is the source smart account address.

Example 0x4444444444444444444444444444444444444444

destinationAddress string

Destination address to show for the overall flow. For internal transfers this is the destination smart account address.

Example 0x3333333333333333333333333333333333333333

latestTxRef string

Latest transaction reference associated with the current visible state.

Example 0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890

sourceDomain enum

Product domain where the overall flow starts. Use with `destination_domain` for route labels such as Funding to Trading.

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. Do not derive route labels from per-step settlement activity.

DOMAIN_EXTERNAL_CHAIN DOMAIN_ZIPPER DOMAIN_FUNDING DOMAIN_TRADING DOMAIN_LENDING

Example EXTERNAL_CHAIN

latestLifecycleSource enum

Provenance of the latest meaningful lifecycle activity reflected in this summary. This is not necessarily the source of the entire flow.

SOURCE_RELAYER SOURCE_POLYESTER_CHAIN SOURCE_EXECUTOR SOURCE_LEDGER

Example RELAYER

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

3 fields

startedAtUnixMs string (uint64)

First observed business timestamp in milliseconds since epoch (UTC).

Example 1

updatedAtUnixMs string (uint64)

Last summary update timestamp in milliseconds since epoch (UTC).

Example 1

terminalAtUnixMs string (uint64)

Terminal timestamp in milliseconds since epoch (UTC), or zero while open.

Example 1

lastActivityAtUnixMs string (uint64)

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

Example 1

isOpen boolean

True when the flow is still progressing.

Example false

isTerminal boolean

True when the flow reached a final state.

Example false

currentStepSequence integer (int32)

One-based sequence of `current_step` in `progress_timeline`.

Example 1

9 fields

4 fields

estimatedCompletionUnixMs string (uint64)

Estimated Unix completion timestamp in milliseconds.

Example 1

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

Request

Testnet

curl --request GET \ \
  --url 'https://api.testnet.polyester.com/v1/chain/flows?flowKind=DEPOSIT&flowState=PENDING_SOURCE&limit=100&orderBy=LAST_ACTIVITY&ownerAccountId=7563897446546&pageToken=eyJvZmZzZXQiOjEwMH0&polyesterChainIds=1&scope=ALL&sort=NEWEST&txRef=0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890&unifiedAssetIds=100&zippedAssetIds=100' \
  --header 'Accept: */*'

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": "SOURCE",
      "currentStepSequence": 1,
      "destinationAddress": "0x3333333333333333333333333333333333333333",
      "destinationDomain": "EXTERNAL_CHAIN",
      "estimatedCompletionUnixMs": "1",
      "flowId": "flow_7YWHMfk9JZeLMgZauHuiSxhI",
      "flowKind": "DEPOSIT",
      "isOpen": false,
      "isTerminal": false,
      "lastActivityAtUnixMs": "1",
      "latestLifecycleSource": "RELAYER",
      "latestTxRef": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890",
      "lifecycleReason": "ZIPPER_VALIDATION_REJECTED",
      "ownerAccountId": "7563897446546",
      "polyesterChainId": 1,
      "progressTimeline": [
        {
          "expectedDurationMs": "1",
          "sequence": 1,
          "status": "COMPLETED",
          "step": "SOURCE"
        }
      ],
      "requestFee": {
        "amountE18": {
          "hi": "1",
          "lo": "1"
        },
        "assetIds": {
          "unifiedAssetId": 100,
          "zippedAssetId": 100
        },
        "recipientAddress": "0x3333333333333333333333333333333333333333",
        "status": "LOCKED"
      },
      "smartAccountAddress": "0x2222222222222222222222222222222222222222",
      "sourceAddress": "0x4444444444444444444444444444444444444444",
      "sourceDomain": "EXTERNAL_CHAIN",
      "sourceTxHash": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890",
      "startedAtUnixMs": "1",
      "terminalAtUnixMs": "1",
      "txOccurrenceIndex": "1",
      "updatedAtUnixMs": "1",
      "zipperReason": {
        "code": "DEPOSIT_WAIT_EXPIRED",
        "message": "value",
        "reasonId": "value"
      }
    }
  ],
  "nextPageToken": "eyJvZmZzZXQiOjIwMH0"
}

Polyester is best experienced on desktop.

Request

Responses