swap.quickswap.v1.QuickSwapService

GetQuickSwap

GetQuickSwap returns the current state of one QuickSwap by swap_id or by idempotency key. Errors: - INVALID_ARGUMENT: malformed selector. - NOT_FOUND: SWAP_NOT_FOUND. - RESOURCE_EXHAUSTED: BROKER_LIMIT, the read request rate of the key. - UNAUTHENTICATED: missing or invalid broker API key.

Method

POST

Path

swap.quickswap.v1.QuickSwapService/GetQuickSwap

Service

swap.quickswap.v1.QuickSwapService

Visibility

Authentication required

MFA Requirement

Not required

POST

swap.quickswap.v1.QuickSwapService/GetQuickSwap

Request

Testnet

curl --request POST \ \
  --url 'https://api.testnet.polyester.com/swap.quickswap.v1.QuickSwapService/GetQuickSwap' \
  --header 'Content-Type: application/json' \
  --header 'Connect-Protocol-Version: 1' \
  --data '{
  "swapId": "1"
}'

Responses

{
  "quickSwap": {
    "chargedFees": [
      {
        "accountId": "7563897446546",
        "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": "7563897446546",
          "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": "7563897446546",
          "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
  }
}

Request

swap.quickswap.v1.GetQuickSwapRequest

Response

swap.quickswap.v1.GetQuickSwapResponse

swapId string (fixed64) required one of > 0

Public QuickSwap identifier.

idempotencyKey string required one of /^[A-Za…,128}$/

Idempotency key used to create it; resolves a QuickSwap whose create outcome was unknown.

one-of

28 fields

swapId string (fixed64)

Public QuickSwap identifier.

idempotencyKey string

The broker's idempotency key that created this QuickSwap.

status enum

Current status.

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

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

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.

6 fields

sourceZippedAssetId integer (int32) > 0

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.

destinationZippedAssetId integer (int32) > 0

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.

basis enum must be defined value

Side of the swap that amount denominates.

SOURCE_AMOUNT DESTINATION_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.

destinationMemo string

Destination tag or memo for destination_address; empty when none.

returnAddress string

Recipient of returned source funds on the source network.

returnMemo string

Destination tag or memo for return_address; empty when none.

refundZippedAssetId integer (int32)

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

refundAddress string

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

refundMemo string

Destination tag or memo for refund_address; empty when none.

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.

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.

5 fields

quotedAt string (date-time)

When the quote was priced.

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.

8 fields

address string

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

memo string

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

zippedAssetId integer (int32)

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

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.

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.

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.

addressState enum

Current lifecycle state of the address.

ACTIVE REFUND_MODE RETIRED

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.

1 field

12 fields

index integer (int32)

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

txHash string

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

txOccurrenceIndex string (uint64)

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

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.

2 fields

disposition enum

What this deposit may do.

EVALUATING ELIGIBLE RETURN_ONLY ON_HOLD MANUAL_RECOVERY

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.

confirmations integer (int32)

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

requiredConfirmations integer (int32)

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

detectedAt string (date-time)

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

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).

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.

depositsTruncated boolean

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

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.

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.

startedAt string (date-time)

When execution started.

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.

finishedAt string (date-time)

When execution finished; unset while executing.

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.

role enum

Why this withdrawal pays its recipient.

DESTINATION REFUND RETURN

depositIndex integer (int32)

Deposit whose funds this withdrawal moves.

zippedAssetId integer (int32)

Asset and network paid, as a zipped_asset_id.

address string

Recipient address in the network's native text form.

memo string

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

2 fields

state enum

Withdrawal progress.

QUEUED SUBMITTED FINALIZED FAILED NOT_SENT

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.

submittedAt string (date-time)

When the withdrawal was submitted; unset until submitted.

finalizedAt string (date-time)

When the withdrawal became final; unset until FINALIZED.

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.

2 fields

withdrawalsTruncated boolean

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

createdAt string (date-time)

When the QuickSwap was created.

updatedAt string (date-time)

When the QuickSwap last changed.

terminalAt string (date-time)

When status became terminal; unset while not terminal.

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.

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.

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.

POST

swap.quickswap.v1.QuickSwapService/GetQuickSwap

Request

Testnet

curl --request POST \ \
  --url 'https://api.testnet.polyester.com/swap.quickswap.v1.QuickSwapService/GetQuickSwap' \
  --header 'Content-Type: application/json' \
  --header 'Connect-Protocol-Version: 1' \
  --data '{
  "swapId": "1"
}'

Responses

{
  "quickSwap": {
    "chargedFees": [
      {
        "accountId": "7563897446546",
        "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": "7563897446546",
          "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": "7563897446546",
          "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
  }
}