Skip to main content

Prerequisites

  • Payward Services API credentials (see the Authentication guide).
  • A verified user with at least one account and sufficient balance in the source asset.
  • Examples read the API base URL from the PWS_BASE_URL environment variable, and credentials from PWS_API_KEY and PWS_API_SECRET.

Workflow

1

Create a price trigger swap

Submit the swap with its trigger condition.POST /v1/accounts/{account_id}/price-trigger-swaps
2

Monitor or cancel

Track status, list active swaps, or cancel one that hasn’t fired yet.
  • GET /v1/accounts/{account_id}/price-trigger-swaps
  • GET /v1/accounts/{account_id}/price-trigger-swaps/{price_trigger_swap_id}
  • POST /v1/accounts/{account_id}/price-trigger-swaps/{price_trigger_swap_id}/cancel

Trigger conditions

The when block specifies the price to monitor and the threshold that fires the trade. Set the base and quote AssetRef pair, then exactly one of drops_to or rises_to: The threshold is a base/quote rate as a decimal string. For example, with base.symbol = BTC and quote.symbol = USD, drops_to: "50000.00" means “fire when 1 BTC trades at 50,000 USD or below”. Examples:
  • Buy the Dip: “Buy BTC when BTC/USD drops to 50,000”: set base.symbol to BTC, quote.symbol to USD, and drops_to to "50000.00". Pair with a trade whose from is USD and to is BTC.
  • Stop the Loss: “Sell BTC when BTC/USD drops to 50,000”: same when block, but with trade.from set to BTC and trade.to set to USD.
  • Join the Rally: “Buy BTC when BTC/USD rises to 80,000”: same pair, replace drops_to with rises_to: "80000.00". Trade goes USD → BTC.
  • Take the Profit: “Sell BTC when BTC/USD rises to 80,000”: same when block as Join the Rally, but with trade.from set to BTC and trade.to set to USD.

Execution behavior

Price trigger swaps are not guaranteed to execute at exactly the threshold price. The threshold is a trigger, not a limit price. The execution price can move beyond the threshold, but only ever in the direction that fired the trigger: it never crosses back to the other side of the threshold:
  • Buy the Dip / Stop the Loss (drops_to): The swap triggers when the market price drops to or below drops_to. The execution price may be lower than the threshold, but never higher.
  • Join the Rally / Take the Profit (rises_to): The swap triggers when the market price rises to or above rises_to. The execution price may be higher than the threshold, but never lower.
For swaps where the execution price is higher than the market price and the user is spending the client’s reserve fiat currency, an error will be returned at creation. Because the execution price may be higher than the threshold, the final spend amount is unbounded upward: this prevents a situation where a user creates a swap that could spend more fiat than the client has approved.

Authentication setup

Authenticated endpoints require an HMAC-SHA512 request signature in the API-Sign header and the signing time in the API-Timestamp header. The helpers below compute both. The examples call signed_headers (signedHeaders in JavaScript) with the request’s method, its path including any query string, and the exact body string they send. See the Authentication guide for the full algorithm. The examples read the API base URL from the PWS_BASE_URL environment variable, and your credentials from PWS_API_KEY and PWS_API_SECRET. Set PWS_BASE_URL to the sandbox or production base URL, listed in Environments.

Step 1: create a price trigger swap

Submit the swap with trade, when, and an optional client_order_id. Use a client_order_id of 1–64 printable ASCII characters. It must be unique per account. Reusing a value returns 409 Conflict with code: price_trigger_swap_client_order_id_duplicate. The response includes the full swap resource in data. You receive its id, status, requested trade, price condition, and timestamps. The response also includes client_order_id when you provide it. Set the amount on exactly one of trade.from or trade.to to indicate which side of the trade is fixed. Setting both or neither returns 400 Bad Request. The trade.fee object sets the partner’s fee on the trade that fires. Provide fee.bps (basis points, 1 bps = 0.01%), fee.absolute (a flat amount denominated in the trade’s quote currency, sent as a decimal string), or both: when both are set they combine. Omit fee to charge no partner fee.

Response example

Step 2: monitor swaps

Get a single swap

Response example

When status is completed, the response also includes executed.fees and executed.rate reflecting what was realized at execution time.

List swaps

Filter by status using the statuses query parameter (repeat for multiple values, or omit to include any status). Use page_token and page_size (default 20, max 25) for pagination: next_page_token is omitted on the final page. Pass the previous response’s next_page_token as page_token; for this endpoint that value is a price-triggered swap id (for example ALCCIA-CUT6P-XCW6K7).

Swap statuses

A cancelled swap is always user-initiated and carries no extra reason. When status is failed, the response includes a failure_reason field explaining why it was terminated. The value is one of:

Step 3: cancel a swap

Cancel an active swap that hasn’t triggered yet. Send an empty JSON object, {}, as the body. Swaps in completed, cancelled, or failed status are terminal and return 409 Conflict with code: price_trigger_swap_not_cancellable.

Webhook events

Subscribe to these events instead of polling for status changes: price_trigger_swap.cancelled covers user-requested cancellations and never includes failure_reason. System terminations, including exhausted retries, unavailable assets, and a locked user, deliver price_trigger_swap.failed. Webhook failure_reason is one of system_error, insufficient_market_liquidity, insufficient_funds, user_locked, user_request, or other. Retry exhaustion is other on the webhook. The swap resource reports retries_exhausted. Created and executed events include requested. The requested.when condition contains exactly one of drops_to or rises_to. Executed events may also include executed with the realized fill details when available.

Portfolio transactions

Successfully executed price trigger swaps appear in the List Portfolio Transactions endpoint as price_trigger_swap. Failed execution attempts do not appear because they have no ledger movements. Track them with the price_trigger_swap.execution_failed or price_trigger_swap.failed webhooks or the price trigger swap status.

API reference