Offers

This page describes how to work with offers in the Two-Coin payment system. Offers represent quotes from different cryptocurrency providers that can be used to create orders.

What is an Offer?

An offer is a quote from a provider that includes:

• •
  The source amount (fiat currency amount to pay)
• •
  The target amount (cryptocurrency amount to receive)
• •
  The exchange rate
• •
  Fees associated with the transaction
• •
  The payment method to be used
• •
  An expiration time

Retrieving Offers

To get a list of available offers, make a GET request to the offers endpoint with the following parameters:

GET https://api.dev2coin.space/api/on_ramp/offers?external_user_id=user123&currency_from=35&currency_to=15&amount_from=100.00&country=US&state=CA

Query Parameters

Example Response

Response is an object with provider codes as keys:

{
  "changelly": {
    "rate": "0.000025",
    "inverted_rate": "40000.00",
    "fee": "4.99",
    "amount_from": "100.00",
    "amount_expected_to": "0.002375",
    "payment_methods": [
      { "payment_method_code": "card", "fee": "3.5%" }
    ]
  },
  "kado": {
    "rate": "0.0000251",
    "inverted_rate": "39841.27",
    "fee": "3.99",
    "amount_from": "100.00",
    "amount_expected_to": "0.002410"
  }
}

Offer Fields

Each offer object contains the following fields:

Offer Expiration

Offers are valid for a limited time, typically 2 minutes. The expires_at field indicates when the offer will expire. After this time, the offer cannot be used to create an order, and you'll need to request new offers.

Using Offers

Once you have retrieved offers, you can:

1. 1. Display the offers to the user, sorted by amount_expected_to (highest to lowest)
2. 2. Allow the user to select a provider from the offers
3. 3. Use the selected provider's provider_code to create an order

POST https://api.dev2coin.space/api/on_ramp/orders
{
  "provider_code": "changelly",
  "external_user_id": "user_12345",
  "external_order_id": "order_67890",
  "from_currency": 35,
  "to_currency": 15,
  "from_amount": "100.00",
  "payment_method": "card",
  "country_code": "US",
  "wallet_address": "bc1q..."
}

Filtering Offers

You can filter offers by payment method or specific providers:

GET https://api.dev2coin.space/api/on_ramp/offers?external_user_id=user123&currency_from=35&currency_to=15&amount_from=100&country=US&state=CA&payment_method=card&provider_codes=changelly,kado

Fee Breakdown

Each offer includes a breakdown of the fees associated with the transaction:

• •
  Processing Fee: Fee charged by the payment processor (percentage or fixed amount)
• •
  Network Fee: Fee for the cryptocurrency transaction on the blockchain
• •
  Service Fee: Fee charged by Two-Coin for the service (may be included in some cases)

The total_fee_amount field provides the sum of all fees in the source currency.

Best Practices

• •
  Always fetch fresh offers before creating an order
• •
  Display offers sorted by best value (highest target amount) by default
• •
  Show the full breakdown of fees to the user
• •
  Clearly indicate the offer expiration time to the user
• •
  Implement a refresh mechanism to get updated offers when the current ones expire

Example User Interface

Here's an example of how you might display offers to the user:

Next Steps