Create a quote

curl --request POST \
  --url https://api.circle.com/v1/cpn/quotes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "senderCountry": "MX",
  "sourceAmount": {
    "amount": "10",
    "currency": "USDC"
  },
  "destinationCountry": "MX",
  "destinationAmount": {
    "amount": "",
    "currency": "MXN"
  },
  "blockchain": "ETH-SEPOLIA",
  "senderType": "BUSINESS",
  "recipientType": "BUSINESS",
  "paymentMethodType": "SPEI",
  "quoteOptions": {
    "isFirstParty": true
  },
  "transactionVersion": "VERSION_2"
}
'

import requests

url = "https://api.circle.com/v1/cpn/quotes"

payload = {
    "senderCountry": "MX",
    "sourceAmount": {
        "amount": "10",
        "currency": "USDC"
    },
    "destinationCountry": "MX",
    "destinationAmount": {
        "amount": "",
        "currency": "MXN"
    },
    "blockchain": "ETH-SEPOLIA",
    "senderType": "BUSINESS",
    "recipientType": "BUSINESS",
    "paymentMethodType": "SPEI",
    "quoteOptions": { "isFirstParty": True },
    "transactionVersion": "VERSION_2"
}
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({
    senderCountry: 'MX',
    sourceAmount: {amount: '10', currency: 'USDC'},
    destinationCountry: 'MX',
    destinationAmount: {amount: '', currency: 'MXN'},
    blockchain: 'ETH-SEPOLIA',
    senderType: 'BUSINESS',
    recipientType: 'BUSINESS',
    paymentMethodType: 'SPEI',
    quoteOptions: {isFirstParty: true},
    transactionVersion: 'VERSION_2'
  })
};

fetch('https://api.circle.com/v1/cpn/quotes', 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.circle.com/v1/cpn/quotes",
  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([
    'senderCountry' => 'MX',
    'sourceAmount' => [
        'amount' => '10',
        'currency' => 'USDC'
    ],
    'destinationCountry' => 'MX',
    'destinationAmount' => [
        'amount' => '',
        'currency' => 'MXN'
    ],
    'blockchain' => 'ETH-SEPOLIA',
    'senderType' => 'BUSINESS',
    'recipientType' => 'BUSINESS',
    'paymentMethodType' => 'SPEI',
    'quoteOptions' => [
        'isFirstParty' => true
    ],
    'transactionVersion' => 'VERSION_2'
  ]),
  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.circle.com/v1/cpn/quotes"

	payload := strings.NewReader("{\n  \"senderCountry\": \"MX\",\n  \"sourceAmount\": {\n    \"amount\": \"10\",\n    \"currency\": \"USDC\"\n  },\n  \"destinationCountry\": \"MX\",\n  \"destinationAmount\": {\n    \"amount\": \"\",\n    \"currency\": \"MXN\"\n  },\n  \"blockchain\": \"ETH-SEPOLIA\",\n  \"senderType\": \"BUSINESS\",\n  \"recipientType\": \"BUSINESS\",\n  \"paymentMethodType\": \"SPEI\",\n  \"quoteOptions\": {\n    \"isFirstParty\": true\n  },\n  \"transactionVersion\": \"VERSION_2\"\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.circle.com/v1/cpn/quotes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"senderCountry\": \"MX\",\n  \"sourceAmount\": {\n    \"amount\": \"10\",\n    \"currency\": \"USDC\"\n  },\n  \"destinationCountry\": \"MX\",\n  \"destinationAmount\": {\n    \"amount\": \"\",\n    \"currency\": \"MXN\"\n  },\n  \"blockchain\": \"ETH-SEPOLIA\",\n  \"senderType\": \"BUSINESS\",\n  \"recipientType\": \"BUSINESS\",\n  \"paymentMethodType\": \"SPEI\",\n  \"quoteOptions\": {\n    \"isFirstParty\": true\n  },\n  \"transactionVersion\": \"VERSION_2\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.circle.com/v1/cpn/quotes")

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  \"senderCountry\": \"MX\",\n  \"sourceAmount\": {\n    \"amount\": \"10\",\n    \"currency\": \"USDC\"\n  },\n  \"destinationCountry\": \"MX\",\n  \"destinationAmount\": {\n    \"amount\": \"\",\n    \"currency\": \"MXN\"\n  },\n  \"blockchain\": \"ETH-SEPOLIA\",\n  \"senderType\": \"BUSINESS\",\n  \"recipientType\": \"BUSINESS\",\n  \"paymentMethodType\": \"SPEI\",\n  \"quoteOptions\": {\n    \"isFirstParty\": true\n  },\n  \"transactionVersion\": \"VERSION_2\"\n}"

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

{
  "data": [
    {
      "type": "quote",
      "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
      "paymentMethodType": "SPEI",
      "blockchain": "ETH-SEPOLIA",
      "senderCountry": "MX",
      "destinationCountry": "MX",
      "createDate": "2023-01-01T12:04:05Z",
      "quoteExpireDate": "2023-01-01T12:04:05Z",
      "cryptoFundsSettlementExpireDate": "2023-01-01T12:04:05Z",
      "sourceAmount": {
        "amount": "10.000000",
        "currency": "USDC"
      },
      "destinationAmount": {
        "amount": "183.24",
        "currency": "MXN"
      },
      "fiatSettlementTime": {
        "max": "3",
        "min": "1",
        "unit": "DAYS"
      },
      "exchangeRate": {
        "pair": "USDC/MXN",
        "rate": "18.324000"
      },
      "fees": {
        "breakdown": [
          {
            "type": "BFI_TRANSACTION_FEE",
            "amount": {
              "amount": "0.240000",
              "currency": "USDC"
            }
          }
        ],
        "totalAmount": {
          "amount": "0.240000",
          "currency": "USDC"
        }
      },
      "senderType": "BUSINESS",
      "recipientType": "BUSINESS",
      "certificate": {
        "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
        "certPem": "LS0tLS1CRUdJT...",
        "domain": "api.circle.com",
        "jwk": {
          "crv": "P-256",
          "kid": "263521881931753643998528753619816524468853605762",
          "kty": "EC",
          "x": "KnxBe8fb2mL_Ve9-tqjGSkGgE9f0yohMkAvH_InaFtE",
          "y": "D41cVUpiKcey4LJKNFtUtmVHDWRmhjZapPLfryX5b1o"
        }
      },
      "quoteOptions": {
        "isFirstParty": true
      },
      "transactionVersion": "VERSION_2",
      "rawExchangeRate": {
        "pair": "USDC/MXN",
        "rate": "18.778689"
      }
    }
  ]
}

{
  "code": 400,
  "message": "Bad request."
}

{
  "code": 401,
  "message": "Malformed authorization."
}

{
  "code": 3,
  "message": "Forbidden"
}

POST

cpn

quotes

Create a quote

curl --request POST \
  --url https://api.circle.com/v1/cpn/quotes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "senderCountry": "MX",
  "sourceAmount": {
    "amount": "10",
    "currency": "USDC"
  },
  "destinationCountry": "MX",
  "destinationAmount": {
    "amount": "",
    "currency": "MXN"
  },
  "blockchain": "ETH-SEPOLIA",
  "senderType": "BUSINESS",
  "recipientType": "BUSINESS",
  "paymentMethodType": "SPEI",
  "quoteOptions": {
    "isFirstParty": true
  },
  "transactionVersion": "VERSION_2"
}
'

import requests

url = "https://api.circle.com/v1/cpn/quotes"

payload = {
    "senderCountry": "MX",
    "sourceAmount": {
        "amount": "10",
        "currency": "USDC"
    },
    "destinationCountry": "MX",
    "destinationAmount": {
        "amount": "",
        "currency": "MXN"
    },
    "blockchain": "ETH-SEPOLIA",
    "senderType": "BUSINESS",
    "recipientType": "BUSINESS",
    "paymentMethodType": "SPEI",
    "quoteOptions": { "isFirstParty": True },
    "transactionVersion": "VERSION_2"
}
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({
    senderCountry: 'MX',
    sourceAmount: {amount: '10', currency: 'USDC'},
    destinationCountry: 'MX',
    destinationAmount: {amount: '', currency: 'MXN'},
    blockchain: 'ETH-SEPOLIA',
    senderType: 'BUSINESS',
    recipientType: 'BUSINESS',
    paymentMethodType: 'SPEI',
    quoteOptions: {isFirstParty: true},
    transactionVersion: 'VERSION_2'
  })
};

fetch('https://api.circle.com/v1/cpn/quotes', 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.circle.com/v1/cpn/quotes",
  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([
    'senderCountry' => 'MX',
    'sourceAmount' => [
        'amount' => '10',
        'currency' => 'USDC'
    ],
    'destinationCountry' => 'MX',
    'destinationAmount' => [
        'amount' => '',
        'currency' => 'MXN'
    ],
    'blockchain' => 'ETH-SEPOLIA',
    'senderType' => 'BUSINESS',
    'recipientType' => 'BUSINESS',
    'paymentMethodType' => 'SPEI',
    'quoteOptions' => [
        'isFirstParty' => true
    ],
    'transactionVersion' => 'VERSION_2'
  ]),
  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.circle.com/v1/cpn/quotes"

	payload := strings.NewReader("{\n  \"senderCountry\": \"MX\",\n  \"sourceAmount\": {\n    \"amount\": \"10\",\n    \"currency\": \"USDC\"\n  },\n  \"destinationCountry\": \"MX\",\n  \"destinationAmount\": {\n    \"amount\": \"\",\n    \"currency\": \"MXN\"\n  },\n  \"blockchain\": \"ETH-SEPOLIA\",\n  \"senderType\": \"BUSINESS\",\n  \"recipientType\": \"BUSINESS\",\n  \"paymentMethodType\": \"SPEI\",\n  \"quoteOptions\": {\n    \"isFirstParty\": true\n  },\n  \"transactionVersion\": \"VERSION_2\"\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.circle.com/v1/cpn/quotes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"senderCountry\": \"MX\",\n  \"sourceAmount\": {\n    \"amount\": \"10\",\n    \"currency\": \"USDC\"\n  },\n  \"destinationCountry\": \"MX\",\n  \"destinationAmount\": {\n    \"amount\": \"\",\n    \"currency\": \"MXN\"\n  },\n  \"blockchain\": \"ETH-SEPOLIA\",\n  \"senderType\": \"BUSINESS\",\n  \"recipientType\": \"BUSINESS\",\n  \"paymentMethodType\": \"SPEI\",\n  \"quoteOptions\": {\n    \"isFirstParty\": true\n  },\n  \"transactionVersion\": \"VERSION_2\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.circle.com/v1/cpn/quotes")

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  \"senderCountry\": \"MX\",\n  \"sourceAmount\": {\n    \"amount\": \"10\",\n    \"currency\": \"USDC\"\n  },\n  \"destinationCountry\": \"MX\",\n  \"destinationAmount\": {\n    \"amount\": \"\",\n    \"currency\": \"MXN\"\n  },\n  \"blockchain\": \"ETH-SEPOLIA\",\n  \"senderType\": \"BUSINESS\",\n  \"recipientType\": \"BUSINESS\",\n  \"paymentMethodType\": \"SPEI\",\n  \"quoteOptions\": {\n    \"isFirstParty\": true\n  },\n  \"transactionVersion\": \"VERSION_2\"\n}"

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

{
  "data": [
    {
      "type": "quote",
      "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
      "paymentMethodType": "SPEI",
      "blockchain": "ETH-SEPOLIA",
      "senderCountry": "MX",
      "destinationCountry": "MX",
      "createDate": "2023-01-01T12:04:05Z",
      "quoteExpireDate": "2023-01-01T12:04:05Z",
      "cryptoFundsSettlementExpireDate": "2023-01-01T12:04:05Z",
      "sourceAmount": {
        "amount": "10.000000",
        "currency": "USDC"
      },
      "destinationAmount": {
        "amount": "183.24",
        "currency": "MXN"
      },
      "fiatSettlementTime": {
        "max": "3",
        "min": "1",
        "unit": "DAYS"
      },
      "exchangeRate": {
        "pair": "USDC/MXN",
        "rate": "18.324000"
      },
      "fees": {
        "breakdown": [
          {
            "type": "BFI_TRANSACTION_FEE",
            "amount": {
              "amount": "0.240000",
              "currency": "USDC"
            }
          }
        ],
        "totalAmount": {
          "amount": "0.240000",
          "currency": "USDC"
        }
      },
      "senderType": "BUSINESS",
      "recipientType": "BUSINESS",
      "certificate": {
        "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
        "certPem": "LS0tLS1CRUdJT...",
        "domain": "api.circle.com",
        "jwk": {
          "crv": "P-256",
          "kid": "263521881931753643998528753619816524468853605762",
          "kty": "EC",
          "x": "KnxBe8fb2mL_Ve9-tqjGSkGgE9f0yohMkAvH_InaFtE",
          "y": "D41cVUpiKcey4LJKNFtUtmVHDWRmhjZapPLfryX5b1o"
        }
      },
      "quoteOptions": {
        "isFirstParty": true
      },
      "transactionVersion": "VERSION_2",
      "rawExchangeRate": {
        "pair": "USDC/MXN",
        "rate": "18.778689"
      }
    }
  ]
}

{
  "code": 400,
  "message": "Bad request."
}

{
  "code": 401,
  "message": "Malformed authorization."
}

{
  "code": 3,
  "message": "Forbidden"
}

Authorizations

Authorization

string

header

required

Circle's API Keys are formatted in the following structure "PREFIX:ID:SECRET". All three parts are requred to make a successful request.

Body

application/json

Request body for creating payment quotes with exchange rates and fees

senderCountry

string

required

ISO 3166-1 alpha-2 two-letter country code. The set of countries the Circle Payment Network serves changes as corridors launch; call GET /v1/cpn/configurations/enabledRoutes for the live list.

Example:

"MX"

sourceAmount

object

required

The crypto source amount. This field is an object containing the currency code and the amount. This field is required; however, if your query is based on the destinationAmount, leave the amount field blank and only populate the currency field.

Show child attributes

destinationCountry

string

required

ISO 3166-1 alpha-2 two-letter country code. The set of countries the Circle Payment Network serves changes as corridors launch; call GET /v1/cpn/configurations/enabledRoutes for the live list.

Example:

"MX"

destinationAmount

object

required

The amount of fiat currency to be delivered to the destination. This field is an object containing the currency code and the amount. This field is required; however, if your query is based on the sourceAmount, leave the amount field blank and only populate the currency field.

Show child attributes

blockchain

enum<string>

required

Supported blockchain networks

Available options:

SOL,

MATIC,

ETH,

ARC,

SOL-DEVNET,

MATIC-AMOY,

ETH-SEPOLIA,

ARC-TESTNET

Example:

"ETH-SEPOLIA"

senderType

enum<string>

required

Type of entity sending or receiving the payment

Available options:

BUSINESS,

INDIVIDUAL

Example:

"BUSINESS"

recipientType

enum<string>

required

Type of entity sending or receiving the payment

Available options:

BUSINESS,

INDIVIDUAL

Example:

"BUSINESS"

paymentMethodType

enum<string>

The method used for the payment (e.g., PIX, WIRE, CHATS)

Available options:

AANI,

ACH-BANK-TRANSFER,

BANK-TRANSFER,

CHATS,

CIPS,

FAST,

FEDWIRE,

FPS,

FTS,

IMPS,

INSTAPAY,

NEFT,

NEQUI,

PESONET,

PIX,

RTGS,

SD-ACH,

SEPA,

SPEI,

SPID,

WIRE

Example:

"SPEI"

quoteOptions

object

Additional information for the OFI to provide a more precise quote

Show child attributes

transactionVersion

enum<string>

The version of the transaction. If not provided, defaults to VERSION_1.

Available options:

VERSION_1,

VERSION_2

Example:

"VERSION_2"

Response

Quotes created successfully

data

object[]

required

Array of quotes containing all the necessary information for payments

Show child attributes

API overview

Fiat payouts

Managed Payments

Stablecoin payments

Circle Payments Network

Create a quote

Authorizations

Body

Response