Public Widget API

Use the public widget API when you want to quote rates and create payout intents from a browser integration. All requests must include your public API key.

Required Headers

x-yara-api-key: <public-key>
Content-Type: application/json

Get Rates (with optional developer margin)

GET /api/rates?developer_percentage=<margin>

curl -X GET "https://api.yara.cash/api/rates?developer_percentage=2.5" \
  -H "x-yara-api-key: <public-key>" \
  -H "Content-Type: application/json"

Response

{
    "data": {
        "baseCurrency": "USD",
        "buy": {
            "BTC": 0.000009417294813746639,
            "CAD": 1.2933503947368423,
            "EUR": 0.864300105769232,
            "GBP": 0.689275815789474,
            "NGN": 1655.5529510187498,
            "SOL": 0.005621620732112859,
            "USD": 1.0403749999999998,
            "USDC": 1.0403749999999998,
            "USDT": 1.0403749999999998
        },
        "sell": {
            "BTC": 0.000009440878504122915,
            "CAD": 1.22971875,
            "ETH": 0.0002875704002979286,
            "EUR": 0.8389094999999991,
            "GBP": 0.680626171875,
            "GHS": 11.59275,
            "NGN": 1418.0169869775002,
            "SOL": 0.006098274267290753,
            "USD": 0.975,
            "USDC": 0.975,
            "USDT": 0.975
        },
        "expiresAt": 1762359164
    },
    "message": "success"
}

If developer_percentage is omitted, the standard buy/sell rates are returned.

List Supported Banks

GET /widget/banks

curl -X GET "https://api.yara.cash/widget/banks" \
  -H "x-yara-api-key: <public-key>" \
  -H "Content-Type: application/json"

Response

{
  "data": {
    "banks": [
      {
        "name": "Globus Bank",
        "code": "000027",
        "country": "NG"
      },
      {
        "name": "Access Bank",
        "code": "044",
        "country": "NG"
      }
    ]
  }
}

Create a Payout Intent

POST /widget

curl -X POST "https://api.yara.cash/widget" \
  -H "x-yara-api-key: <public-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "sender": {},
    "recipient": {
      "firstName": "Test",
      "lastName": "Example",
      "email": "[email protected]",
      "phoneNumber": "+2348030959898",
      "bankAccount": {
        "accountNumber": "80309588897",
        "bankCode": "100004"
      },
      "address": "100 Market Street",
      "city": "Lagos",
      "country": "NG"
    },
    "amount": 1500.5,
    "paymentRemarks": "Monthly salary payment",
    "fromCurrency": "USD",
    "payoutCurrency": "NGN",
    "publicKey": "pk_test_123",
    "developerFee": "2.5",
    "payoutType": "DIRECT_DEPOSIT"
  }'

Response

{
  "data": {
    "id": "9c1d0ff4-819b-4ad0-b13c-570fa8a22c03",
    "ethAddress": "0x69965551E505005915b7cA4c43dB09F4bB000330",
    "btcAddress": "35Lq8sFQ4CYkymeYME3qkZ96JZrqFbSxjj",
    "solAddress": "BbUGfA7dkCsJueCxwLg78r27JnVH5g4xbHky4ANsDHRS",
    "tronAddress": "TXiExibwNM9At4BVGAJruQgcTGZV8bDSDX",
    "depositAmount": 1500.5,
    "depositCurrency": "USD",
    "depositAmountInUSD": 1500.5,
    "fiatPayoutAmount": 400950424.66,
    "payoutCurrency": "NGN",
    "payoutType": "DIRECT_DEPOSIT",
    "source": "WIDGET",
    "status": "DEPOSIT_PENDING",
    "message": ""
  },
  "message": "success"
}

The sender payload is optional—if omitted, the authenticated widget owner is assumed to be the sender.

Track Payout Status

GET /widget?id=<payout-intent-id>

curl -X GET "https://api.yara.cash/widget?id=9c1d0ff4-819b-4ad0-b13c-570fa8a22c03" \
  -H "x-yara-api-key: <public-key>" \
  -H "Content-Type: application/json"

Response

{
  "data": {
    "id": "9c1d0ff4-819b-4ad0-b13c-570fa8a22c03",
    "ethAddress": "0x69965551E505005915b7cA4c43dB09F4bB000330",
    "btcAddress": "35Lq8sFQ4CYkymeYME3qkZ96JZrqFbSxjj",
    "solAddress": "BbUGfA7dkCsJueCxwLg78r27JnVH5g4xbHky4ANsDHRS",
    "tronAddress": "TXiExibwNM9At4BVGAJruQgcTGZV8bDSDX",
    "depositAmount": 1500.5,
    "depositCurrency": "USD",
    "depositAmountInUSD": 1500.5,
    "fiatPayoutAmount": 400950424.66,
    "payoutCurrency": "NGN",
    "payoutType": "DIRECT_DEPOSIT",
    "source": "WIDGET",
    "status": "DEPOSIT_PENDING",
    "message": ""
  },
  "message": "success"
}