Astro Developer API

Give each of your users their own crypto wallet, get notified the moment they receive crypto, sell crypto for naira, swap coins, send to outside wallets and sell gift cards — through one REST API.

Getting access

1. Request a sandbox account. Email [email protected] with your business name and a technical contact. You get a test key (ak_test_…) and the sandbox address.
2. Build against the sandbox. Sandbox wallets are not real and never hold real funds. Use sandbox deposits to send yourself pretend deposits and test your webhook handling end to end.
3. Complete the business check (KYB). Company registration (the CAC number in Nigeria) and an identity check for each director: BVN, ID selfie and address.
4. Go live. Once your business is approved, you receive a live key (ak_live_…) for the live base URL.

Quickstart

Three calls take you from a new user to an address they can be paid on.

# 1. Create a user with your own reference
curl -X POST "$ASTRO_BASE/users" \
  -H "Authorization: Bearer $ASTRO_KEY" -H "Content-Type: application/json" \
  -d '{"reference":"cust_8812","first_name":"Ada","last_name":"Okafor"}'

# 2. Ask for a USDT (TRC20) deposit address
curl -X POST "$ASTRO_BASE/users/ref:cust_8812/addresses" \
  -H "Authorization: Bearer $ASTRO_KEY" -H "Content-Type: application/json" \
  -d '{"currency":"usdt","network":"trc20"}'

# 3. Read it until status is "ready"
curl "$ASTRO_BASE/users/ref:cust_8812/addresses/usdt" \
  -H "Authorization: Bearer $ASTRO_KEY"

const base = process.env.ASTRO_BASE;
const headers = { Authorization: `Bearer ${process.env.ASTRO_KEY}`, "Content-Type": "application/json" };
const call = async (method, path, body) => {
  const res = await fetch(base + path, { method, headers, body: body && JSON.stringify(body) });
  const json = await res.json();
  if (!res.ok) throw new Error(`${json.error.code}: ${json.error.message}`);
  return json.data;
};

await call("POST", "/users", { reference: "cust_8812", first_name: "Ada", last_name: "Okafor" });
await call("POST", "/users/ref:cust_8812/addresses", { currency: "usdt", network: "trc20" });

let addr;
do {
  await new Promise((r) => setTimeout(r, 3000));
  [addr] = await call("GET", "/users/ref:cust_8812/addresses/usdt");
} while (addr?.status !== "ready");
console.log(addr.address);

import os, time, requests

BASE = os.environ["ASTRO_BASE"]
S = requests.Session()
S.headers["Authorization"] = f"Bearer {os.environ['ASTRO_KEY']}"

def call(method, path, body=None):
    r = S.request(method, BASE + path, json=body, timeout=20)
    data = r.json()
    if not r.ok:
        raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
    return data["data"]

call("POST", "/users", {"reference": "cust_8812", "first_name": "Ada", "last_name": "Okafor"})
call("POST", "/users/ref:cust_8812/addresses", {"currency": "usdt", "network": "trc20"})

while True:
    time.sleep(3)
    addr = call("GET", "/users/ref:cust_8812/addresses/usdt")[0]
    if addr["status"] == "ready":
        print(addr["address"]); break

Authentication

Send your key as a bearer token on every request.

Authorization: Bearer ak_live_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Keys are shown once, when they are created. Astro stores only a fingerprint and cannot recover a key; a lost key is revoked and replaced.
• Test keys work only on the sandbox and live keys only on live. A key used in the wrong place returns wrong_environment.
• You can hold several keys (for example, one per server). A revoked key stops working immediately.
• Keys can be restricted to a list of your server IP addresses.
• Keep keys on your servers. Never ship a key in a mobile app, a web page or a public repository.

Requests and responses

Send JSON with Content-Type: application/json (bodies up to 50 KB). Successful responses are wrapped in data. Errors are wrapped in error, with a stable code to program against and a human-readable message.

{ "data": { "id": 401, "reference": "cust_8812" } }

{ "error": { "code": "user_not_found", "message": "User not found." } }

Every response includes X-Astro-Mode: test or live, showing which kind of key made the call. Amounts are always strings, so no precision is lost.

Account

{
  "data": {
    "id": 12,
    "name": "Acme Pay",
    "country": "NG",
    "status": "active",
    "mode": "live",
    "environment": "live",
    "webhook_url": "https://acme.example/astro/webhooks"
  }
}

Users

A user is one of your customers. You identify each user with your own reference, and Astro returns an id. Wherever a path takes :id, you can pass the Astro id or ref:<your reference>.

curl -X POST "$ASTRO_BASE/users" \
  -H "Authorization: Bearer $ASTRO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "cust_8812",
    "first_name": "Ada",
    "last_name": "Okafor",
    "email": "[email protected]"
  }'

{
  "data": {
    "id": 401,
    "reference": "cust_8812",
    "email": "[email protected]",
    "first_name": "Ada",
    "last_name": "Okafor",
    "status": "active",
    "kyc_status": "none",
    "created_at": "2026-11-09T19:02:11.000Z"
  }
}

curl "$ASTRO_BASE/users/ref:cust_8812" \
  -H "Authorization: Bearer $ASTRO_KEY"

{
  "data": {
    "users": [ { "id": 401, "reference": "cust_8812", "status": "active" } ],
    "page": 1,
    "per_page": 50,
    "total": 1
  }
}

Deposit addresses

curl -X POST "$ASTRO_BASE/users/ref:cust_8812/addresses" \
  -H "Authorization: Bearer $ASTRO_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "currency": "usdt", "network": "trc20" }'

{
  "data": {
    "id": "a1b2c3",
    "currency": "usdt",
    "network": "trc20",
    "address": null,
    "destination_tag": null,
    "status": "pending"
  }
}

{
  "data": [
    {
      "id": "a1b2c3",
      "currency": "usdt",
      "network": "trc20",
      "address": "TQ5x…9vKp",
      "destination_tag": null,
      "status": "ready"
    }
  ]
}

Balances

{
  "data": [
    { "currency": "usdt", "balance": "125.50", "locked": "0.0" },
    { "currency": "btc", "balance": "0.0012", "locked": "0.0" }
  ]
}

Rates

{
  "data": {
    "crypto": [
      {
        "currency": "usdt",
        "name": "Tether",
        "usd_price": 1,
        "networks": ["trc20", "bep20", "erc20"],
        "sell_ngn": [
          { "min_usd": 1, "max_usd": null, "ngn_per_usd": 1360 }
        ]
      }
    ],
    "giftcards": [
      {
        "entry_id": 214,
        "card": "Steam",
        "uid": "steam",
        "range": "$50–$100",
        "description": "USA, physical",
        "ngn_per_usd": 1000,
        "ghs_per_usd": null
      }
    ],
    "as_of": "2026-11-09T19:05:00.000Z"
  }
}

Sell to naira

Sell a user's crypto for naira at Astro's rate. The naira goes to your Astro naira balance; you then pay your user in your own app. Naira only. There is no fee: the price is the sell_ngn rate.

{
  "data": {
    "id": 5012,
    "type": "sell",
    "status": "quoted",
    "reference": null,
    "user": { "id": 401, "reference": "cust_8812" },
    "from": { "currency": "usdt", "amount": "10" },
    "to": { "currency": "ngn", "amount": "13600" },
    "fee": "0",
    "rate": { "ngn_per_usd": 1360, "usd_value": "10.00" },
    "expires_at": "2026-11-09T19:20:30.000Z"
  }
}

Swaps

Swap one coin for another inside the user's wallet. Astro's fee is 0.5% of the amount, taken in the coin being swapped. The smallest swap is $1 worth.

{
  "data": {
    "id": 5013,
    "type": "swap",
    "status": "completed",
    "reference": "swap_77",
    "from": { "currency": "btc", "amount": "0.005" },
    "to": { "currency": "usdt", "amount": "372.28" },
    "fee": "0.000025",
    "fee_currency": "btc",
    "price": "74830.5"
  }
}

Withdrawals

Send crypto from a user's wallet to an outside address. Astro charges only the network fee, which comes from the user's balance on top of the amount.

{
  "data": {
    "id": 5014,
    "type": "withdraw",
    "status": "processing",
    "reference": "wd_3391",
    "from": { "currency": "usdt", "amount": "5" },
    "to": { "currency": "usdt", "amount": "5" },
    "network": "trc20",
    "address": "TJCn…sxMW",
    "memo": null,
    "network_fee": "1",
    "txid": null
  }
}

Gift cards

Submit a user's gift card for Astro to review. Approved cards are paid in naira to your Astro naira balance at the card's rate on GET /rates, fixed when you submit.

{
  "data": {
    "id": 5015,
    "type": "giftcard",
    "status": "processing",
    "reference": "gc_120",
    "from": { "currency": "usd", "amount": "100" },
    "to": { "currency": "ngn", "amount": "100000", "amount_is_estimate": true },
    "card": "Steam",
    "card_range": "$50–$100",
    "ngn_per_usd": 1000
  }
}

Trades and balance

{ "data": { "currency": "ngn", "balance": "13600.00" } }

Webhooks

Astro sends events as POST requests with a JSON body to an https URL on a public address. Respond with any 2xx within 10 seconds. Redirects are not followed.

POST /astro/webhooks
Content-Type: application/json
X-Astro-Event: deposit.received
X-Astro-Signature: t=1794250000,v1=5f2c…

{
  "id": "evt_9031",
  "created_at": "2026-11-09T19:10:42.000Z",
  "event": "deposit.received",
  "data": {
    "user": { "id": 401, "reference": "cust_8812" },
    "deposit": {
      "id": "dep_77a1",
      "currency": "btc",
      "amount": "0.02",
      "network": "bitcoin",
      "txid": "8f3e…",
      "status": "accepted",
      "fee": "0.0001",
      "fee_percent": 0.5,
      "credited_amount": "0.0199",
      "fee_status": "collected"
    }
  }
}

{ "data": { "queued": true, "event_id": "evt_9032" } }

Verifying signatures

Every event is signed with your webhook secret (whsec_…, shown once when it is created). The X-Astro-Signature header is t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of t + "." + raw body.

• Use the raw request body exactly as received, not re-encoded JSON.
• Compare in constant time.
• Reject signatures older than 5 minutes.

const crypto = require("crypto");

function verifyAstro(secret, rawBody, header, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec || !parts.v1) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  const got = Buffer.from(parts.v1, "hex");
  return got.length === expected.length && crypto.timingSafeEqual(got, expected);
}

// Express: keep the raw body for this route
app.post("/astro/webhooks", express.raw({ type: "application/json" }), (req, res) => {
  const ok = verifyAstro(process.env.ASTRO_WEBHOOK_SECRET, req.body.toString("utf8"),
    req.get("X-Astro-Signature") || "");
  if (!ok) return res.sendStatus(400);
  const event = JSON.parse(req.body);
  // Skip if event.id was already handled, then do the work.
  res.sendStatus(200);
});

import hashlib, hmac, time

def verify_astro(secret: str, raw_body: bytes, header: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    try:
        t = int(parts["t"])
    except (KeyError, ValueError):
        return False
    if abs(time.time() - t) > tolerance or "v1" not in parts:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

function verify_astro(string $secret, string $rawBody, string $header, int $tolerance = 300): bool {
    $parts = [];
    foreach (explode(",", $header) as $p) {
        [$k, $v] = array_pad(explode("=", $p, 2), 2, null);
        $parts[trim($k)] = trim((string) $v);
    }
    $t = (int) ($parts["t"] ?? 0);
    if (!$t || abs(time() - $t) > $tolerance || empty($parts["v1"])) return false;
    $expected = hash_hmac("sha256", $t . "." . $rawBody, $secret);
    return hash_equals($expected, $parts["v1"]);
}

// $rawBody = file_get_contents("php://input");

Sandbox deposits

On the sandbox, every user's wallet is pretend. Addresses look like SANDBOX-USDT-TRC20-… and cannot receive real crypto. Never send real funds to them. To test your deposit handling, send the user a pretend deposit: the balance goes up and you receive a signed deposit.received webhook, exactly as on live.

curl -X POST "$ASTRO_BASE/users/ref:cust_8812/sandbox/deposits" \
  -H "Authorization: Bearer $ASTRO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"currency":"usdt","network":"trc20","amount":"25.5"}'

{
  "data": {
    "id": "sbxdep_cba44de2dfe1909c",
    "currency": "usdt",
    "amount": "25.5",
    "network": "trc20",
    "txid": "sandbox-9f2c…",
    "status": "accepted",
    "fee": "0",
    "fee_percent": 0,
    "credited_amount": "25.5",
    "fee_status": "none",
    "address": "SANDBOX-USDT-TRC20-6c46c20e1812a6ed7dfb"
  }
}

Fees

The sandbox applies the same fees, so you can test your accounting. Sandbox network fees are made up.

Error codes

Limits

Coming next

The following are planned and not available yet. This page will be updated as each one is released.