Skip to main content
POST
/
v1
/
accounts
/
{account_id}
/
conversions
curl
curl -X POST "https://api.services.payward.com/v1/accounts/W4BE9868GY65TB6523/conversions" \
  -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 '{
    "from": {
      "asset": {
        "symbol": "USD",
        "type": "fiat",
        "amount": "10000.00"
      },
      "source": { "type": "balance" }
    },
    "to": {
      "asset": {
        "symbol": "USDG",
        "type": "stablecoin"
      },
      "destination": {
        "type": "external_wallet",
        "wallet_id": "wl_client_usdg",
        "user_id": "tcs_cust_12345"
      }
    },
    "transaction_id": "tcs_tx_99001"
  }'
{
  "data": {
    "id": "conv_bal_001",
    "status": "completed",
    "from": {
      "account": "W4BE9868GY65TB6523",
      "asset": {
        "symbol": "USD",
        "name": "US Dollar",
        "type": "fiat",
        "amount": "10000.00"
      },
      "source": {
        "type": "balance"
      }
    },
    "to": {
      "asset": {
        "symbol": "USDG",
        "name": "Global Dollar",
        "type": "stablecoin",
        "amount": "9998.50"
      },
      "destination": {
        "type": "external_wallet",
        "wallet_id": "wl_client_usdg",
        "user_id": "tcs_cust_12345"
      }
    },
    "fees": {
      "trade": {
        "symbol": "USD",
        "name": "US Dollar",
        "type": "fiat",
        "amount": "1.50"
      }
    },
    "chain_references": {
      "withdraw_txid": "5r...solana_tx"
    },
    "created_at": "2026-04-24T16:00:00Z",
    "updated_at": "2026-04-24T16:00:02Z",
    "transaction_id": "tcs_tx_99001"
  }
}

Authorizations

​
api-key
string
header
required
​
api-sign
string
header
required
​
api-nonce
string
header
required
​
api-otp
string
header
required

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 one-shot conversion.

Pricing: omit swap_quote_id for indicative pricing (executes at market when the deposit lands); supply swap_quote_id to lock a previously created Swap quote. The supplied from/to assets must match the locked quote.

​
from
object
required

Source side of a conversion request. asset.amount is optional: omit it to convert whatever the inbound deposit credits (price-locked or indicative); set it to convert a fixed amount (required for source.type: balance).

​
to
object
required

Destination side of a conversion request. The amount delivered is computed from the source amount and the trade rate, so only the asset reference (symbol + type) is supplied here.

​
swap_quote_id
string

Optional ID of a Swap quote to lock. Mutually compatible with both source types.

Required string length: 1 - 64
​
transaction_id
string

Partner-supplied identifier for this conversion in the partner's system. Echoed back on the response.

Maximum string length: 128

Response

Successful response

​
data
object

A conversion resource.

Lifecycle for push-sourced conversions: pending_deposit → converting → settling → completed. Balance-sourced conversions skip pending_deposit. Terminal failures populate failure_reason; expired push-sourced conversions land in expired.