AutoWithdrawService

List Auto-Withdraw Runs

List the account's auto-withdraw runs with their payouts, newest first.

Method

GET

Path

/v1/auto-withdraw/runs

Visibility

Authentication required

Authentication

Session token or API key

MFA Requirement

Not required

GET

/v1/auto-withdraw/runs

Request

Testnet

curl --request GET \ \
  --url 'https://api.testnet.polyester.com/v1/auto-withdraw/runs?limit=100&subaccountId=45LUmqjT' \
  --header 'Accept: */*' \
  --header 'X-API-KEY-ID: YOUR_API_KEY_ID' \
  --header 'X-API-TIMESTAMP: YOUR_API_TIMESTAMP' \
  --header 'X-API-SIGNATURE: YOUR_API_SIGNATURE'

Responses

{
  "nextPageToken": "eyJvZmZzZXQiOjIwMH0",
  "runs": [
    {
      "createdAt": "2025-01-01T00:00:00Z",
      "finishedAt": "2025-01-01T00:00:00Z",
      "reason": "value",
      "ruleVersion": 1,
      "runSeq": "1",
      "scheduledFor": "2025-01-01T00:00:00Z",
      "state": "PLANNED",
      "steps": [
        {
          "amount": "18.446744073709551617",
          "assetId": 100,
          "available": "18.446744073709551617",
          "destinationAddress": "0x3333333333333333333333333333333333333333",
          "destinationChainId": "1",
          "intentId": "9155001234567",
          "networkFee": "18.446744073709551617",
          "reason": "value",
          "state": "PENDING",
          "txHash": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890",
          "valueUsd": "18.446744073709551617"
        }
      ]
    }
  ]
}

limit integer ≤ 100

Maximum number of runs to return: 0 or omitted means 20, at most 100.

pageToken string max 256 chars

Cursor from a previous response's nextPageToken; omit for the first page.

subaccountId string /^[1-9A…m-z]+$/

Public subaccount ID; omit for the caller's root account. Public ID, as a base58 string.

nextPageToken string

Cursor for the next page. Empty when no more results exist.

Example eyJvZmZzZXQiOjIwMH0

8 fields

createdAt string (date-time)

When the run started.

Example 2025-01-01T00:00:00Z

finishedAt string (date-time)

When the run ended; unset while it is in progress.

Example 2025-01-01T00:00:00Z

reason string

Machine-readable reason for a skipped run: nothing_to_pay, price_unavailable (an asset was not paid because no current price valued it) or rule_superseded; empty otherwise.

Example value

ruleVersion integer (int32)

The rule version the run executes.

Example 1

runSeq string /^[0-9]+$/

The account's run number, increasing by one per run.

Example 1

scheduledFor string (date-time)

The scheduled slot the run belongs to.

Example 2025-01-01T00:00:00Z

state enum

Where the run stands.

PLANNED PAYING COMPLETED PARTIALLY_FAILED FAILED SKIPPED

Example PLANNED

11 fields

amount string /^[0-9]…9]+)?$/

What the step pays, as a decimal string in whole units of the asset; '0' when skipped.

Example 18.446744073709551617

assetId integer (int32)

Ledger asset paid.

Example 100

available string /^[0-9]…9]+)?$/

The account's available balance of the asset when the run started, as a decimal string in whole units of the asset.

Example 18.446744073709551617

destinationAddress string

Canonical destination address.

Example 0x3333333333333333333333333333333333333333

destinationChainId string /^[0-9]+$/

External destination chain identifier.

Example 1

intentId string

Withdraw intent identifier once the withdrawal is accepted; follows the same lifecycle as a user withdrawal.

Example 9155001234567

networkFee string /^[0-9]…9]+)?$/

The network fee charged on the withdrawal, as a decimal string in whole units of the asset. Once it completed, the destination received amount minus this fee; once Zipper rejected it or its execution failed, the fee Zipper kept, which is not refunded. Absent until the step is final, when it was skipped or failed before it reached Zipper, and when the fee was not reported.

Example 18.446744073709551617

reason string

Machine-readable reason for a skipped or failed step, such as below_minimum, price_unavailable (the rule has a USD minimum and no current price valued the asset; the funds stay for a later run), rule_superseded, destination_not_whitelisted, destination_cooling_down (a broker vault's destination added to its external withdraw whitelist less than 24 hours ago; the funds stay for a later run), authority_revoked, gateway_capacity_insufficient (the funds stay for a later run), withdrawal_released or withdrawal_failed; empty otherwise.

Example value

state enum

Where the payout stands.

PENDING SUBMITTING SUBMITTED COMPLETED FAILED SKIPPED

Example PENDING

txHash string

Destination-network transaction hash once the withdrawal completed.

Example 0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890

valueUsd string /^[0-9]…9]+)?$/

USD value of the payable amount when the run started, as a decimal string in whole USD; absent when the rule has no USD minimum or no current price was available.

Example 18.446744073709551617

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.

GET

/v1/auto-withdraw/runs

Request

Testnet

curl --request GET \ \
  --url 'https://api.testnet.polyester.com/v1/auto-withdraw/runs?limit=100&subaccountId=45LUmqjT' \
  --header 'Accept: */*' \
  --header 'X-API-KEY-ID: YOUR_API_KEY_ID' \
  --header 'X-API-TIMESTAMP: YOUR_API_TIMESTAMP' \
  --header 'X-API-SIGNATURE: YOUR_API_SIGNATURE'

Responses

{
  "nextPageToken": "eyJvZmZzZXQiOjIwMH0",
  "runs": [
    {
      "createdAt": "2025-01-01T00:00:00Z",
      "finishedAt": "2025-01-01T00:00:00Z",
      "reason": "value",
      "ruleVersion": 1,
      "runSeq": "1",
      "scheduledFor": "2025-01-01T00:00:00Z",
      "state": "PLANNED",
      "steps": [
        {
          "amount": "18.446744073709551617",
          "assetId": 100,
          "available": "18.446744073709551617",
          "destinationAddress": "0x3333333333333333333333333333333333333333",
          "destinationChainId": "1",
          "intentId": "9155001234567",
          "networkFee": "18.446744073709551617",
          "reason": "value",
          "state": "PENDING",
          "txHash": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890",
          "valueUsd": "18.446744073709551617"
        }
      ]
    }
  ]
}