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.comand read credentials from thePWS_API_KEYandPWS_API_SECRETenvironment variables.
Workflow
1
Request a quote
Lock a price for ~2 minutes.
POST /v1/accounts/{account_id}/quotes2
Execute the quote
Commit the locked price before it expires.
POST /v1/accounts/{account_id}/quotes/{quote_id}/execute3
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 needsfrom, 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 theAPI-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 aPOST to /v1/accounts/{account_id}/quotes with the trade body.
Response example
Step 2: execute the quote
Send aPOST 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, pollGET /v1/accounts/{account_id}/quotes/{quote_id} until status reaches a terminal value (executed, expired, or failed).
Response example
Error handling
Best practices
- Treat
executed,expired, andfailedas terminal. Don’t retry execution after a terminal state — request a new quote. - Capture
Request-Idfrom response headers. It speeds up support investigations.