Track funding flows

Use lifecycle reads to determine where a deposit or withdrawal is, what has happened, and whether processing succeeded. An accepted withdrawal request or a confirmed source transaction starts the journey; neither proves the destination received the funds.

On Testnet, call these reads on https://api.testnet.polyester.com; Mainnet is coming soon. For submission, follow Deposits, Withdraw from Trading, or the funds transfer overview.

Find the flow

Choose the operation by the identifier you have. The references contain request schemas and filters.

• Account history: ListFlows, REST GET /v1/chain/flows. Select the account by its account ID or smart-account address, then narrow by kind, Network, or Asset.
• On-chain transaction: ListFlowsByTx, REST GET /v1/chain/flows/by-tx/{tx_hash}/matches. Use TX_SOURCE for the original source transaction or TX_ANY for the source or latest activity reference.
• Known flow: GetFlowById, REST GET /v1/chain/flows/{flow_id}. Save the public flowId from a list or transaction match and use it for subsequent detail reads.

A transaction can match zero, one, or several flows. For a deposit with several legs, inspect every match and distinguish occurrences using txOccurrenceIndex, the Asset, account, and route. An empty result does not prove the transfer failed or never happened.

Follow nextPageToken until empty. Keep the filters and ordering unchanged while following a page cursor. For later polling, start a fresh list: the default last-activity ordering changes as flows progress.

Match a withdrawal request

Persist the withdrawal's idempotency key, signed payload, account, destination, and returned intentId. The withdrawal response acknowledges acceptance, rather than delivery.

GetFlowById requires a public flowId; do not pass intentId or construct a flow ID from it. Use ListFlows for the source account, including open and terminal flows. Compare the route, Asset, gross amount, destination, and submission time. Once a transaction reference is available, use ListFlowsByTx to narrow the candidates.

These comparisons are candidate matching, not a unique request identifier. If several withdrawals look identical, keep them unresolved and contact Polyester support with their saved intent IDs. Do not submit a replacement withdrawal to obtain a clearer match.

Identify the route and Asset

Flow kinds describe the family:

• KIND_DEPOSIT: deposits into Polyester.
• KIND_WITHDRAW: withdrawals out of Polyester-controlled balances or accounts.
• KIND_TRANSFER: transfers between Polyester accounts.

Use the flow's source and destination domains for route labels, such as Funding to Trading or Trading to an external Network. Do not infer the whole route from one intermediate milestone.

The flow's assetIds identifies the Asset and its chain-specific mapping. Its sourceAddress and destinationAddress describe the movement; they are not token contract addresses. Resolve token contracts through GetDepositWithdrawConfig (GET /v1/chain/deposit-withdraw/config).

Lifecycle responses use the protobuf-style views, including amountE18: gross principal in 18-decimal units, separate from the request fee. Delivery activities can show net amounts. Use scaled integers when decoding these values.

Read progress and the outcome

ListFlows supports these state filters:

• STATE_PENDING_SOURCE: waiting for source-Network progress.
• STATE_PENDING_POLYESTER_CHAIN: progressing on Polyester Chain.
• STATE_PENDING_LEDGER: waiting for balance posting or settlement.
• STATE_COMPLETED: completed successfully.
• STATE_FAILED: failed and no longer progressing.
• STATE_DROPPED: stopped before successful completion.
• STATE_REFUNDED: ended in a refund or reversal.

These are flowState filter values. Returned summaries expose currentStep, isOpen, and isTerminal, rather than a flowState field. To select successful completions explicitly, list with STATE_COMPLETED and LIST_TERMINAL_ONLY, then match the saved flowId across the pages. Use LIST_ALL for reconciliation so that completed or failed flows are not excluded.

Terminal is not a promise that later evidence can never arrive. A deposit marked DEPOSIT_SOURCE_NOT_CONFIRMED can resume and complete if its source transaction confirms later. Retain its transaction and flow IDs for reconciliation.

Milestones versus estimates

A detail read separates factual observedSteps from the summary's projected progressTimeline. The current step can be ahead of the last observed milestone. A planned or projected step is not proof of execution.

The steps that apply depend on the route:

• Source: FLOW_STEP_SOURCE tracks the external transaction and confirmations.
• Request and validation: FLOW_STEP_REQUEST and FLOW_STEP_VALIDATION cover request creation and approval. Approval and rejection counts describe validation progress.
• Transfer or execution: FLOW_STEP_TRANSFER covers deposit crediting; FLOW_STEP_EXECUTION covers execution on Polyester Chain.
• External delivery: FLOW_STEP_BRIDGE_FULFILLMENT covers delivery progress. FLOW_STEP_FULFILLING means a withdrawal destination transaction hash is committed, with final fulfillment confirmation still pending. A hash alone is not completed delivery.
• Settlement: FLOW_STEP_SETTLEMENT confirms durable balance settlement where the route involves a ledger balance. Deposit activities distinguish credit to Funding from credit to Trading.
• Unsuccessful endings: FLOW_STEP_FAILED, FLOW_STEP_DROPPED, and FLOW_STEP_REFUNDED identify failure, dropping, or refund/reversal outcomes.

For an explorer link, use the milestone's transaction chain ID and that Network's configured explorer. A reference with no transaction chain ID can be a settlement identifier, not an on-chain transaction hash.

Confirmations and timing

Follow the flow's current and required confirmation counts when they apply. Network configuration provides a default confirmation requirement and estimated average confirmation time when known; neither is a guarantee for this transfer.

Use the returned expected step durations and estimated completion time for progress displays. When isDelayed is true, there is no reliable ETA and the estimated completion timestamp is zero. Show the delay and continue reconciliation rather than displaying that timestamp as a date.

Polling and streams

Polling GetFlowById is the direct way to follow a known flow. Refresh account lists to discover new flows, using bounded backoff and jitter. Honor any retry delay; see rate limits.

Streams reduce polling. On the realtime connection, account lifecycle flow summaries report changes to the flows of one Main Account or Subaccount, and lifecycle flow detail follows one flowId with its observed steps. Balance and ledger transfer streams report the resulting balance changes. Follow the WebSocket session model for authentication, recovery, and deduplication. The private order WebSocket carries orders, not funding lifecycles. Use lifecycle reads after reconnects or gaps and to confirm an outcome before updating your records.

When progress stops or fails

Related Topics