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/offers?source_currency=USD&source_amount=100&target_currency=BTC

Query Parameters

Example Response

{
  "offers": [
    {
      "offer_id": "ofr_123456",
      "provider_id": "provider_a",
      "source_amount": 100,
      "source_currency": "USD",
      "target_amount": 0.003,
      "target_currency": "BTC",
      "rate": 33333.33,
      "payment_method_id": "pm_credit_card",
      "fees": {
        "processing_fee": 2.5,
        "network_fee": 1
      },
      "total_fee_amount": 3.5,
      "expires_at": 1673456400
    },
    {
      "offer_id": "ofr_123457",
      "provider_id": "provider_b",
      "source_amount": 100,
      "source_currency": "USD",
      "target_amount": 0.00298,
      "target_currency": "BTC",
      "rate": 33557.05,
      "payment_method_id": "pm_bank_transfer",
      "fees": {
        "processing_fee": 1.0,
        "network_fee": 1
      },
      "total_fee_amount": 2.0,
      "expires_at": 1673456400
    },
    // More offers...
  ]
}

Offer Properties

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 a list of offers, you can:

1. 1. Display the offers to the user, sorted by target amount (highest to lowest) or by provider preference
2. 2. Allow the user to select an offer
3. 3. Use the selected offer's offer_id to create an order

POST https://api.dev2coin.space/orders
{
  "offer_id": "ofr_123456",
  "target_address": "bc1q...",
  "customer_email": "[email protected]",
  "redirect_url": "https://your-site.com/order-complete"
}

Filtering Offers

You can filter offers by payment method to show only offers that use a specific payment method:

GET /offers?source_currency=USD&source_amount=100&target_currency=BTC&payment_method_id=pm_credit_card

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