Guide

Comprehensive Guide: Requesting a Quote

This guide will walk you through the process of requesting a quote using the bindpay API. This is typically the first step in processing a payment transaction.

What is a Quote Request?

A quote request allows you to get pricing information for a potential transaction before actually executing it. This is useful for:

1. Showing the user how much they'll pay before they commit

2. Understanding the current exchange rates and fees

3. Preparing the necessary transaction details

Prerequisites

Before you start, make sure you have:

1. A bindpay API key

2. The details of the transaction you want to quote

If you don't have an API key yet, you can register for one here.

Step-by-Step Guide

1. Prepare Your Request

You'll need to gather the following information:

• fromChain: The ID of the blockchain network the payment is coming from.

  • Refer to our Active Chains list to find the correct chainID.

  • Example: "1" for Ethereum Mainnet, "8453" for Base

• fromToken: The address of the token being used for payment.

  • This is a unique address for each token on each network.

  • Example: For ETH on Ethereum, you can use "ETH" or the zero address "0x0000000000000000000000000000000000000000"

• fromAddress: The wallet address of the person making the payment.

  • This should be a valid address on the specified chain.

  • Example: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"

• usdAmount: The amount of the transaction in US Dollars.

  • This should be a string representing the dollar amount.

  • Example: "100" for a $100 transaction

2. Make the API Call

Now that you have all the necessary information, you can make the API call. Here's how to do it using cURL:

cURL

curl -X POST "https://api.bindpay.xyz/v1/quote" \
     -H "Content-Type: application/json" \
     -H "x-api-key: your_api_key_here" \
     -d '{
       "fromChain": "1",
       "fromToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
       "fromAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
       "usdAmount": 1
     }'

Python

import requests

url = "https://api.bindpay.xyz/v1/quote"
headers = {
    "Content-Type": "application/json",
    "x-api-key": "your_api_key_here"
}
data = {
    "fromChain": "1",
    "fromToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "fromAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "usdAmount": 100
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

Rust

use reqwest::Client;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let url = "https://api.bindpay.xyz/v1/quote";
    let client = Client::new();

    let response = client.post(url)
        .header("Content-Type", "application/json")
        .header("x-api-key", "your_api_key_here")
        .json(&json!({
            "fromChain": "1",
            "fromToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
            "fromAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
            "usdAmount": 100
        }))
        .send()
        .await?;

    println!("{}", response.text().await?);
    Ok(())
}

Ruby

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://api.bindpay.xyz/v1/quote')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri, 
    'Content-Type' => 'application/json',
    'x-api-key' => 'your_api_key_here'
)
request.body = {
    fromChain: '1',
    fromToken: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
    fromAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
    usdAmount: 100
}.to_json

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

JavaScript

const axios = require('axios');

const url = 'https://api.bindpay.xyz/v1/quote';
const headers = {
    'Content-Type': 'application/json',
    'x-api-key': 'your_api_key_here'
};
const data = {
    fromChain: '1',
    fromToken: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
    fromAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
    usdAmount: 100
};

axios.post(url, data, { headers })
    .then(response => console.log(response.data))
    .catch(error => console.error('Error:', error));

TypeScript

import axios from 'axios';

const url = 'https://api.bindpay.xyz/v1/quote';
const headers = {
    'Content-Type': 'application/json',
    'x-api-key': 'your_api_key_here'
};
const data = {
    fromChain: '1',
    fromToken: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
    fromAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
    usdAmount: 100
};

axios.post(url, data, { headers })
    .then(response => console.log(response.data))
    .catch(error => console.error('Error:', error));

Replace your_api_key_here with your actual API key.

3. Understand the Response

The API will respond with a JSON object containing the quote details. Here's an example of what you might receive:

{
  "message": "Quote requested",
  "transactionId": "67f40266796881d339a60c79",
  "quote": {
    "provider": "Relay",
    "providerRequestId": "0x4ad4c299291d15d4371f4ebb4caff9585febf004d09ad436d1bc5b63938995e8",
    "providerLogoURI": "https://api.bindpay.xyz/static/images/providers/relay.svg",
    "fromToken": {
      "address": "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
      "decimals": 6,
      "chainId": 42161,
      "logoURI": "https://ethereum-optimism.github.io/data/USDC/logo.png",
      "symbol": "USDC",
      "price": 0.9999549927725895
    },
    "toToken": {
      "address": "0x0b2c639c533813f4aa9d7837caf62653d097ff85",
      "decimals": 6,
      "chainId": 10,
      "logoURI": "https://ethereum-optimism.github.io/data/USDC/logo.png",
      "symbol": "USDC",
      "price": 0.9999549774887444
    },
    "fromAmount": "11998073",
    "toAmount": "11994000",
    "fromAddress": "0x4cCBA2311f7F1C4802835b5b9eA450D17a238378",
    "toAddress": "0x7a020cbdDe05c6DA1B4Bf57C4678eBC28659E598",
    "estimatedDuration": 4,
    "fees": {
      "bridge": 0.004073,
      "gas": "0.000927",
      "integrator": "0.000000"
    }
  },
  "approvalTxParams": {
    "from": "0x4cCBA2311f7F1C4802835b5b9eA450D17a238378",
    "to": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
    "gas": "0x16a63",
    "data": "0x095ea7b3000000000000000000000000af88d065e77c8cc2239327c5edb3a432268e58310000000000000000000000000000000000000000000000000000000000b71379",
    "value": "0x0",
    "nonce": 0
  },
  "transactionRequest": {
    "from": "0x4cCBA2311f7F1C4802835b5b9eA450D17a238378",
    "to": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
    "data": "0xa9059cbb000000000000000000000000f70da97812cb96acdf810712aa562db8dfa3dbef0000000000000000000000000000000000000000000000000000000000b713794ad4c299291d15d4371f4ebb4caff9585febf004d09ad436d1bc5b63938995e8",
    "value": "0",
    "chainId": 42161,
    "requestId": "0x4ad4c299291d15d4371f4ebb4caff9585febf004d09ad436d1bc5b63938995e8",
    "maxFeePerGas": "0x1a2b18c",
    "maxPriorityFeePerGas": "0x0"
  }
}

✅ Quote Summary

• Message: "Quote requested" — this confirms that a quote for the transaction has been successfully generated.

• Transaction ID: 67f40266796881d339a60c79 — a unique ID you can use to track or reference this specific quote.

🔄 Swap/Bridge Details

• Provider: Relay — this is the service (bridge or router) that will handle the cross-chain transfer.

• Provider Request ID: A unique ID used by Relay to identify this transaction request.

• Provider Logo: A logo link for display purposes (Relay's logo).

💱 From Token (What you’re sending)

• Symbol: USDC

• Network: Arbitrum (chain ID 42161)

• Token Address: 0xaf88d065e77c8cc2239327c5edb3a432268e5831

• Decimals: 6 (USDC typically has 6 decimals)

• Price: About $0.99995 — so, just slightly below 1 USD per token.

• From Amount: 11.998073 USDC (that’s 11998073 in micro-units, due to 6 decimals)

• From Address: The wallet sending the tokens: 0x4cCBA2311f7F1C4802835b5b9eA450D17a238378

🎯 To Token (What you’re receiving)

• Symbol: USDC

• Network: Optimism (chain ID 10)

• Token Address: 0x0b2c639c533813f4aa9d7837caf62653d097ff85

• Decimals: 6

• Price: Also just below $1 — $0.99995 per token

• To Amount: 11.994000 USDC (i.e., you’ll receive 11994000 micro-units on Optimism)

• To Address: The destination wallet: 0x7a020cbdDe05c6DA1B4Bf57C4678eBC28659E598

⏱️ Estimated Time

• 4 seconds — That’s the expected duration to complete the bridge/swap.

💸 Fees Breakdown

• Bridge Fee: 0.004073 USDC — what the bridge takes as a cut.

• Gas Cost: Equivalent of 0.000927 USDC — likely covers on-chain execution costs.

• Integrator Fee: 0.000000 — meaning no extra fee is being taken by the platform offering the quote.

✅ Approval Transaction Parameters (approvalTxParams):

• from: The address of the user initiating the transaction.

• to: The address of the contract that needs approval (USDC token contract in this case).

• gas: Estimated gas limit for the approval transaction.

• gasPrice: Gas price for the transaction.

• data: The encoded data for the approval transaction (standard ERC-20 approval format).

• value: The value in wei being sent with the transaction (usually 0 for approval transactions).

• nonce: The transaction count from the from address (to prevent double-spends).

🔄 Transaction Request (transactionRequest):

• to: The address that the transaction is being sent to (could be a smart contract or user address).

• from: The user's address initiating the transaction.

• data: Encoded call data for the transaction (typically contains function selectors and parameters for smart contract calls).

• value: The amount of ETH (in wei) sent with the transaction.

• chainId: The chain ID of the network.

• gasPrice: The gas price for the transaction.

• gasLimit: The maximum gas allowed for this transaction.

Quote Expiry

Quotes from the bindpay API typically have a validity period of 15 seconds. This brief timeframe is intended to guarantee that users are making transactions that reflect the latest market conditions. Here are some important aspects regarding quote expiration:

• Timeliness: Users should frequently request new quotes to ensure they are working with accurate and current data.

• Time Limit: After receiving a quote, users must complete the transaction within 30 seconds to ensure its validity.

To facilitate seamless transactions and achieve the best pricing, it’s advisable to set up an automatic quote refresh system for users who haven't completed their transactions within the 30-second timeframe.

4. Next Steps

Once you have the quote:

1. Display the relevant information to your user.

2. If the user agrees to the quote, you can proceed to execute the transaction using the approval and transaction data.

3. If the user wants to change something, you can request a new quote with updated parameters.

Common Issues and Troubleshooting

• Invalid API Key: Make sure your API key is correct and active.

• Unsupported Chain or Token: Check our documentation for supported chains and tokens.

• Insufficient Balance: Ensure the fromAddress has enough balance for the transaction.

• Rate Limiting: If you're making too many requests, you might hit our rate limits. Space out your requests if this happens.

Best Practices

1. Always validate user input before sending it to the API.

2. Handle API errors gracefully and provide meaningful feedback to your users.

3. Consider implementing retry logic with exponential backoff for failed requests.

4. Keep your API key secure and never expose it in client-side code.

By following this guide, you should be able to successfully request quotes for transactions using the bindpay API. If you encounter any issues or have questions, don't hesitate to reach out to our support team.