Create a Rate-Locked Quote

Create a Quote

curl --request POST \
  --url https://api.spherepay.co/v2/quote \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": "100.00",
  "customerId": "customer_3faa484998f44cfead9668608b9ee1f5",
  "destination": {
    "currency": "brl",
    "network": "pix"
  },
  "source": {
    "currency": "usdc",
    "network": "polygon"
  },
  "integratorBpsFeeRate": "20",
  "quoteDurationSeconds": 60,
  "referenceSide": "source"
}
'

import requests

url = "https://api.spherepay.co/v2/quote"

payload = {
    "amount": "100.00",
    "customerId": "customer_3faa484998f44cfead9668608b9ee1f5",
    "destination": {
        "currency": "brl",
        "network": "pix"
    },
    "source": {
        "currency": "usdc",
        "network": "polygon"
    },
    "integratorBpsFeeRate": "20",
    "quoteDurationSeconds": 60,
    "referenceSide": "source"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amount: '100.00',
    customerId: 'customer_3faa484998f44cfead9668608b9ee1f5',
    destination: {currency: 'brl', network: 'pix'},
    source: {currency: 'usdc', network: 'polygon'},
    integratorBpsFeeRate: '20',
    quoteDurationSeconds: 60,
    referenceSide: 'source'
  })
};

fetch('https://api.spherepay.co/v2/quote', 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.spherepay.co/v2/quote",
  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([
    'amount' => '100.00',
    'customerId' => 'customer_3faa484998f44cfead9668608b9ee1f5',
    'destination' => [
        'currency' => 'brl',
        'network' => 'pix'
    ],
    'source' => [
        'currency' => 'usdc',
        'network' => 'polygon'
    ],
    'integratorBpsFeeRate' => '20',
    'quoteDurationSeconds' => 60,
    'referenceSide' => 'source'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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.spherepay.co/v2/quote"

	payload := strings.NewReader("{\n  \"amount\": \"100.00\",\n  \"customerId\": \"customer_3faa484998f44cfead9668608b9ee1f5\",\n  \"destination\": {\n    \"currency\": \"brl\",\n    \"network\": \"pix\"\n  },\n  \"source\": {\n    \"currency\": \"usdc\",\n    \"network\": \"polygon\"\n  },\n  \"integratorBpsFeeRate\": \"20\",\n  \"quoteDurationSeconds\": 60,\n  \"referenceSide\": \"source\"\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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.spherepay.co/v2/quote")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": \"100.00\",\n  \"customerId\": \"customer_3faa484998f44cfead9668608b9ee1f5\",\n  \"destination\": {\n    \"currency\": \"brl\",\n    \"network\": \"pix\"\n  },\n  \"source\": {\n    \"currency\": \"usdc\",\n    \"network\": \"polygon\"\n  },\n  \"integratorBpsFeeRate\": \"20\",\n  \"quoteDurationSeconds\": 60,\n  \"referenceSide\": \"source\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.spherepay.co/v2/quote")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": \"100.00\",\n  \"customerId\": \"customer_3faa484998f44cfead9668608b9ee1f5\",\n  \"destination\": {\n    \"currency\": \"brl\",\n    \"network\": \"pix\"\n  },\n  \"source\": {\n    \"currency\": \"usdc\",\n    \"network\": \"polygon\"\n  },\n  \"integratorBpsFeeRate\": \"20\",\n  \"quoteDurationSeconds\": 60,\n  \"referenceSide\": \"source\"\n}"

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

{
  "created": "2025-01-01T00:00:00.000Z",
  "customerId": "customer_d243ab2b1de4447d8a046d87fefe58cf",
  "destination": {
    "amount": "545.50",
    "currency": "brl",
    "exchangeRate": "5.455",
    "network": "pix"
  },
  "expiresAt": "2025-01-01T00:01:00.000Z",
  "fees": {
    "integratorFee": {
      "bpsRate": "0",
      "currency": "usdc",
      "fixedAmount": "0.00",
      "totalAmount": "0.00"
    },
    "platformFee": {
      "bpsRate": "20",
      "currency": "usdc",
      "fixedAmount": "0.00",
      "totalAmount": "2.00"
    }
  },
  "id": "quote_d243ab2b1de4447d8a046d87fefe58cf",
  "source": {
    "amount": "100.00",
    "currency": "usdc",
    "network": "polygon"
  },
  "type": "off_ramp",
  "quoteDurationSeconds": 45,
  "referenceSide": "source",
  "status": "active"
}

{
  "code": "address/invalid",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "detail": "Invalid request parameters",
  "status": 400
}

{
  "code": "resource/not-found",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "detail": "Resource not found",
  "status": 404
}

{
  "code": "validation/failed",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "detail": "Validation failed",
  "errors": [
    {
      "detail": "Invalid email format",
      "pointer": "/email"
    },
    {
      "detail": "Name is required",
      "pointer": "/name"
    }
  ],
  "status": 422
}

Create a Quote

curl --request POST \
  --url https://api.spherepay.co/v2/quote \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": "100.00",
  "customerId": "customer_3faa484998f44cfead9668608b9ee1f5",
  "destination": {
    "currency": "brl",
    "network": "pix"
  },
  "source": {
    "currency": "usdc",
    "network": "polygon"
  },
  "integratorBpsFeeRate": "20",
  "quoteDurationSeconds": 60,
  "referenceSide": "source"
}
'

import requests

url = "https://api.spherepay.co/v2/quote"

payload = {
    "amount": "100.00",
    "customerId": "customer_3faa484998f44cfead9668608b9ee1f5",
    "destination": {
        "currency": "brl",
        "network": "pix"
    },
    "source": {
        "currency": "usdc",
        "network": "polygon"
    },
    "integratorBpsFeeRate": "20",
    "quoteDurationSeconds": 60,
    "referenceSide": "source"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amount: '100.00',
    customerId: 'customer_3faa484998f44cfead9668608b9ee1f5',
    destination: {currency: 'brl', network: 'pix'},
    source: {currency: 'usdc', network: 'polygon'},
    integratorBpsFeeRate: '20',
    quoteDurationSeconds: 60,
    referenceSide: 'source'
  })
};

fetch('https://api.spherepay.co/v2/quote', 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.spherepay.co/v2/quote",
  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([
    'amount' => '100.00',
    'customerId' => 'customer_3faa484998f44cfead9668608b9ee1f5',
    'destination' => [
        'currency' => 'brl',
        'network' => 'pix'
    ],
    'source' => [
        'currency' => 'usdc',
        'network' => 'polygon'
    ],
    'integratorBpsFeeRate' => '20',
    'quoteDurationSeconds' => 60,
    'referenceSide' => 'source'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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.spherepay.co/v2/quote"

	payload := strings.NewReader("{\n  \"amount\": \"100.00\",\n  \"customerId\": \"customer_3faa484998f44cfead9668608b9ee1f5\",\n  \"destination\": {\n    \"currency\": \"brl\",\n    \"network\": \"pix\"\n  },\n  \"source\": {\n    \"currency\": \"usdc\",\n    \"network\": \"polygon\"\n  },\n  \"integratorBpsFeeRate\": \"20\",\n  \"quoteDurationSeconds\": 60,\n  \"referenceSide\": \"source\"\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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.spherepay.co/v2/quote")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": \"100.00\",\n  \"customerId\": \"customer_3faa484998f44cfead9668608b9ee1f5\",\n  \"destination\": {\n    \"currency\": \"brl\",\n    \"network\": \"pix\"\n  },\n  \"source\": {\n    \"currency\": \"usdc\",\n    \"network\": \"polygon\"\n  },\n  \"integratorBpsFeeRate\": \"20\",\n  \"quoteDurationSeconds\": 60,\n  \"referenceSide\": \"source\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.spherepay.co/v2/quote")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": \"100.00\",\n  \"customerId\": \"customer_3faa484998f44cfead9668608b9ee1f5\",\n  \"destination\": {\n    \"currency\": \"brl\",\n    \"network\": \"pix\"\n  },\n  \"source\": {\n    \"currency\": \"usdc\",\n    \"network\": \"polygon\"\n  },\n  \"integratorBpsFeeRate\": \"20\",\n  \"quoteDurationSeconds\": 60,\n  \"referenceSide\": \"source\"\n}"

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

{
  "created": "2025-01-01T00:00:00.000Z",
  "customerId": "customer_d243ab2b1de4447d8a046d87fefe58cf",
  "destination": {
    "amount": "545.50",
    "currency": "brl",
    "exchangeRate": "5.455",
    "network": "pix"
  },
  "expiresAt": "2025-01-01T00:01:00.000Z",
  "fees": {
    "integratorFee": {
      "bpsRate": "0",
      "currency": "usdc",
      "fixedAmount": "0.00",
      "totalAmount": "0.00"
    },
    "platformFee": {
      "bpsRate": "20",
      "currency": "usdc",
      "fixedAmount": "0.00",
      "totalAmount": "2.00"
    }
  },
  "id": "quote_d243ab2b1de4447d8a046d87fefe58cf",
  "source": {
    "amount": "100.00",
    "currency": "usdc",
    "network": "polygon"
  },
  "type": "off_ramp",
  "quoteDurationSeconds": 45,
  "referenceSide": "source",
  "status": "active"
}

{
  "code": "address/invalid",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "detail": "Invalid request parameters",
  "status": 400
}

{
  "code": "resource/not-found",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "detail": "Resource not found",
  "status": 404
}

{
  "code": "validation/failed",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "detail": "Validation failed",
  "errors": [
    {
      "detail": "Invalid email format",
      "pointer": "/email"
    },
    {
      "detail": "Name is required",
      "pointer": "/name"
    }
  ],
  "status": 422
}

Use this endpoint to lock an exchange rate before creating a transfer. Quotes give the customer a deterministic source-to-destination conversion rate that’s valid for a fixed window (30, 60, or 300 seconds). The quote captures the source amount, destination amount, exchange rate, and full fee breakdown (integrator + platform) at the moment of issuance. A quote can be redeemed exactly once by passing its ID when calling Create Transfer.

Quotes are most useful for trading and cross-border payouts where the customer needs to see the exact rate they’ll receive before committing the transfer. For floating-rate transfers (e.g. payroll, treasury rebalancing), skip the quote and call /v2/transfer directly.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

amount

string

required

The quote amount. For MXN/USD RFQ it is denominated by referenceSide; all other corridors retain their existing source-amount behavior.

Pattern: ^\d+(\.\d{2})?$

Example:

"100.00"

customerId

string

required

The customer's ID.

Pattern: ^customer_[a-z0-9]+$

Example:

"customer_3faa484998f44cfead9668608b9ee1f5"

destination

object

required

The destination currency and network for the quote.

Show child attributes

source

object

required

The source currency and network for the quote.

Show child attributes

integratorBpsFeeRate

string

The integrator BPS fee rate. The BPS rate must be an integer string between 0 and 10000.

Pattern: ^\d+$

Example:

"20"

quoteDurationSeconds

number

For MXN/SPEI to USD/wire or USD/swift quotes, the field may be omitted or must be 45; omission defaults to 45. For all other supported routes, explicit values must be 30, 60, or 300 seconds and omission defaults to 60.

Example:

60

referenceSide

enum<string>

MXN/USD RFQ only. The side denominating amount; defaults to source when omitted.

Available options:

source,

destination

Example:

"source"

Response

created

string<date-time>

required

The datetime the quote was created.

Example:

"2025-01-01T00:00:00.000Z"

customerId

string

required

The customer ID.

Example:

"customer_d243ab2b1de4447d8a046d87fefe58cf"

destination

object

required

Show child attributes

expiresAt

string<date-time>

required

The datetime when this quote expires.

Example:

"2025-01-01T00:01:00.000Z"

fees

object

required

Show child attributes

string

required

A unique identifier for the quote.

Pattern: ^quote_[a-z0-9]+$

Example:

"quote_d243ab2b1de4447d8a046d87fefe58cf"

source

object

required

Show child attributes

type

enum<string>

required

The transfer type this quote is for.

Available options:

on_ramp,

off_ramp,

fiat_to_fiat

Example:

"off_ramp"

quoteDurationSeconds

integer

RFQ-only quote duration in seconds.

Required range: x > 0

Example:

45

referenceSide

enum<string>

RFQ-only side whose amount was referenced for pricing.

Available options:

source,

destination

Example:

"source"

status

enum<string>

The current status of the quote.

Available options:

active,

used,

expired

Example:

"active"

Last modified on June 18, 2026

Onboarding

Accounts

Money movement

Webhooks

Create a Rate-Locked Quote

Authorizations

Body

Response