A deposit brings a supported Asset from an external Network into a Polyester account. You create a deposit address for the receiving account and Network, send the Asset to it from any wallet or exchange, and follow the resulting deposit flow until the balance is settled.
Each address belongs to one account (the Main Account or one Subaccount) and one Network. It does not rotate, so creating it again returns the same address.
Deposit addresses
Two methods manage addresses, and both accept a session or an API key:
CreateDepositAddress(POST /v1/chain/deposit-addresses) creates the address, or returns the existing one.ListDepositAddresses(GET /v1/chain/deposit-addresses) lists the account's addresses.
Both take an optional subaccountId. Omit it to target the Main Account, or the bound Subaccount
for a Subaccount-scoped API key. chainId is the
Polyester-registered Network id from the deposit and withdraw configuration, not the Network's
native chain id. ListDepositAddresses without chainId returns the account's addresses on every
Network that currently accepts deposits, ordered by chainId.
{
"chainId": 1
}Add subaccountId to target a Subaccount. The response wraps the address and its chainId in depositAddress.
Who may create and list
Deposit addresses are outside policy scope: no policy action controls them, and an attached Subaccount or API key policy never blocks them. Access depends on the caller:
| Caller | Create | List |
|---|---|---|
| Session on a Subaccount | OWNER, ADMIN, TREASURY, TRADER, or LEVERAGED_TRADER | Any role, including VIEWER |
| Main Account API key | The Main Account and every Subaccount it owns | Same |
| Subaccount-scoped API key | Its bound Subaccount only | Same |
Creating an address requires the acting Main Account to have accepted the current terms, including when it uses an API key or a shared Subaccount. Listing and using existing addresses do not. No MFA step-up is required.
Network availability
Addresses are offered only for Networks that currently accept deposits. When deposits on a Network
are suspended, creating an address for it, or listing with that chainId, fails with ConnectRPC FailedPrecondition (REST 400, code failed_precondition). A chainId Polyester does not
support for deposits fails with InvalidArgument. See Funds transfer overview.
Before you send
Read GetDepositWithdrawConfig (GET /v1/chain/deposit-withdraw/config).
It is public and lists
every supported Network and Asset route:
requiredConfirmationsandconfirmationTimeSecondsper Network, when knowndepositMinAmountper Asset route, in Asset unitsnetworkFee,sourceDecimals, and the source token contract per route
Deposit lifecycle
Sending the Asset starts a deposit flow (KIND_DEPOSIT). Polyester detects the source transfer, so
no API call is needed after you send. A deposit moves through these steps:
FLOW_STEP_SOURCE
Polyester observes the source transaction and counts confirmations. Progress reports currentConfirmations and requiredConfirmations. The live requirement can differ from the
configured default, so follow the flow rather than a fixed count.
FLOW_STEP_REQUEST
Zipper verifies the source transaction against the route and opens a deposit request.
FLOW_STEP_VALIDATION
Independent Zipper validators approve or reject the request. Progress reports approval and rejection counts against the required quorum.
FLOW_STEP_TRANSFER
The route's Zipped Asset is minted on Polyester Chain and credited to the account.
FLOW_STEP_SETTLEMENT
The ledger settlement is confirmed and the balance is usable.
The credit lands in Funding or in Trading according to the receiving account's Default Deposit
Destination, an on-chain account setting. The flow's destinationDomain and its ACTIVITY_FUNDING or ACTIVITY_TRADING activity show where it landed. If routing to Trading fails, the credit stays
in Funding. See Deposit Funds.
Statuses
FlowState | Meaning |
|---|---|
STATE_PENDING_SOURCE | Waiting on the source Network. |
STATE_PENDING_POLYESTER_CHAIN | Progressing on Polyester Chain. |
STATE_PENDING_LEDGER | Waiting for ledger settlement. |
STATE_COMPLETED | Credited and settled. |
STATE_FAILED | Failed; no longer progressing. |
STATE_DROPPED | Dropped before completion. |
STATE_REFUNDED | Ended in a refund or reversal. |
isTerminal: true means processing ended, not that it succeeded. Confirm success from STATE_COMPLETED and the settlement step, and read lifecycleReason for any other outcome. For
example, DEPOSIT_SOURCE_NOT_CONFIRMED means the source transaction did not confirm in time; the
deposit resumes and completes if it confirms later.
An open flow carries estimatedCompletionUnixMs. When isDelayed is true there is no reliable
estimate; the flow still completes once progress resumes.
Track deposits
| Need | Method |
|---|---|
| Deposits for an account | ListFlows with flowKind deposit and an account selector |
| Flows for a source transaction | ListFlowsByTx with the source transaction hash |
| One flow in detail | GetFlowById |
| Credited ledger legs | ListTransfers, rows with transferCode DEPOSIT and a flowId |
The REST routes are GET /v1/chain/flows, GET /v1/chain/flows/by-tx/{txHash}/matches, GET /v1/chain/flows/{flowId}, and GET /v1/transfers.
One source transaction can create several flows, one per deposit leg. Every transfer to the same address is its own flow, so follow each one to completion. Credited ledger legs also arrive on the Ledger transfers stream, and flow changes on the account lifecycle flow summaries stream, over WebSocket JSON or WebSocket Protobuf. See Track funding flows for reading progress and outcomes.
Field schemas are in the API reference.
