QuickSwapBrokerService

Get broker QuickSwap

Read the full detail of a QuickSwap belonging to this broker.

Method

GET

Path

/v1/quickswap/brokers/{broker}/quickswaps/{swap_id}

Visibility

Authentication required

Authentication

Session token

MFA Requirement

Not required

GET

/v1/quickswap/brokers/{broker}/quickswaps/{swap_id}

Request

Testnet

curl --request GET \ \
  --url 'https://api.testnet.polyester.com/v1/quickswap/brokers/value/quickswaps/1' \
  --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

{
  "quickSwap": {
    "chargedFees": [
      {
        "accountId": "3KXZCRpAVzd",
        "amount": {
          "baseUnits": "value",
          "decimals": 36
        },
        "assetId": 100,
        "kind": "SERVICE"
      }
    ],
    "createdAt": "2025-01-01T00:00:00Z",
    "depositInstructions": {
      "address": "0x3333333333333333333333333333333333333333",
      "addressRetiresAt": "2025-01-01T00:00:00Z",
      "addressState": "ACTIVE",
      "fundingExpiresAt": "2025-01-01T00:00:00Z",
      "issuedAt": "2025-01-01T00:00:00Z",
      "memo": "value",
      "minNativeGasLimit": "1",
      "zippedAssetId": 100
    },
    "deposits": [
      {
        "amount": {
          "baseUnits": "value",
          "decimals": 36
        },
        "confirmations": 1,
        "creditedAt": "2025-01-01T00:00:00Z",
        "detectedAt": "2025-01-01T00:00:00Z",
        "disposition": "EVALUATING",
        "flowId": "flow_7YWHMfk9JZeLMgZauHuiSxhJ",
        "index": 1,
        "reason": "SOURCE_SCREENING_FAILED",
        "requiredConfirmations": 1,
        "txHash": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890",
        "txOccurrenceIndex": "1",
        "zippedAssetId": 100
      }
    ],
    "depositsTruncated": false,
    "destinationAddress": "0x3333333333333333333333333333333333333333",
    "destinationMemo": "value",
    "execution": {
      "completedSlices": 1,
      "deadline": "2025-01-01T00:00:00Z",
      "executedInput": {
        "baseUnits": "value",
        "decimals": 36
      },
      "finishedAt": "2025-01-01T00:00:00Z",
      "inputAmount": {
        "baseUnits": "value",
        "decimals": 36
      },
      "intermediateRemainder": {
        "baseUnits": "value",
        "decimals": 36
      },
      "outputAmount": {
        "baseUnits": "value",
        "decimals": 36
      },
      "startedAt": "2025-01-01T00:00:00Z",
      "totalSlices": 1
    },
    "feeScheduleVersion": "1",
    "fees": {
      "affiliates": [
        {
          "accountId": "3Gjjw3W5BAR",
          "bps": 1
        }
      ],
      "brokerBps": 1
    },
    "idempotencyKey": "idem_01J5EXAMPLE0000000000000",
    "isTerminal": false,
    "quote": {
      "depositAmount": {
        "baseUnits": "value",
        "decimals": 36
      },
      "expectedAmountOut": {
        "baseUnits": "value",
        "decimals": 36
      },
      "expiresAt": "2025-01-01T00:00:00Z",
      "fees": [
        {
          "accountId": "3BWMYZjBBMT",
          "amount": {
            "baseUnits": "value",
            "decimals": 36
          },
          "bps": 1,
          "kind": "SERVICE",
          "zippedAssetId": 100
        }
      ],
      "intermediateAssetId": 100,
      "maxDepositAmount": {
        "baseUnits": "value",
        "decimals": 36
      },
      "minAmountOut": {
        "baseUnits": "value",
        "decimals": 36
      },
      "minDepositAmount": {
        "baseUnits": "value",
        "decimals": 36
      },
      "minRate": "value",
      "quotedAt": "2025-01-01T00:00:00Z"
    },
    "reason": "SOURCE_SCREENING_FAILED",
    "refundAddress": "value",
    "refundMemo": "value",
    "refundZippedAssetId": 100,
    "returnAddress": "value",
    "returnMemo": "value",
    "screening": {
      "sourceWallet": "value"
    },
    "status": "ALLOCATING",
    "swapId": "1",
    "terminalAt": "2025-01-01T00:00:00Z",
    "terms": {
      "amount": {
        "baseUnits": "value",
        "decimals": 36
      },
      "basis": "SOURCE_AMOUNT",
      "destinationZippedAssetId": 100,
      "execution": {
        "market": {}
      },
      "protection": {
        "maxSlippageBps": 1
      },
      "sourceZippedAssetId": 100
    },
    "updatedAt": "2025-01-01T00:00:00Z",
    "version": "1",
    "withdrawals": [
      {
        "address": "0x3333333333333333333333333333333333333333",
        "amount": {
          "baseUnits": "value",
          "decimals": 36
        },
        "depositIndex": 1,
        "finalizedAt": "2025-01-01T00:00:00Z",
        "flowId": "flow_7YWHMfk9JZeLMgZauHuiSxhJ",
        "index": 1,
        "memo": "value",
        "networkFee": {
          "baseUnits": "value",
          "decimals": 36
        },
        "role": "DESTINATION",
        "state": "QUEUED",
        "submittedAt": "2025-01-01T00:00:00Z",
        "txHash": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890",
        "unsentAmount": {
          "baseUnits": "value",
          "decimals": 36
        },
        "zippedAssetId": 100
      }
    ],
    "withdrawalsTruncated": false
  }
}

broker string required /^[a-z0…0,62}$/

Broker name.

swap_id string required > 0

Public QuickSwap ID as a decimal string.

28 fields

swapId string (fixed64)

Public QuickSwap identifier.

Example 1

idempotencyKey string

The broker's idempotency key that created this QuickSwap.

Example idem_01J5EXAMPLE0000000000000

status enum

Current status.

ALLOCATING AWAITING_DEPOSIT WAITING_FOR_CAPACITY PREPARING_DEPOSIT CONFIRMING CREDITED EXECUTING PAYING_OUT REFUNDING RETURNING HELD COMPLETED REFUNDED RETURNED EXPIRED

Example ALLOCATING

reason enum

Why the status is notable (held, returning, delayed, terminal without destination output); REASON_UNSPECIFIED otherwise. When a payout completes but a refund or return was NOT_SENT, the status follows the paid withdrawals (for example COMPLETED) and the reason is REFUND_BELOW_MINIMUM. A FAILED withdrawal takes precedence: the status is HELD and the reason WITHDRAWAL_FAILED.

SOURCE_SCREENING_FAILED CAPACITY_UNAVAILABLE PROTECTION_NOT_MET EXECUTION_DEADLINE_REACHED LATE_DEPOSIT DEPOSIT_BELOW_MINIMUM DEPOSIT_ABOVE_MAXIMUM WRONG_ASSET FUNDING_WINDOW_ENDED WITHDRAWAL_FAILED OUTCOME_RECONCILING SOURCE_SCREENING_BLOCKED REFUND_BELOW_MINIMUM DEPOSIT_ADDRESS_CONFLICT DEPOSIT_ADDRESS_ALREADY_USED DEPOSIT_ADDRESS_RETIRED DEPOSIT_ADDRESS_NOT_ISSUED INTERMEDIATE_BELOW_MINIMUM

Example SOURCE_SCREENING_FAILED

isTerminal boolean

True when status is terminal; authoritative, including for status values added later. Polling can stop at a terminal status. A terminal status never changes. Shortly after it, address_retires_at can still move later, and withdrawal details can be corrected as documented on Withdrawal; another deposit reaching the address also shows as RETURN_ONLY, and another deposit observed on an already retired address shows as MANUAL_RECOVERY. Returns made directly for such deposits are not yet reported in withdrawals; RETURN_ONLY does not confirm a completed return. Read again if the end user reports such a deposit or needs the final retirement time.

Example false

6 fields

sourceZippedAssetId integer (int32)

Source asset and network: an AssetChainVariant.zipped_asset_id from GET /v1/chain/deposit-withdraw/config. The end user deposits this asset on this network.

Example 100

destinationZippedAssetId integer (int32)

Destination asset and network: an AssetChainVariant.zipped_asset_id from GET /v1/chain/deposit-withdraw/config. The end user receives this asset on this network.

Example 100

basis enum

Side of the swap that amount denominates.

SOURCE_AMOUNT DESTINATION_AMOUNT

Example SOURCE_AMOUNT

2 fields

destinationAddress string

Recipient of the swap output on the destination network. Addresses and memos are in their network's canonical form (for example lowercase EVM hex), which can differ in case or encoding from the create request; that form is the one paid.

Example 0x3333333333333333333333333333333333333333

destinationMemo string

Destination tag or memo for destination_address; empty when none.

Example value

returnAddress string

Recipient of returned source funds on the source network.

Example value

returnMemo string

Destination tag or memo for return_address; empty when none.

Example value

refundZippedAssetId integer (int32)

Refund route (asset and network) of the intermediate asset; zero when none was supplied.

Example 100

refundAddress string

Recipient of refunded intermediate asset; empty when none was supplied.

Example value

refundMemo string

Destination tag or memo for refund_address; empty when none.

Example value

10 fields

2 fields

minRate string

Guaranteed minimum execution rate: destination display units per source display unit, as a decimal string with at most 18 fractional digits, rounded up when quoted. Guarantee: for the source amount converted all the way to the destination asset, the destination output before the withdrawal network fee is at least that amount × min_rate, rounded down to destination token units. On a two-leg route, the source amount converted is the first leg's input in proportion to the intermediate funds the second leg converted. Source that is not traded is returned to return_address, and intermediate funds that the second leg does not convert are refunded in the intermediate asset to refund_address; those parts are outside the destination guarantee. The amount delivered is the output less the actual withdrawal network fee, which can differ from the quote.

Example value

2 fields

intermediateAssetId integer (int32)

Unified asset ID of the intermediate asset of a two-leg route (for example USDT for BTC to SOL): the AssetConfig.ledger_id from GET /v1/chain/deposit-withdraw/config. Zero for a direct route or a bridge. When non-zero, CreateQuickSwap requires a refund address for that asset. The route is fixed at creation.

Example 100

5 fields

quotedAt string (date-time)

When the quote was priced.

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

expiresAt string (date-time)

End of the short quote validity, typically seconds to minutes after quoted_at. Display the quote until expires_at. CreateQuickSwap prices the terms again and never fails because a quote expired. After it the price fields are stale; the protection of a created QuickSwap still applies. Independent of the funding window and the execution deadline.

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

8 fields

address string

Deposit address in the source network's native text form, without memo.

Example 0x3333333333333333333333333333333333333333

memo string

Destination tag or memo the deposit must carry; empty when the source network uses none. A deposit without it cannot be attributed.

Example value

zippedAssetId integer (int32)

Asset and network to deposit; equal to terms.source_zipped_asset_id.

Example 100

issuedAt string (date-time)

When the address was issued to this QuickSwap; the funding window starts here. After ADDRESS_UNAVAILABLE it can be long after created_at.

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

fundingExpiresAt string (date-time)

End of the funding window, fixed when the address is issued (currently 7 days after issued_at). A deposit can execute only if Polyester detects it before this time; detection time counts, not block time, and confirmations may finish later. A deposit detected at or after this time never executes. A deposit observed on a retired address is MANUAL_RECOVERY and is not returned automatically; other late deposits are RETURN_ONLY. For an unfunded address, address_retires_at equals this time, so there is no separate scheduled return period. Send deposits well before this time. Never changes.

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

addressRetiresAt string (date-time)

After this time the deposit address is retired and funds sent to it may not be recoverable. For an unfunded address it equals funding_expires_at. After a deposit is accepted it is provisional, a lower bound, until Polyester releases the deposit address, which can be shortly after the QuickSwap becomes terminal; from then on it is at least 7 days after all payouts finish. It only moves later, never earlier, and never before funding_expires_at.

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

addressState enum

Current lifecycle state of the address.

ACTIVE REFUND_MODE RETIRED

Example ACTIVE

minNativeGasLimit string (uint64)

Recommended gas limit, in gas units, for native-coin deposits on EVM networks: 250000. Polyester does not enforce this limit. On some networks, depositing to an address that has never received funds requires far more than 21000 gas. If the limit is too low, the transaction fails on chain without depositing funds, and the network fee is still charged. Use at least the recommended limit. Unused gas is not charged. Zero for token deposits and non-EVM networks.

Example 1

1 field

12 fields

index integer (int32)

Zero-based position in detection order; stable for the QuickSwap's life.

Example 1

txHash string

Source-network transaction identifier in the network's native text form.

Example 0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890

txOccurrenceIndex string (uint64)

Output or log index of the deposit within tx_hash; zero is valid.

Example 1

zippedAssetId integer (int32)

Asset and network actually received, as a zipped_asset_id. Zero until Polyester has identified the deposit's asset, shortly after detection, and when the asset is not a supported route.

Example 100

2 fields

disposition enum

What this deposit may do.

EVALUATING ELIGIBLE RETURN_ONLY ON_HOLD MANUAL_RECOVERY

Example EVALUATING

reason enum

Why the disposition is RETURN_ONLY, ON_HOLD or MANUAL_RECOVERY; REASON_UNSPECIFIED otherwise, and for a deposit ON_HOLD for review without a more specific reason.

Example SOURCE_SCREENING_FAILED

confirmations integer (int32)

Current source-network confirmations; zero until the source network reports any. Never decreases.

Example 1

requiredConfirmations integer (int32)

Source-network confirmations required before credit; zero until known.

Example 1

detectedAt string (date-time)

When the deposit was first seen. Eligibility compares this time with funding_expires_at.

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

creditedAt string (date-time)

When the deposit was credited; unset until credited. Credit does not decide eligibility: a credited deposit can still be EVALUATING, and one then found ineligible, such as a late deposit, stays credited and is returned (RETURN_ONLY).

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

flowId string

Public, URL-safe lifecycle flow identifier of this deposit, usable with GET /v1/chain/flows/{flow_id}; empty until the flow exists. Lifecycle flow amounts are 18-decimal unified units (amount_e18), not token base units.

Example flow_7YWHMfk9JZeLMgZauHuiSxhJ

depositsTruncated boolean

True when more than 50 deposits were detected; only the first 50 are listed.

Example false

9 fields

2 fields

completedSlices integer (int32)

Completed slices: a market execution's one slice completes when execution finishes; a TWAP slice completes once it has traded and is over, so a slot that traded nothing or was skipped never completes. Zero for a bridge.

Example 1

totalSlices integer (int32)

Planned slices: a market execution has one once it is planned; a TWAP has its slice count, duration_ms over slice_interval_ms rounded up. Zero until then, and for a bridge, which trades nothing.

Example 1

startedAt string (date-time)

When execution started.

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

deadline string (date-time)

Execution deadline: started_at plus the TWAP duration, or plus the market execution window. Funds not converted by then are refunded or returned. Independent of the quote validity and the funding window. Unset until the execution is planned, and for a bridge, which trades nothing.

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

finishedAt string (date-time)

When execution finished; unset while executing.

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

14 fields

index integer (int32)

Zero-based position in the withdrawals list. Not stable: a withdrawal's position can change between reads, so do not use it as an identifier.

Example 1

role enum

Why this withdrawal pays its recipient.

DESTINATION REFUND RETURN

Example DESTINATION

depositIndex integer (int32)

Deposit whose funds this withdrawal moves.

Example 1

zippedAssetId integer (int32)

Asset and network paid, as a zipped_asset_id.

Example 100

address string

Recipient address in the network's native text form.

Example 0x3333333333333333333333333333333333333333

memo string

Recipient destination tag or memo; empty when the network uses none.

Example value

2 fields

state enum

Withdrawal progress.

QUEUED SUBMITTED FINALIZED FAILED NOT_SENT

Example QUEUED

txHash string

Recipient-network transaction recorded for this withdrawal; empty until the transaction is committed on the recipient network. It can be corrected for up to 24 hours after the QuickSwap ends (terminal_at) and is not updated after that. For the authoritative, latest state of the transfer, read flow_id.

Example 0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890

submittedAt string (date-time)

When the withdrawal was submitted; unset until submitted.

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

finalizedAt string (date-time)

When the withdrawal became final; unset until FINALIZED.

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

flowId string

Public, URL-safe lifecycle flow identifier of this withdrawal, usable with GET /v1/chain/flows/{flow_id}; empty until the flow exists. The flow is the authoritative, latest state of the transfer, including a correction made after tx_hash, amount and network_fee stop being updated. Lifecycle flow amounts are 18-decimal unified units (amount_e18), not token base units.

Example flow_7YWHMfk9JZeLMgZauHuiSxhJ

2 fields

withdrawalsTruncated boolean

True when more than 50 withdrawals exist; only the first 50 are listed.

Example false

createdAt string (date-time)

When the QuickSwap was created.

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

updatedAt string (date-time)

When the QuickSwap last changed.

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

terminalAt string (date-time)

When status became terminal; unset while not terminal.

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

version string (uint64)

Monotonic state version: a snapshot with a lower version is older. Zero while ALLOCATING; 1 once the deposit address is issued (AWAITING_DEPOSIT) or allocation ends without one (EXPIRED with DEPOSIT_ADDRESS_CONFLICT); every later change increments it.

Example 1

feeScheduleVersion string (uint64)

Fee schedule version fixed at creation. Every execution or bridge payout of this QuickSwap is charged that version's service fees, whatever later versions change.

Example 1

2 fields

4 fields

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/quickswap/brokers/{broker}/quickswaps/{swap_id}

Request

Testnet

curl --request GET \ \
  --url 'https://api.testnet.polyester.com/v1/quickswap/brokers/value/quickswaps/1' \
  --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

{
  "quickSwap": {
    "chargedFees": [
      {
        "accountId": "3KXZCRpAVzd",
        "amount": {
          "baseUnits": "value",
          "decimals": 36
        },
        "assetId": 100,
        "kind": "SERVICE"
      }
    ],
    "createdAt": "2025-01-01T00:00:00Z",
    "depositInstructions": {
      "address": "0x3333333333333333333333333333333333333333",
      "addressRetiresAt": "2025-01-01T00:00:00Z",
      "addressState": "ACTIVE",
      "fundingExpiresAt": "2025-01-01T00:00:00Z",
      "issuedAt": "2025-01-01T00:00:00Z",
      "memo": "value",
      "minNativeGasLimit": "1",
      "zippedAssetId": 100
    },
    "deposits": [
      {
        "amount": {
          "baseUnits": "value",
          "decimals": 36
        },
        "confirmations": 1,
        "creditedAt": "2025-01-01T00:00:00Z",
        "detectedAt": "2025-01-01T00:00:00Z",
        "disposition": "EVALUATING",
        "flowId": "flow_7YWHMfk9JZeLMgZauHuiSxhJ",
        "index": 1,
        "reason": "SOURCE_SCREENING_FAILED",
        "requiredConfirmations": 1,
        "txHash": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890",
        "txOccurrenceIndex": "1",
        "zippedAssetId": 100
      }
    ],
    "depositsTruncated": false,
    "destinationAddress": "0x3333333333333333333333333333333333333333",
    "destinationMemo": "value",
    "execution": {
      "completedSlices": 1,
      "deadline": "2025-01-01T00:00:00Z",
      "executedInput": {
        "baseUnits": "value",
        "decimals": 36
      },
      "finishedAt": "2025-01-01T00:00:00Z",
      "inputAmount": {
        "baseUnits": "value",
        "decimals": 36
      },
      "intermediateRemainder": {
        "baseUnits": "value",
        "decimals": 36
      },
      "outputAmount": {
        "baseUnits": "value",
        "decimals": 36
      },
      "startedAt": "2025-01-01T00:00:00Z",
      "totalSlices": 1
    },
    "feeScheduleVersion": "1",
    "fees": {
      "affiliates": [
        {
          "accountId": "3Gjjw3W5BAR",
          "bps": 1
        }
      ],
      "brokerBps": 1
    },
    "idempotencyKey": "idem_01J5EXAMPLE0000000000000",
    "isTerminal": false,
    "quote": {
      "depositAmount": {
        "baseUnits": "value",
        "decimals": 36
      },
      "expectedAmountOut": {
        "baseUnits": "value",
        "decimals": 36
      },
      "expiresAt": "2025-01-01T00:00:00Z",
      "fees": [
        {
          "accountId": "3BWMYZjBBMT",
          "amount": {
            "baseUnits": "value",
            "decimals": 36
          },
          "bps": 1,
          "kind": "SERVICE",
          "zippedAssetId": 100
        }
      ],
      "intermediateAssetId": 100,
      "maxDepositAmount": {
        "baseUnits": "value",
        "decimals": 36
      },
      "minAmountOut": {
        "baseUnits": "value",
        "decimals": 36
      },
      "minDepositAmount": {
        "baseUnits": "value",
        "decimals": 36
      },
      "minRate": "value",
      "quotedAt": "2025-01-01T00:00:00Z"
    },
    "reason": "SOURCE_SCREENING_FAILED",
    "refundAddress": "value",
    "refundMemo": "value",
    "refundZippedAssetId": 100,
    "returnAddress": "value",
    "returnMemo": "value",
    "screening": {
      "sourceWallet": "value"
    },
    "status": "ALLOCATING",
    "swapId": "1",
    "terminalAt": "2025-01-01T00:00:00Z",
    "terms": {
      "amount": {
        "baseUnits": "value",
        "decimals": 36
      },
      "basis": "SOURCE_AMOUNT",
      "destinationZippedAssetId": 100,
      "execution": {
        "market": {}
      },
      "protection": {
        "maxSlippageBps": 1
      },
      "sourceZippedAssetId": 100
    },
    "updatedAt": "2025-01-01T00:00:00Z",
    "version": "1",
    "withdrawals": [
      {
        "address": "0x3333333333333333333333333333333333333333",
        "amount": {
          "baseUnits": "value",
          "decimals": 36
        },
        "depositIndex": 1,
        "finalizedAt": "2025-01-01T00:00:00Z",
        "flowId": "flow_7YWHMfk9JZeLMgZauHuiSxhJ",
        "index": 1,
        "memo": "value",
        "networkFee": {
          "baseUnits": "value",
          "decimals": 36
        },
        "role": "DESTINATION",
        "state": "QUEUED",
        "submittedAt": "2025-01-01T00:00:00Z",
        "txHash": "0xabc123def4567890abc123def4567890abc123def4567890abc123def4567890",
        "unsentAmount": {
          "baseUnits": "value",
          "decimals": 36
        },
        "zippedAssetId": 100
      }
    ],
    "withdrawalsTruncated": false
  }
}