Domain & wallet API
Search, register, renew and manage domain names from your own software — a hosting panel, a reseller site or an internal tool. Every purchase is paid from your POS GROVE wallet.
Overview
Base URL: https://update.posgrove.com/api/v1
Postman: domain-wallet-api.postman_collection.json — every endpoint on this page, ready to import (how to import).
- JSON in and out, UTF-8. Every answer has the shape
{ "success": true, "data": { … } }or{ "success": false, "error": "CODE", "message": "…" }. - Prices and the wallet are in US dollars, with 2 decimals.
- Domains bought through the API appear in your account on this website, and the other way round.
Authentication
Create an API key under Account → Developer API and send it as a bearer token:
Authorization: Bearer pgk_your_api_key
A key can use the domain endpoints below and read your wallet. It cannot buy plans, plugins or templates, see your other data or change your password; those need a signed-in session. You can have up to 5 keys and delete any of them at once if it leaks.
A sign-in token from POST /users/login also works on every endpoint here.
Prices and the wallet
- Add money to the wallet on the website (Account → Wallet) by card, bank transfer or USSD.
- Each purchase is priced by our server at the moment you buy — you never send an amount. The wallet is charged once, atomically; if the registrar then fails, the money goes straight back to the wallet.
- If the wallet is short, the call fails with
402 INSUFFICIENT_FUNDSand tells you how much is missing. Nothing is ordered. - Domains with auto-renew on are renewed for 1 year from the wallet up to 30 days before they expire. Keep enough in the wallet; we email the account owner if a renewal can't be paid.
Quick start
KEY=pgk_your_api_key
# 1. Is it free, and how much?
curl -H "Authorization: Bearer $KEY" "https://update.posgrove.com/api/v1/domains/search?query=mybakery&years=1"
# 2. Buy it — paid from the wallet
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"domain":"mybakery.com","years":1,"payWith":"wallet"}' \
https://update.posgrove.com/api/v1/domains/orders
# 3. Point it at your server
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"type":"A","name":"@","content":"203.0.113.10","ttl":600}' \
https://update.posgrove.com/api/v1/domains/DOM-XXXXXXXXXXXX/dnsNode.js
const API = 'https://update.posgrove.com/api/v1';
const headers = { Authorization: `Bearer ${process.env.POSGROVE_API_KEY}`, 'Content-Type': 'application/json' };
async function call(path, opts = {}) {
const res = await fetch(API + path, { headers, ...opts });
const body = await res.json();
if (!body.success) throw Object.assign(new Error(body.message), { code: body.error, status: res.status, details: body.details });
return body.data;
}
const { results } = await call('/domains/search?query=mybakery');
const pick = results.find((r) => r.purchasable);
const bought = await call('/domains/orders', { method: 'POST', body: JSON.stringify({ domain: pick.domain, years: 1, payWith: 'wallet' }) });
console.log(bought.domain.id, 'paid', bought.paid, 'wallet now', bought.wallet.balance);PHP
$ch = curl_init('https://update.posgrove.com/api/v1/domains/orders');
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('POSGROVE_API_KEY'), 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode(['domain' => 'mybakery.com', 'years' => 1, 'payWith' => 'wallet']),
CURLOPT_RETURNTRANSFER => true,
]);
$res = json_decode(curl_exec($ch), true);
if (!$res['success']) { throw new Exception($res['error'] . ': ' . $res['message']); }GET /users/me/wallet
Balance and the latest activity. Query: page, limit (1–100, default 20).
{
"success": true,
"data": {
"wallet": {
"id": "WAL-1A2B3C4D5E6F",
"currency": "USD",
"balance": 42.5,
"status": "active",
"lifetimeFunded": 100,
"lifetimeSpent": 57.5
},
"transactions": [
{
"id": "WTX-…",
"direction": "debit",
"kind": "purchase",
"amount": 14,
"balanceAfter": 42.5,
"currency": "USD",
"item": {
"kind": "domain",
"id": "DORD-…",
"name": "Register mybakery.com (1 year)"
},
"createdAt": "2026-10-04T10:12:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 6,
"totalPages": 1
}
}
}GET /domains/tlds
Extensions on sale and their yearly prices. No key needed.
{
"success": true,
"data": {
"maxYears": 5,
"tlds": [
{
"tld": "com",
"currency": "USD",
"registrationPerYear": 14,
"renewalPerYear": 14
},
{
"tld": "online",
"currency": "USD",
"registrationPerYear": 3,
"renewalPerYear": 35
}
]
}
}First-year promotions can make registration cheaper than renewal — show both prices to your customers.
GET /domains/search?query=&years=
query is a name (mybakery, checked on the popular extensions) or a full domain (mybakery.ng). years 1–5 (default 1).
{
"success": true,
"data": {
"query": "mybakery",
"results": [
{
"domain": "mybakery.com",
"tld": "com",
"available": true,
"premium": false,
"purchasable": true,
"reason": null,
"price": {
"currency": "USD",
"registrationPerYear": 14,
"renewalPerYear": 14,
"total": 14,
"years": 1
}
},
{
"domain": "mybakery.net",
"tld": "net",
"available": false,
"purchasable": false,
"reason": "TAKEN",
"price": null
}
]
}
}reason when not purchasable: TAKEN, PREMIUM (not sold through us), PRICE_UNAVAILABLE.
POST /domains/orders
Body: { "domain": "mybakery.com", "years": 1, "payWith": "wallet" }
With payWith: "wallet" the domain is ordered, paid and registered in one call:
{
"success": true,
"message": "mybakery.com is registered — paid from your wallet",
"data": {
"kind": "domain",
"reference": "WPAY-…",
"paid": 14,
"completed": true,
"order": {
"id": "DORD-…",
"type": "registration",
"domain": "mybakery.com",
"years": 1,
"amount": 14,
"currency": "USD",
"status": "completed"
},
"domain": {
"id": "DOM-…",
"name": "mybakery.com",
"status": "active",
"expiresAt": "2027-10-04T10:12:00.000Z",
"autoRenew": false
},
"wallet": {
"balance": 28.5,
"currency": "USD"
}
}
}Without payWith, an unpaid order (a price quote valid for 60 minutes) is created. Pay it with the next endpoint or on the website.
If completed is false the registrar is still working or needs a manual check; the order appears in your account and is finished or refunded by our team.
POST /domains/orders/:orderId/pay
Pays an unpaid registration or renewal order from the wallet. Fails with 409 QUOTE_EXPIRED once the quote is older than 60 minutes — create a new order.
GET /domains
Your domains.
{
"success": true,
"data": {
"domains": [
{
"id": "DOM-CB4B491C9AB7",
"name": "mybakery.com",
"tld": "com",
"status": "active",
"registeredAt": "2026-10-04T10:12:00.000Z",
"expiresAt": "2027-10-04T10:12:00.000Z",
"autoRenew": true,
"autoRenewAttempt": null,
"whoisPrivacy": true,
"nameservers": [
"ns1.example.net",
"ns2.example.net"
],
"usesDefaultNameservers": true,
"managementLocked": false
}
]
}
}autoRenewAttempt shows the last automatic renewal: { at, ok, error }.
GET /domains/:domainId
One domain with its DNS records (dnsRecords).
POST /domains/:domainId/renew
Body: { "years": 1, "payWith": "wallet" } — renews now and adds the years to the current expiry date. Without payWith you get an unpaid renewal order.
PATCH /domains/:domainId/auto-renew
Body: { "enabled": true }. When on, the domain is renewed for 1 year from the wallet up to 30 days before it expires; we try again daily if the wallet is short.
DNS records
GET /domains/:domainId/dns
POST /domains/:domainId/dns { "type": "A", "name": "@", "content": "203.0.113.10", "ttl": 600 }
PUT /domains/:domainId/dns/:recordId { "type": "CNAME", "name": "www", "content": "mybakery.com" }
DELETE /domains/:domainId/dns/:recordIdTypes: A, AAAA, CNAME, ALIAS, MX, TXT, NS, SRV, CAA. name is the part before the domain (@ for the domain itself). prio for MX and SRV. Records only take effect while the domain uses our nameservers.
Nameservers
GET /domains/:domainId/nameservers
PUT /domains/:domainId/nameservers { "nameservers": ["ns1.host.com", "ns2.host.com"] }
PUT /domains/:domainId/nameservers { "useDefault": true }Changes can take up to 48 hours to spread across the internet.
GET /domains/orders
Your registration and renewal orders, newest first. Filter with ?status=pending_payment|completed|failed|cancelled. GET /domains/orders/:orderId returns one; POST /domains/orders/:orderId/cancel cancels an unpaid one.
Errors
| Status | Code | What to do |
|---|---|---|
| 401 | UNAUTHORIZED | Check the key; it may have been deleted. |
| 402 | INSUFFICIENT_FUNDS | details.shortBy is how much to add to the wallet. |
| 403 | API_KEY_NOT_ALLOWED | That endpoint needs a signed-in session, not a key. |
| 404 | NOT_FOUND | Unknown domain or order, or it belongs to another account. |
| 409 | DOMAIN_NOT_AVAILABLE | Someone else has it. Search again. |
| 409 | QUOTE_EXPIRED | Create a new order for a fresh price. |
| 422 | VALIDATION_ERROR | details names the field. |
| 423 | WALLET_FROZEN | Contact support. |
| 429 | RATE_LIMITED | Slow down; see limits. |
Limits
- Search: 20 requests a minute per IP address (the registrar limits availability checks).
- Wallet payments: 60 per 15 minutes per account.
- Up to 5 years per registration or renewal.