Prepare on-demand conversion

curl --request POST \
  --url https://api.sandbox.services.payward.com/v1/accounts/{account_id}/on-demand-conversions/prepare \
  --header 'API-Key: <api-key>' \
  --header 'API-Nonce: <api-key>' \
  --header 'API-Sign: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "from": {
    "symbol": "USD",
    "type": "bank",
    "amount": "1000.00",
    "bank_account": {
      "via": "rfp",
      "account_link_id": "AL7H1R6R6B6H1R6R6B6H1R6R6B"
    }
  },
  "to": {
    "symbol": "ETH",
    "type": "wallet",
    "wallet": {
      "via": "ethereum",
      "address": "0xabcdef1234567890abcdef1234567890abcdef12"
    }
  }
}
'

import requests

url = "https://api.sandbox.services.payward.com/v1/accounts/{account_id}/on-demand-conversions/prepare"

payload = {
    "from": {
        "symbol": "USD",
        "type": "bank",
        "amount": "1000.00",
        "bank_account": {
            "via": "rfp",
            "account_link_id": "AL7H1R6R6B6H1R6R6B6H1R6R6B"
        }
    },
    "to": {
        "symbol": "ETH",
        "type": "wallet",
        "wallet": {
            "via": "ethereum",
            "address": "0xabcdef1234567890abcdef1234567890abcdef12"
        }
    }
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "API-Key": "<api-key>",
    "API-Sign": "<api-key>",
    "API-Nonce": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    'API-Key': '<api-key>',
    'API-Sign': '<api-key>',
    'API-Nonce': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    from: {
      symbol: 'USD',
      type: 'bank',
      amount: '1000.00',
      bank_account: {via: 'rfp', account_link_id: 'AL7H1R6R6B6H1R6R6B6H1R6R6B'}
    },
    to: {
      symbol: 'ETH',
      type: 'wallet',
      wallet: {via: 'ethereum', address: '0xabcdef1234567890abcdef1234567890abcdef12'}
    }
  })
};

fetch('https://api.sandbox.services.payward.com/v1/accounts/{account_id}/on-demand-conversions/prepare', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.services.payward.com/v1/accounts/{account_id}/on-demand-conversions/prepare",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'from' => [
        'symbol' => 'USD',
        'type' => 'bank',
        'amount' => '1000.00',
        'bank_account' => [
                'via' => 'rfp',
                'account_link_id' => 'AL7H1R6R6B6H1R6R6B6H1R6R6B'
        ]
    ],
    'to' => [
        'symbol' => 'ETH',
        'type' => 'wallet',
        'wallet' => [
                'via' => 'ethereum',
                'address' => '0xabcdef1234567890abcdef1234567890abcdef12'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "API-Key: <api-key>",
    "API-Nonce: <api-key>",
    "API-Sign: <api-key>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.services.payward.com/v1/accounts/{account_id}/on-demand-conversions/prepare"

	payload := strings.NewReader("{\n  \"from\": {\n    \"symbol\": \"USD\",\n    \"type\": \"bank\",\n    \"amount\": \"1000.00\",\n    \"bank_account\": {\n      \"via\": \"rfp\",\n      \"account_link_id\": \"AL7H1R6R6B6H1R6R6B6H1R6R6B\"\n    }\n  },\n  \"to\": {\n    \"symbol\": \"ETH\",\n    \"type\": \"wallet\",\n    \"wallet\": {\n      \"via\": \"ethereum\",\n      \"address\": \"0xabcdef1234567890abcdef1234567890abcdef12\"\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("API-Key", "<api-key>")
	req.Header.Add("API-Sign", "<api-key>")
	req.Header.Add("API-Nonce", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sandbox.services.payward.com/v1/accounts/{account_id}/on-demand-conversions/prepare")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("API-Key", "<api-key>")
  .header("API-Sign", "<api-key>")
  .header("API-Nonce", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"from\": {\n    \"symbol\": \"USD\",\n    \"type\": \"bank\",\n    \"amount\": \"1000.00\",\n    \"bank_account\": {\n      \"via\": \"rfp\",\n      \"account_link_id\": \"AL7H1R6R6B6H1R6R6B6H1R6R6B\"\n    }\n  },\n  \"to\": {\n    \"symbol\": \"ETH\",\n    \"type\": \"wallet\",\n    \"wallet\": {\n      \"via\": \"ethereum\",\n      \"address\": \"0xabcdef1234567890abcdef1234567890abcdef12\"\n    }\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.services.payward.com/v1/accounts/{account_id}/on-demand-conversions/prepare")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["API-Key"] = '<api-key>'
request["API-Sign"] = '<api-key>'
request["API-Nonce"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"from\": {\n    \"symbol\": \"USD\",\n    \"type\": \"bank\",\n    \"amount\": \"1000.00\",\n    \"bank_account\": {\n      \"via\": \"rfp\",\n      \"account_link_id\": \"AL7H1R6R6B6H1R6R6B6H1R6R6B\"\n    }\n  },\n  \"to\": {\n    \"symbol\": \"ETH\",\n    \"type\": \"wallet\",\n    \"wallet\": {\n      \"via\": \"ethereum\",\n      \"address\": \"0xabcdef1234567890abcdef1234567890abcdef12\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": "c1a7e2f4-31b9-4f0e-8d63-7a2b9c5d0e11",
    "status": "prepared",
    "from": {
      "symbol": "USD",
      "type": "bank",
      "amount": "1000.00",
      "status": "pending",
      "bank_account": {
        "via": "rfp",
        "account_link_id": "AL7H1R6R6B6H1R6R6B6H1R6R6B"
      }
    },
    "to": {
      "symbol": "ETH",
      "type": "wallet",
      "amount": "0.39770000",
      "status": "pending",
      "wallet": {
        "via": "ethereum",
        "address": "0xabcdef1234567890abcdef1234567890abcdef12"
      }
    },
    "rate": {
      "base": {
        "symbol": "USD"
      },
      "quote": {
        "symbol": "ETH"
      },
      "price": "0.0004"
    },
    "fees": {
      "from": {
        "symbol": "USD",
        "amount": "0.00"
      },
      "trade": {
        "symbol": "USD",
        "amount": "5.00"
      },
      "to": {
        "symbol": "ETH",
        "amount": "0.00030000"
      }
    },
    "created_at": "2026-10-05T12:00:00Z",
    "updated_at": "2026-10-05T12:00:00Z",
    "expires_at": "2026-10-05T12:02:00Z"
  }
}

Conversions

Prepare on-demand conversion

Creates an on-demand conversion in status prepared. Its price and fees are locked up to expires_at. The conversion does not start and does not reserve funds. To start it, call Execute prepared on-demand conversion before expires_at. To start a conversion at once, call Execute on-demand conversion.

To preview indicative amounts, rates, and fees without locking a price, use Estimate on-demand conversion.

If the conversion is not executed before expires_at, or the locked price can no longer be honored, the conversion is canceled. Then status is canceled and cancellation_reason tells why. Prepare a new conversion to try again.

An Idempotency-Key identifies one prepare request. If this endpoint already received the key, it does not prepare a new conversion. The response is a 409 error with code idempotency_key_already_used and the conversion_id of the conversion that the first request prepared. To get the result of the first request, call Get on-demand conversion with that conversion_id.

Prepare checks keys separately from Execute on-demand conversion and Execute prepared on-demand conversion. A key that one of these endpoints received does not cause a conflict here. Use a new key for each new request.

POST

accounts

{account_id}

on-demand-conversions

prepare

Prepare on-demand conversion

curl --request POST \
  --url https://api.sandbox.services.payward.com/v1/accounts/{account_id}/on-demand-conversions/prepare \
  --header 'API-Key: <api-key>' \
  --header 'API-Nonce: <api-key>' \
  --header 'API-Sign: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "from": {
    "symbol": "USD",
    "type": "bank",
    "amount": "1000.00",
    "bank_account": {
      "via": "rfp",
      "account_link_id": "AL7H1R6R6B6H1R6R6B6H1R6R6B"
    }
  },
  "to": {
    "symbol": "ETH",
    "type": "wallet",
    "wallet": {
      "via": "ethereum",
      "address": "0xabcdef1234567890abcdef1234567890abcdef12"
    }
  }
}
'

import requests

url = "https://api.sandbox.services.payward.com/v1/accounts/{account_id}/on-demand-conversions/prepare"

payload = {
    "from": {
        "symbol": "USD",
        "type": "bank",
        "amount": "1000.00",
        "bank_account": {
            "via": "rfp",
            "account_link_id": "AL7H1R6R6B6H1R6R6B6H1R6R6B"
        }
    },
    "to": {
        "symbol": "ETH",
        "type": "wallet",
        "wallet": {
            "via": "ethereum",
            "address": "0xabcdef1234567890abcdef1234567890abcdef12"
        }
    }
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "API-Key": "<api-key>",
    "API-Sign": "<api-key>",
    "API-Nonce": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    'API-Key': '<api-key>',
    'API-Sign': '<api-key>',
    'API-Nonce': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    from: {
      symbol: 'USD',
      type: 'bank',
      amount: '1000.00',
      bank_account: {via: 'rfp', account_link_id: 'AL7H1R6R6B6H1R6R6B6H1R6R6B'}
    },
    to: {
      symbol: 'ETH',
      type: 'wallet',
      wallet: {via: 'ethereum', address: '0xabcdef1234567890abcdef1234567890abcdef12'}
    }
  })
};

fetch('https://api.sandbox.services.payward.com/v1/accounts/{account_id}/on-demand-conversions/prepare', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.services.payward.com/v1/accounts/{account_id}/on-demand-conversions/prepare",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'from' => [
        'symbol' => 'USD',
        'type' => 'bank',
        'amount' => '1000.00',
        'bank_account' => [
                'via' => 'rfp',
                'account_link_id' => 'AL7H1R6R6B6H1R6R6B6H1R6R6B'
        ]
    ],
    'to' => [
        'symbol' => 'ETH',
        'type' => 'wallet',
        'wallet' => [
                'via' => 'ethereum',
                'address' => '0xabcdef1234567890abcdef1234567890abcdef12'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "API-Key: <api-key>",
    "API-Nonce: <api-key>",
    "API-Sign: <api-key>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.services.payward.com/v1/accounts/{account_id}/on-demand-conversions/prepare"

	payload := strings.NewReader("{\n  \"from\": {\n    \"symbol\": \"USD\",\n    \"type\": \"bank\",\n    \"amount\": \"1000.00\",\n    \"bank_account\": {\n      \"via\": \"rfp\",\n      \"account_link_id\": \"AL7H1R6R6B6H1R6R6B6H1R6R6B\"\n    }\n  },\n  \"to\": {\n    \"symbol\": \"ETH\",\n    \"type\": \"wallet\",\n    \"wallet\": {\n      \"via\": \"ethereum\",\n      \"address\": \"0xabcdef1234567890abcdef1234567890abcdef12\"\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("API-Key", "<api-key>")
	req.Header.Add("API-Sign", "<api-key>")
	req.Header.Add("API-Nonce", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sandbox.services.payward.com/v1/accounts/{account_id}/on-demand-conversions/prepare")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("API-Key", "<api-key>")
  .header("API-Sign", "<api-key>")
  .header("API-Nonce", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"from\": {\n    \"symbol\": \"USD\",\n    \"type\": \"bank\",\n    \"amount\": \"1000.00\",\n    \"bank_account\": {\n      \"via\": \"rfp\",\n      \"account_link_id\": \"AL7H1R6R6B6H1R6R6B6H1R6R6B\"\n    }\n  },\n  \"to\": {\n    \"symbol\": \"ETH\",\n    \"type\": \"wallet\",\n    \"wallet\": {\n      \"via\": \"ethereum\",\n      \"address\": \"0xabcdef1234567890abcdef1234567890abcdef12\"\n    }\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.services.payward.com/v1/accounts/{account_id}/on-demand-conversions/prepare")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["API-Key"] = '<api-key>'
request["API-Sign"] = '<api-key>'
request["API-Nonce"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"from\": {\n    \"symbol\": \"USD\",\n    \"type\": \"bank\",\n    \"amount\": \"1000.00\",\n    \"bank_account\": {\n      \"via\": \"rfp\",\n      \"account_link_id\": \"AL7H1R6R6B6H1R6R6B6H1R6R6B\"\n    }\n  },\n  \"to\": {\n    \"symbol\": \"ETH\",\n    \"type\": \"wallet\",\n    \"wallet\": {\n      \"via\": \"ethereum\",\n      \"address\": \"0xabcdef1234567890abcdef1234567890abcdef12\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": "c1a7e2f4-31b9-4f0e-8d63-7a2b9c5d0e11",
    "status": "prepared",
    "from": {
      "symbol": "USD",
      "type": "bank",
      "amount": "1000.00",
      "status": "pending",
      "bank_account": {
        "via": "rfp",
        "account_link_id": "AL7H1R6R6B6H1R6R6B6H1R6R6B"
      }
    },
    "to": {
      "symbol": "ETH",
      "type": "wallet",
      "amount": "0.39770000",
      "status": "pending",
      "wallet": {
        "via": "ethereum",
        "address": "0xabcdef1234567890abcdef1234567890abcdef12"
      }
    },
    "rate": {
      "base": {
        "symbol": "USD"
      },
      "quote": {
        "symbol": "ETH"
      },
      "price": "0.0004"
    },
    "fees": {
      "from": {
        "symbol": "USD",
        "amount": "0.00"
      },
      "trade": {
        "symbol": "USD",
        "amount": "5.00"
      },
      "to": {
        "symbol": "ETH",
        "amount": "0.00030000"
      }
    },
    "created_at": "2026-10-05T12:00:00Z",
    "updated_at": "2026-10-05T12:00:00Z",
    "expires_at": "2026-10-05T12:02:00Z"
  }
}

Authorizations

API-Key

string

header

required

Your public API key. Identifies the partner making the request.

API-Sign

string

header

required

HMAC signature over the request, computed with your private key.

API-Nonce

string

header

required

Monotonically increasing nonce included in the request signature.

Headers

Idempotency-Key

string<uuid>

required

Client-generated canonical UUIDv4 that uniquely identifies a request for safe retries.

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

Globally unique public identifier for an account.

Required string length: 14 - 42

Body

application/json

Source amount
Destination amount

Provide from.amount to specify how much to debit. Omit to.amount; the service calculates the amount delivered to the destination.

from

OnDemandConversionBalanceSource · object

required

Source side of an on-demand conversion.

OnDemandConversionBalanceSource
OnDemandConversionBankSource

Show child attributes

OnDemandConversionWalletDestination · object

required

Destination side of an on-demand conversion.

OnDemandConversionWalletDestination
OnDemandConversionBankDestination

Show child attributes

Response

On-demand conversion prepared.

data

object

required

Details of an on-demand conversion. It includes the amount debited from the source, the amount delivered to the destination, the exchange rate, destination details, and fees. Transaction references are included when available. A linked bank source remains pending while funding is in progress. An RfP conversion includes next_action while its payer must authorize the payment. A wallet destination may include a saved memo or tag; when present, those fields are returned in every response.

Show child attributes