The sandbox is a fully isolated test environment — it uses real API logic, real HMAC auth, and pre-seeded inventory, but no real money moves and no real domains transfer. Use it to build and verify your integration before going live.
pk_sandbox_ / sk_sandbox_name.ai — same as livepk_live_ / sk_live_name.ai — same as sandboxApply at /partners/apply — sandbox credentials are issued immediately on approval, no manual review. You receive a Key ID and a Secret shown once at issuance.
Key ID : pk_sandbox_01JXYZABCDEF...
Secret : sk_sandbox_01JXYZABCDEF... ← shown once, store it nowKeep credentials server-side only. Never expose them in client code or NEXT_PUBLIC_ variables.
export NAMEAI_KEY_ID="pk_sandbox_your_key_id"
export NAMEAI_API_SECRET="sk_sandbox_your_secret"
export NAMEAI_BASE_URL="https://name.ai"The sandbox is seeded with a fixed set of test listings. Run a search to see what's available:
import crypto from "crypto";
const KEY_ID = process.env.NAMEAI_KEY_ID;
const SECRET = process.env.NAMEAI_API_SECRET;
const BASE = process.env.NAMEAI_BASE_URL;
const url = `${BASE}/api/partner/v1/domains/search?q=wallet`;
const ts = String(Math.floor(Date.now() / 1000));
const nonce = crypto.randomUUID();
// Build canonical string and sign (see Authentication docs for full helper)
const canonical = ["GET", new URL(url).pathname, "q=wallet", ts, nonce,
crypto.createHash("sha256").update("").digest("hex")].join("\n");
const sig = "v1=" + crypto.createHmac("sha256", SECRET).update(canonical).digest("hex");
const res = await fetch(url, {
headers: {
"X-NameAI-Key-Id": KEY_ID,
"X-NameAI-Timestamp": ts,
"X-NameAI-Nonce": nonce,
"X-NameAI-Signature": sig,
},
});
console.log(await res.json());MoR partners collect payment themselves and notify name.ai via POST /v1/orders. In sandbox, any order notification is accepted — no real payment is verified.
{
"domain": "custodylawyer.com",
"sale_price": 2500,
"currency": "USD",
"buyer_email": "testbuyer@example.com",
"external_payment_ref": "sandbox_test_001",
"idempotency_key": "test-order-001"
}A successful response returns status: "CONFIRMED" and a public_id. The order will appear in the admin partner-orders panel for inspection.
Full flow: MoR order flow →
Non-MoR partners generate a hosted checkout link. In sandbox, the checkout uses Stripe test mode — no real card is charged.
Call POST /api/partner/v1/checkout-session with a domain from search results. Redirect your test buyer to the returned checkout_url.
Stripe test cards
| Card number | Outcome |
|---|---|
| 4242 4242 4242 4242 | Payment succeeds |
| 4000 0000 0000 0002 | Payment declined |
| 4000 0025 0000 3155 | 3D Secure authentication required |
Use any future expiry, any 3-digit CVC, any postal code.
Full flow: Pay with name.ai →
Register a webhook endpoint in your partner console. The sandbox fires real signed webhook events for every order state change — order.confirmed, order.transfer_completed, order.settled, etc.
Use ngrok or a similar tunnel to expose your local server for webhook delivery during development:
# Expose local port 3000 to a public URL
npx ngrok http 3000
# Use the generated URL as your webhook endpoint, e.g.:
# https://abc123.ngrok.io/api/webhooks/nameaiVerify signatures with your webhookSecret (issued alongside your API credentials). See Webhooks & events →
Contact name.ai to have live credentials issued (pk_live_ / sk_live_). Swap your environment variables — the API paths and signing logic are identical.
Your base URL does not change. Sandbox and live are served from the same origin — name.ai — on the same /api/partner/v1/ paths. The credential you sign with is what selects the inventory tier, so going live is a credential swap and nothing else.
Next: Authentication → · Quick start →