ڈویلپر گائیڈز انگریزی میں ہیں۔

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_FUNDS and 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/dns

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

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/:recordId

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

StatusCodeWhat to do
401UNAUTHORIZEDCheck the key; it may have been deleted.
402INSUFFICIENT_FUNDSdetails.shortBy is how much to add to the wallet.
403API_KEY_NOT_ALLOWEDThat endpoint needs a signed-in session, not a key.
404NOT_FOUNDUnknown domain or order, or it belongs to another account.
409DOMAIN_NOT_AVAILABLESomeone else has it. Search again.
409QUOTE_EXPIREDCreate a new order for a fresh price.
422VALIDATION_ERRORdetails names the field.
423WALLET_FROZENContact support.
429RATE_LIMITEDSlow 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.