Developer Documentation

Appropriate usage of the API

To keep the service running seamlessly for everyone, please do not hammer the servers with unintended calls. The send method already returns your balance after the transaction, so there is no reason to call balance right after it. Cache data such as your balance and user hashes, and refresh it every 5 minutes or so with a cron job — never on every public page view.

Every API key belongs to one faucet, and payouts are made from that faucet's own wallet — top it up first from Faucet Owner → Manage → Funds Management.

Send an HTTP POST request with the required parameters (such as api_key). The request body may be multipart/form-data, application/x-www-form-urlencoded or application/json. Every response is JSON containing a status and message — 200 means success.

Get balance of the faucet (balance, getbalance)

Request URLs

• POST https://aoywallet.com/api/v1/balance
• POST https://aoywallet.com/api/v1/getbalance

Parameters

Return values

Example response

{
  "status": 200,
  "message": "OK",
  "currency": "BTC",
  "balance": "100000000",
  "balance_bitcoin": "1"
}

Get list of supported currencies (currencies)

Request URL

• POST https://aoywallet.com/api/v1/currencies

Parameters

Return values

Example response

{
  "status": 200,
  "message": "OK",
  "currencies": ["BTC","ETH","USDT","BNB","SOL","NEAR","XRP","USDC","DOGE","ADA","TRX","ZER","LTC","BCH","XLM","SHIB","XMR","POL","PEPE","TRUMP","BONK","FLOKI","DASH","DGB","GRAM","XAUT","ALT"],
  "currencies_names": [
    { "name": "Bitcoin", "acronym": "BTC" },
    { "name": "Ethereum", "acronym": "ETH" },
    { "name": "Tether", "acronym": "USDT" },
    { "name": "Binance Coin", "acronym": "BNB" },
    { "name": "Solana", "acronym": "SOL" },
    { "name": "NEAR Protocol", "acronym": "NEAR" },
    { "name": "Ripple", "acronym": "XRP" },
    { "name": "USD Coin", "acronym": "USDC" },
    { "name": "Dogecoin", "acronym": "DOGE" },
    { "name": "Cardano", "acronym": "ADA" },
    { "name": "TRON", "acronym": "TRX" },
    { "name": "Zero", "acronym": "ZER" },
    { "name": "Litecoin", "acronym": "LTC" },
    { "name": "Bitcoin Cash", "acronym": "BCH" },
    { "name": "Stellar", "acronym": "XLM" },
    { "name": "Shiba Inu", "acronym": "SHIB" },
    { "name": "Monero", "acronym": "XMR" },
    { "name": "Polygon", "acronym": "POL" },
    { "name": "Pepe", "acronym": "PEPE" },
    { "name": "Official Trump", "acronym": "TRUMP" },
    { "name": "Bonk", "acronym": "BONK" },
    { "name": "Floki", "acronym": "FLOKI" },
    { "name": "Dash", "acronym": "DASH" },
    { "name": "DigiByte", "acronym": "DGB" },
    { "name": "Gram", "acronym": "GRAM" },
    { "name": "Tether Gold", "acronym": "XAUT" },
    { "name": "AoyWallet Lottery Token", "acronym": "ALT" }
  ]
}

Check if an address belongs to a user (checkaddress)

Request URL

• POST https://aoywallet.com/api/v1/checkaddress

Parameters

Return values

Example response

{
  "status": 200,
  "message": "OK",
  "payout_user_hash": "b8446e7a814d677f5e381f2e05206bf0cee6d063"
}

{
  "status": 456,
  "message": "The address does not belong to any user."
}

Send a payment (send)

Request URL

• POST https://aoywallet.com/api/v1/send

Parameters

Return values

Example response

{
  "status": 200,
  "message": "OK",
  "rate_limit_remaining": null,
  "currency": "BTC",
  "balance": "8673047351",
  "balance_bitcoin": "86.73047351",
  "payout_id": "2af11f6f-9ca8-4c3e-b6af-0a649b011006",
  "payout_user_hash": "c448e31098a8dfb48248f7e2374e77674bb90925"
}

Recent payouts (payouts)

Request URL

• POST https://aoywallet.com/api/v1/payouts

Parameters

Example response

{
  "status": 200,
  "message": "OK",
  "rewards": [
    { "to": "username", "amount": 10451, "date": "14-06-26 03:11:59 GMT" },
    { "to": "username", "amount": 151, "date": "10-06-26 03:11:59 GMT" }
  ]
}

Faucet list (faucetlist)

Request URL

• POST https://aoywallet.com/api/v1/listv1/faucetlist

Parameters

Return values

Example response

{
  "status": 200,
  "message": "OK",
  "list_data": {
    "normal": {
      "BTC": [
        {
          "id": "…",
          "name": "My Faucet",
          "url": "https://myfaucet.example",
          "owner_name": "satoshi",
          "currency": "BTC",
          "timer_in_minutes": "60",
          "reward": "10",
          "is_enabled": "1",
          "balance": "0.10000000",
          "health": "100"
        }
      ]
    }
  }
}

Error codes

1. The checkout form

Drop a form on your site that sends a POST to https://aoywallet.com/merchant/webscr. Nothing to sign and no API key involved — the buyer authenticates themselves when they approve the payment on our side. Any enabled AoyWallet ticker works for the two currency fields — all 27 of them, listed under Supported currencies.

A complete form

<form action="https://aoywallet.com/merchant/webscr" method="post">
  <input type="hidden" name="merchant_username" value="aoyshop">
  <input type="hidden" name="item_description" value="Premium VPN — 1 month">
  <input type="hidden" name="amount1" value="25">
  <input type="hidden" name="currency1" value="USDT">
  <input type="hidden" name="currency2" value="">
  <input type="hidden" name="custom" value="inv-88031">
  <input type="hidden" name="callback_url" value="https://yourstore.example/ipn">
  <input type="hidden" name="success_url" value="https://yourstore.example/thanks">
  <input type="hidden" name="cancel_url" value="https://yourstore.example/cart">
  <button type="submit">Pay with AoyWallet</button>
</form>

Prices in a different coin are converted at the live rate the moment the buyer confirms — if they pay in LTC for a USDT-priced item, the LTC amount is computed right then, never earlier.

2. Getting notified (IPN)

If the form carried a callback_url, we POST a single field named token to it once the buyer has paid. The token on its own proves nothing — anyone can POST to your endpoint — so the required next step is asking us whether it is real:

GET https://aoywallet.com/merchant/get-payment/<token>

A genuine, completed payment answers with "valid": true plus the details you should cross-check on your side — that the username is yours, and that the price and currency match what you were selling:

{
  "valid": true,
  "transaction_id": "b7a91c04e2d85f6a3c10de99f42b7d1583aa20c6",
  "merchant_username": "aoyshop",
  "amount1": "25.00000000",
  "currency1": "USDT",
  "amount2": "0.21734500",
  "currency2": "LTC",
  "fee2": "0.00108672",
  "net2": "0.21625828",
  "custom": "inv-88031"
}

A minimal PHP handler

<?php
// AoyWallet merchant IPN endpoint.
$token = $_POST['token'] ?? '';

// The POST alone proves nothing — anyone can hit this URL.
// Ask AoyWallet whether the token is real before trusting it.
$info = json_decode(
  file_get_contents('https://aoywallet.com/merchant/get-payment/' . urlencode($token)),
  true
);

if (!$info || $info['valid'] !== true) {
  http_response_code(200);           // acknowledge so we stop retrying
  exit('not a real payment');
}
if ($info['merchant_username'] !== 'aoyshop') {
  exit('payment belongs to another shop');
}
if ($info['currency1'] !== 'USDT' || $info['amount1'] !== '25.00000000') {
  exit('price mismatch — do not ship');
}

// All good: mark order $info['custom'] as paid in your database here.
http_response_code(200);
echo 'OK';

3. Delivery retries

Answer the IPN with HTTP 200 and we consider it delivered. Any other outcome — timeout, 4xx, 5xx, redirect — puts the notification back in the queue on this schedule:

Seven tries and we stop — but nothing is lost: your server can query get-payment with a stored token at any time and reconcile missed orders.