Skip to main content
POST
/
v1
/
accounts
/
{account_id}
/
price-trigger-swaps
curl
curl -X POST "https://api.services.payward.com/v1/accounts/W4BE9868GY65TB6523/price-trigger-swaps" \
  -H "API-Key: $PWS_API_KEY" \
  -H "API-Nonce: $PWS_API_NONCE" \
  -H "API-Sign: $PWS_API_SIGN" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Buy 100 USD of BTC under 50k",
    "trade": {
      "from": { "symbol": "USD", "type": "fiat", "amount": "100.00" },
      "to": { "symbol": "BTC", "type": "crypto" },
      "fee": { "bps": 50 }
    },
    "when": {
      "base": { "symbol": "BTC", "type": "crypto" },
      "quote": { "symbol": "USD", "type": "fiat" },
      "drops_to": "50000.00"
    }
  }'
{
  "data": {
    "id": "swap_01J0M7C0Z9F8YX3GQH8E"
  }
}

Authorizations

​
API-Key
string
header
required

Your public API key. Identifies the partner making the request.

​
API-Nonce
string
header
required

Monotonically increasing nonce included in the request signature.

​
API-Sign
string
header
required

HMAC signature over the request, computed with your private key.

Headers

​
Idempotency-Key
string<uuid>

Client-generated UUIDv4 for safe retries. Sent as the Idempotency-Key HTTP header. Replayed responses include the Idempotent-Replayed: true header.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
Example:

"550e8400-e29b-41d4-a716-446655440000"

Path Parameters

​
account_id
string
required

ID of the account the request applies to. This refers to one of the accounts held by the user the request is acting on behalf of (typically the user's main account, but any of the user's accounts is accepted). Routes the request to that specific account container. Canonical identifier for an account in the Payward public API.

Required string length: 14 - 42

Body

application/json

Request to create a new price trigger swap.

​
trade
object
required

The trade to execute when the order's when condition fires.

from and to use the same AssetAmount shape as a swap quote — a price trigger swap is, in effect, a swap quote that waits for a price condition before executing. Exactly one of from.amount or to.amount must be provided to indicate which side of the trade is fixed; the other side's amount is determined at execution time. Setting both amounts or omitting both is rejected with a 400 Bad Request.

fee is the partner's configured fee, applied on top of the underlying execution price when the trade fires. Request-only — not echoed in response payloads.

​
when
object
required

The condition under which the order's trade fires.

Watches the price of the base/quote asset pair and fires when the live price reaches the threshold. Specify exactly one of drops_to or rises_to:

  • drops_to: fires when the price falls to or below the value (e.g. "buy on dip").
  • rises_to: fires when the price rises to or above the value (e.g. "take profit").
​
external_reference
string

Optional client-supplied external reference for the swap. Echoed back on reads and webhook events for client-side correlation. Not interpreted by Payward.

Required string length: 1 - 128

Response

Swap created. The Location header points at the new swap resource. The response body returns only the new swap's id; fetch GET /v1/accounts/{account_id}/price-trigger-swaps/{price_trigger_swap_id} for the full resource.

​
data
object