Complete Integration Flow

This guide provides a comprehensive walkthrough of integrating with the Two-Coin platform. Follow these steps to successfully implement cryptocurrency payment functionality in your application.

Understanding Currency IDs

Why Use IDs Instead of Tickers?

Two-Coin uses integer IDs to uniquely identify currencies. This system has several advantages:

• • Unambiguous: Multiple cryptocurrencies might share similar names
• • Immutable: IDs never change, but tickers might be updated
• • Network Support: For crypto, the network is linked to the ID
• • Consistency: All endpoints use the same ID system

Example Currency IDs

USD (US Dollar) = 35
EUR (Euro) = 6
GBP (British Pound) = 49

BTC (Bitcoin) = 15
ETH (Ethereum) = 22
USDC (USD Coin) = 2

Integration Steps

Step 1: Fetch Currency Dictionary

⚠️ Required: Always start here. This data is essential for all subsequent API calls.

Fetch all currencies and cache the mapping:

GET https://api.dev2coin.space/api/dict/currencies

Build two lookup tables:

• id_to_currency - Maps integer ID to currency info (35 → USD)
• ticker_to_id - Maps ticker to ID ("USD" → 35)

Step 2: Fetch Available Countries

GET https://api.dev2coin.space/api/on_ramp/countries

Use this to show your user a list of supported countries for selection.

Step 3: Get Currency Pairs

After user selects a country, fetch available currency pairs:

GET https://api.dev2coin.space/api/on_ramp/currency_pairs?country_code=US

Response example:

[
  {
    "provider_code": "changelly",
    "fiat_currencies": [35, 6, 49],
    "crypto_currencies": [15, 22, 2]
  },
  {
    "provider_code": "kado",
    "fiat_currencies": [35],
    "crypto_currencies": [15, 22]
  }
]

How to interpret: Use your currency lookup to resolve IDs. Display fiat currencies (USD, EUR, GBP) separately from cryptocurrencies (BTC, ETH, USDC) to the user.

Step 4: Fetch Payment Methods

After user selects a fiat currency, get available payment methods:

GET https://api.dev2coin.space/api/on_ramp/payment_methods?fiat_currency=35&country_code=US

Display available payment methods (credit card, bank transfer, etc.) to the user.

Step 5: Get Offers

After user enters amount and selects payment method, fetch offers:

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&payment_method=card

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"
  },
  "kado": {
    "rate": "0.0000251",
    "inverted_rate": "39841.27",
    "fee": "3.99",
    "amount_from": "100.00",
    "amount_expected_to": "0.002410"
  }
}

Display offers to the user with:

• • Cryptocurrency amount they'll receive (amount_expected_to)
• • Fee information (fee)
• • Exchange rate (inverted_rate for display)

Step 6: Validate Wallet Address

Before creating an order, validate the user's wallet address:

POST https://api.dev2coin.space/api/on_ramp/validate-address

{
  "provider_code": "changelly",
  "currency": 15,
  "wallet_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
}

Response:

{"result": true}

Step 7: Create Order

After user selects a provider and wallet is validated:

POST https://api.dev2coin.space/api/on_ramp/orders

{
  "provider_code": "changelly",
  "from_currency": 35,
  "from_amount": "100.00",
  "to_currency": 15,
  "wallet_address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
  "payment_method": "card",
  "country_code": "US",
  "state_code": "CA",
  "external_user_id": "user_12345",
  "external_order_id": "order_67890"
}

Critical Requirements:

• • Use integer currency IDs (35, 15) not tickers
• • external_user_id is REQUIRED
• • external_order_id is REQUIRED
• • state_code is REQUIRED if country has states (check GET /api/dict/countries)
• • Store BOTH the provider's id and your external_order_id

Response includes a redirect_url - redirect your user here to complete payment with the provider.

Step 8: Monitor Order Status

Orders update through webhooks. Implement webhook verification and listen for status changes (pending → processing → complete).

See the Webhooks section for implementation details.

Common Mistakes

Best Practices

• ✓ Cache the currency dictionary on application startup
• ✓ Build lookup tables (ID→Currency and Ticker→ID) for quick resolution
• ✓ Always use integer currency IDs in API requests
• ✓ Store both your external_order_id and provider's order_code
• ✓ Validate wallet addresses before creating orders
• ✓ Implement webhook signature verification
• ✓ Implement webhook failure fallback with polling