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
Check quote limits (optional)
Confirm the amount you plan to fix falls within current min/max bounds.
GET /v1/accounts/{account_id}/quotes/limits2
Request a quote
Lock a price for ~2 minutes.
POST /v1/accounts/{account_id}/quotes3
Execute the quote
Commit the locked price before it expires.
POST /v1/accounts/{account_id}/quotes/{quote_id}/execute4
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:
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 to0when omitted.fee.absolute— a flat fee amount denominated in the quote currency, sent as a decimal string (e.g.,"10.00").
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:
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 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
- Capture
Request-Idfrom response headers. It speeds up support investigations.