Developer Documentation

Developer API & Checkout Integration

Everything you need to build on AoyWallet: the payout REST API for faucets, and the hosted merchant checkout for selling with crypto.

Payout REST API Merchant Checkout

Part 1 — Faucet Payout REST API

Pay your faucet's users straight into their AoyWallet balance automatically.

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 updated wallet 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 balance — 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.

Endpoint Base URL: https://aoywallet.com/api/v1

Supported Payout Currencies

These tickers can be used in the currency parameter. The list updates dynamically from our active currency registry.

BTC

Bitcoin

ETH

Ethereum

USDT

Tether

BNB

Binance Coin

SOL

Solana

NEAR

NEAR Protocol

ATOM

Cosmos Token

LUNA

Terra

QTUM

Qtum

RVN

Ravencoin

SUI

Sui

VET

Vechain

WAVES

Waves

XNO

Nano

XRP

Ripple

XTZ

TEZOS

USDC

USD Coin

DOGE

Dogecoin

ADA

Cardano

TRX

TRON

ZER

Zero

LTC

Litecoin

BCH

Bitcoin Cash

XLM

Stellar

SHIB

Shiba Inu

XMR

Monero

POL

Polygon

PEPE

Pepe

TRUMP

Official Trump

BONK

Bonk

FLOKI

Floki

DASH

Dash

DGB

DigiByte

GRAM

Gram

XAUT

Tether Gold

ALT

AoyWallet Lottery Token

Get balance of the faucet (balance, getbalance)

POST

https://aoywallet.com/api/v1/balance

https://aoywallet.com/api/v1/getbalance

Parameters

Field	Required	Description
api_key	Required	Your faucet's API key — Faucet Owner → Manage → Faucet Information
currency	Optional	Defaults to "BTC". Any supported ticker — see Supported currencies below

Response Fields

Field	Description
currency	The currency you set while making the request
balance	The faucet wallet balance in 10^8 units ("satoshis")
balance_bitcoin	The faucet wallet balance in regular coin value

Example Response

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

Get list of supported currencies (currencies)

POST

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

Parameters

Field	Required	Description
api_key	Required	Your faucet's API key — Faucet Owner → Manage → Faucet Information

Response Fields

Field	Description
currencies	A JSON array with currency acronyms
currencies_names	A JSON array with names and acronyms

Example Response

{
  "status": 200,
  "message": "OK",
  "currencies": ["BTC","ETH","USDT","BNB","SOL","NEAR","ATOM","LUNA","QTUM","RVN","SUI","VET","WAVES","XNO","XRP","XTZ","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": "Cosmos Token", "acronym": "ATOM" },
    { "name": "Terra", "acronym": "LUNA" },
    { "name": "Qtum", "acronym": "QTUM" },
    { "name": "Ravencoin", "acronym": "RVN" },
    { "name": "Sui", "acronym": "SUI" },
    { "name": "Vechain", "acronym": "VET" },
    { "name": "Waves", "acronym": "WAVES" },
    { "name": "Nano", "acronym": "XNO" },
    { "name": "Ripple", "acronym": "XRP" },
    { "name": "TEZOS", "acronym": "XTZ" },
    { "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)

POST

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

Parameters

Field	Required	Description
api_key	Required	Your faucet's API key — Faucet Owner → Manage → Faucet Information
address	Required	A username, an account email, or a payment address (1234567890@aoywallet.com)

Response Fields

Field	Description
payout_user_hash	A stable hash identifying the user. Use it to recognise the same user across requests

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)

POST

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

Parameters

Field	Required	Description
api_key	Required	Your faucet's API key — Faucet Owner → Manage → Faucet Information
amount	Required	Amount in 10^8 units ("satoshis"). For example: 50
to	Required	Who to pay: their AoyWallet username, their email, or their payment address (1234567890@aoywallet.com — a members-only address that receives money and nothing else)
currency	Optional	Defaults to "BTC". Any supported ticker — see Supported currencies below
referral	Optional	Set to "true" to mark this as a referral payment
unique_id	Optional	Optional idempotency key (A–Z, a–z, 0–9, "-", "_", max 64). Retrying a request with the same unique_id never pays twice — strongly recommended
ip_address	Optional	The claiming user’s IP address as seen by your site (IPv4 or IPv6). Enables the IP blacklist and the IP-based anti-fraud rules; those rules are skipped when omitted. The IP is stored with the payout record for your faucet’s own anti-fraud accounting

Response Fields

Field	Description
currency	The currency you paid in
balance	The remaining faucet wallet balance in 10^8 units
balance_bitcoin	The remaining faucet wallet balance in coin value
payout_id	A unique identifier for this transaction
payout_user_hash	Hash of the user you paid

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)

POST

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

Parameters

Field	Required	Description
api_key	Required	Your faucet's API key — Faucet Owner → Manage → Faucet Information
currency	Optional	Defaults to "BTC". Any supported ticker — see Supported currencies below
count	Optional	Number of transactions to fetch, between 0 and 100

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)

POST

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

Parameters

Field	Required	Description
api_key	Required	Your faucet's API key — Faucet Owner → Manage → Faucet Information

Response Fields

Field	Description
list_data	A JSON object with the registered faucets, grouped per currency under "normal"

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 Status Codes & Meaning

Status	Meaning / Description
200	Success.
402	You don't have sufficient funds for this transaction.
403	Invalid API Key used. Please login to your account and use a valid API Key.
405	You are sending an invalid amount of payment to the user.
410	Invalid currency provided.
450	Rate limit reached — the payout breaks a limit you set under Manage → Rate-Limits or Anti-Fraud.
456	The address does not belong to any user.
457	Your IP address is not whitelisted for this faucet (Manage → IP Whitelisting).
458	The recipient is blacklisted on this faucet (Manage → IP Whitelisting → Recipient Blacklist).
459	The payout was declined by the faucet's anti-fraud rules (Manage → Anti-Fraud).

Part 2 — Merchant Gateway

Hosted Merchant Checkout

Accept crypto payments from your website. You create an HTML form that POSTs to our checkout page; the buyer pays with their AoyWallet balance or on-chain crypto, and we notify your server (IPN) the moment it clears.

1. Creating the payment button

Build a standard HTML <form> that posts to https://aoywallet.com/merchant/webscr:

Field	Required	What it does	Example
merchant_username	Required	The AoyWallet account that gets paid — must hold an approved merchant status	aoyshop
item_description	Required	What the buyer sees on the checkout page	Premium VPN — 1 month
amount1	Required	The price, in plain coin units of currency1	25
currency1	Required	Ticker the price is quoted in	USDT
currency2	Optional	Lock the payment to one specific coin. Leave blank and the buyer picks any coin you accept	LTC
custom	Optional	Free-form reference echoed back to your server — an order number, a user id, anything	inv-88031
callback_url	Optional	Your server endpoint for the payment notification (IPN). Must be a public https/http URL	https://yourstore.example/ipn
success_url	Optional	Where the buyer’s browser goes after a completed payment	https://yourstore.example/thanks
cancel_url	Optional	Where the buyer’s browser goes if they back out	https://yourstore.example/cart

A Complete Form Sample

<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>

1b. Taking coin on-chain (optional)

By default a buyer can only pay from their AoyWallet balance. Switch On-chain payments on in your Merchant Dashboard and the checkout offers a second tab: the buyer picks a network, gets a temporary address and an exact amount, and sends it from any wallet.

The fee: 0.5% of the amount that arrives, taken out of what you are credited — the buyer sends exactly what they were quoted: 100 USDT → 99.5 USDT. Internal balance payments stay 0% free.
The clock: The address and the rate are held for one hour. After that the quote is void and the address goes back into the pool.
One transfer: The order settles on the first transfer that covers the quote. Underpayments are never treated as payment; an overpayment settles the order and credits what arrived, less the fee.
Confirmations: An on-chain payment settles when the network confirms it. Your IPN fires at that moment, exactly as for a balance payment.

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 order details:

{
  "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"
}

transaction_id	Unique id of this payment — store it to deduplicate callbacks
merchant_username	Must be YOUR username, or the callback is not about your shop
amount1 / currency1	The original asking price — compare against what the order actually costs
amount2 / currency2	What the buyer really paid, in the coin they picked — GROSS, before any settlement fee
fee2	Settlement fee deducted, in currency2. "0" on a balance payment, which is free
net2	What actually reached your balance: amount2 minus fee2. Book THIS as revenue
custom	Your own reference from the form, echoed back untouched

A Minimal PHP IPN Handler Sample

<?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 retry queue on this schedule:

Attempt 1	the moment the buyer pays
Attempt 2	5 minutes later
Attempt 3	15 minutes later
Attempt 4	30 minutes later
Attempt 5	1 hour later
Attempt 6	2 hours later
Attempt 7	4 hours later

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.