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

Request a quote

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

Execute the quote

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

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: fee.bps is the partner’s fee in basis points (1 bps = 0.01%, so 50 bps is 0.5%).

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

  1. Treat executed, expired, and failed as terminal. Don’t retry execution after a terminal state — request a new quote.
  2. Capture Request-Id from response headers. It speeds up support investigations.

API reference