Domains

Purchase one or more domains

Purchases one or more domains and registers them immediately. Send {"domain": "..."} for single or {"domains": ["...", "..."]} for bulk (max 10).

If the domain is listed for sale on the Domani marketplace, this endpoint automatically routes to a marketplace purchase instead of a fresh registration. The response includes years: 0 and marketplace_purchase: true to distinguish it from a registration. Marketplace purchases are single-domain only. The buyer pays the full listed price; the seller receives the price minus a platform commission (default 10%).

Bulk purchases process each domain independently - failures don't block other purchases. The response includes results (succeeded), errors (failed), and summary with counts.

Accepts three payment methods:

  1. Card (default): Requires a card on file via POST /api/billing/setup. Charged per domain.
  2. USDC (two-step): First call without payment to get a 402 with payment_options.crypto (wallet address, amount, chains). Send USDC on-chain, then retry with payment_tx and payment_chain in the request body.
  3. x402 USDC (atomic): Include a PAYMENT-SIGNATURE header with a signed USDC payment on Base.

Bulk purchases require a card on file (USDC not supported for multi-domain). If no payment is provided for single domain, returns HTTP 402 with payment instructions.

post/api/domains/buy

Request

  • Base URL: https://domani.run
  • URL: https://domani.run/api/domains/buy
  • Auth: HTTP bearer

Headers

PAYMENT-SIGNATUREstring

Base64-encoded x402 payment payload (USDC on Base). When provided, the domain is paid with USDC instead of a card. x402-compatible clients handle this automatically after receiving a 402 response.

Request body

domainstring

Single domain to purchase (e.g. mysite.com)

domainsstring[]

Array of domains to purchase (max 10, requires card on file)

payment_method'card' | 'usdc' | 'balance'

Payment method: 'card' (default), 'usdc' (x402 - first call returns 402 with payment instructions), or 'balance' (spend marketplace credit).

payment_txstring

Transaction hash of a USDC payment already sent on-chain. Required on the second call of the two-step USDC flow.

payment_chain'base' | 'ethereum'

Chain the USDC payment was sent on (e.g. 'base' or 'ethereum').

yearsinteger

Number of years to register (1-10, default 1). Price is multiplied by years.

max_pricenumber

Ceiling in USD for the total charge. If the real price exceeds it, the request fails with 400 PRICE_ABOVE_MAX and nothing is charged - a safety belt for autonomous agents. Without max_price the ceiling is the price search listed: when only a registrar billing more can take the name, the buy fails the same way. The error's price is the total to accept, with listed_price and renewal_price beside it; confirm them with the user before retrying with that max_price.

refstring

Referral code (optional) - the referrer earns a commission

Example request

{
  "domain": "mysite.com",
  "domains": [
    "mysite.com",
    "mysite.dev"
  ],
  "max_price": 20
}

Response

Domain purchased and registered successfully

OR

Changes

No recorded changes to this operation across all 2 revisions of this API.