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 target https://api.services.payward.com and read credentials from the PWS_API_KEY and PWS_API_SECRET environment variables.

Workflow

1

Check quote limits (optional)

Confirm the amount you plan to fix falls within current min/max bounds.GET /v1/accounts/{account_id}/quotes/limits
2

Request a quote

Lock a price for ~2 minutes.POST /v1/accounts/{account_id}/quotes
3

Execute the quote

Commit the locked price before it expires.POST /v1/accounts/{account_id}/quotes/{quote_id}/execute
4

Poll for terminal status

Wait for the quote to settle, or subscribe to webhooks.GET /v1/accounts/{account_id}/quotes/{quote_id}

Quote lifecycle

A quote is valid for approximately 120 seconds (2 minutes) after creation. Calling execute on a quote whose expires_at has passed returns 410 Gone.

Specifying the trade

A quote needs from, to, and fee fields. Set the amount on exactly one of from or to to indicate which side of the trade is fixed. The server calculates the other side. Setting both or neither returns 400 Bad Request. Each side carries a type that classifies the asset: The fee object sets the partner’s fee applied on top of the execution price. Provide it as basis points, a flat amount, or both:
  • fee.bps — fee in basis points (1 bps = 0.01%, so 50 bps is 0.5%). Defaults to 0 when omitted.
  • fee.absolute — a flat fee amount denominated in the quote currency, sent as a decimal string (e.g., "10.00").
When both are set they combine. Omit fee entirely to charge no partner fee. An absolute value that is too small to apply or too large for the trade size is rejected with 400 Bad Request on fee.absolute.

Check quote limits

Before creating a quote, you can fetch the effective amount limits for a pair on the selected account:
Required query parameters: Limits are a point-in-time estimate and can change before you create a quote. Clamp create-quote amounts to [minimum_swap, maximum]. When present, limit_reasons explains which constraints contributed to maximum. Dust-only floors are not exposed on this endpoint; a dust-sweep-specific minimum may be added later.

Response example

Authentication setup

Authenticated endpoints require an HMAC-SHA512 request signature in the API-Sign header and a monotonically increasing nonce in the API-Nonce header. The helper below derives the signature from the URL path, request body, and nonce. See the Authentication guide for the full algorithm.

Step 1: request a quote

Send a POST to /v1/accounts/{account_id}/quotes with the trade body.

Response example

Quotes expire after 120 seconds (2 minutes). Execute the quote promptly or request a new one if it expires. The exact expiration time is returned in the expires_at field of the quote response.

Step 2: execute the quote

Send a POST to /v1/accounts/{account_id}/quotes/{quote_id}/execute with an empty body. The response confirms the quote moved to executing; settlement happens asynchronously.

Response example

Step 3: poll for terminal status

After executing, poll GET /v1/accounts/{account_id}/quotes/{quote_id} until status reaches a terminal value (executed, expired, or failed).

Response example

Instead of polling, subscribe to the quote.executed and quote.execution_failed webhooks and use GET only for reconciliation.

Error handling

Best practices

  • Capture Request-Id from response headers. It speeds up support investigations.

API reference