REST API · v1

API Reference

Full REST API for DNSDivi testnet. Query domains, check availability, read activity, and submit signed transactions to register, update, renew, or transfer domain names.

Base URL https://divi.cx/testnet/api/v1

All endpoints return JSON. Timestamps are Unix epoch seconds. Domain names are case-insensitive; the API normalizes to lowercase. The testnet zone is testnet.divi.cx — full resolution example: alice.testnet.divi.cx.

Authentication

WalletConnect Authorization

Read-only endpoints (GET) are unauthenticated — no API key required. Write operations (register, update, renew, transfer) require a signed payload from your wallet.

How write auth works: Sign the JSON request body with your Divi private key and include the signature in the X-Divi-Signature header. The server verifies ownership of the domain's registered address before applying changes.

Format: X-Divi-Signature: <base64(secp256k1_sign(sha256(body)))>
The manage UI at /testnet/manage/ handles signing automatically via WalletConnect.

Errors

Error Responses

Errors return a JSON object with a code and message field.

JSON

{
  "code": "domain_not_found",
  "message": "No domain registered with name 'alice'"
}

HTTP Status	Code	Meaning
200	—	Success
400	invalid_request	Bad parameters or malformed body
401	unauthorized	Missing or invalid signature
403	forbidden	Signature valid but wrong owner
404	domain_not_found	Domain doesn't exist
409	domain_taken	Already registered
422	invalid_domain	Name fails validation rules
503	node_unavailable	Upstream node unreachable

Domains

Domain Endpoints

GET /domains List all registered domains

Parameter	Type	Description
owneropt	string	Filter by owner address
sortopt	string	`recent` (sort by most recently registered)

bash

curl https://divi.cx/testnet/api/v1/domains?limit=10

JSON

[
  {
    "name": "onetwothree",
    "owner": "794652685a58335a7141787037333735506468426952464c56417168657446636777",
    "registered_at": 1774361176,
    "expires_at": 1805897176,
    "record_count": 2,
    "status": "active"
  }
]

Try It — Live Request

limit

offset

sort

GET /domains/stats Aggregate domain statistics

No parameters required.

bash

curl https://divi.cx/testnet/api/v1/domains/stats

JSON

{
  "total_domains": 2,
  "active_domains": 2,
  "expired_domains": 0,
  "registrations_24h": 1,
  "registrations_7d": 1
}

Try It — Live Request

GET /domains/:name Get domain details

Parameter	Type	Description
namerequired	path	Domain name without zone suffix (e.g. `alice`)

bash

curl https://divi.cx/testnet/api/v1/domains/alice

JSON

{
  "name": "onetwothree",
  "owner": "794652685a58335a7141787037333735506468426952464c56417168657446636777",
  "records": [
    { "record_type": "A", "value": "1.1.1.1", "ttl": 300 },
    { "record_type": "A", "value": "2.2.2.2", "ttl": 300 }
  ],
  "registered_at": 1774361176,
  "expires_at": 1805897176,
  "status": "active",
  "days_remaining": 364
}

Try It — Live Request

name (path parameter)

GET /domains/:name/available Check availability & price

Parameter	Type	Description
namerequired	path	Domain label to check (without zone)

bash

curl https://divi.cx/testnet/api/v1/domains/mysite/available

JSON

{
  "name": "testname123",
  "available": true,
  "price": 50000000000,
  "price_display": "500 DIVI"
}

Try It — Live Request

name (path parameter)

GET /domains/:name/history Domain event history

Parameter	Type	Description
namerequired	path	Domain label
limitopt	integer	Max events to return (default 20)

bash

curl https://divi.cx/testnet/api/v1/domains/alice/history

JSON

{
  "name": "alice",
  "events": [
    {
      "type": "registered",
      "at": "2026-02-01T12:34:56Z",
      "tx_hash": "a3f2c1d8...",
      "owner": "yEnBd9Vbt..."
    },
    {
      "type": "records_updated",
      "at": "2026-02-15T09:10:22Z",
      "tx_hash": "b7e91a2f...",
      "changes": 2
    }
  ]
}

Try It — Live Request

name (path parameter)

GET /domains/resolve/:name Live DNS resolution

Parameter	Type	Description
namerequired	path	Domain label or FQDN to resolve
typeopt	string	DNS record type filter: `A`, `AAAA`, `CNAME`, `TXT`, `MX`

bash

curl "https://divi.cx/testnet/api/v1/domains/resolve/alice?type=A"

JSON

{
  "name": "onetwothree",
  "record_type": "A",
  "answers": ["1.1.1.1", "2.2.2.2"],
  "ttl": 300,
  "resolved": true
}

Try It — Live Request

name (path parameter)

type (optional)

POST /domains/register Register a new domain

Authorization required. Include X-Divi-Signature header with a secp256k1 signature of the request body from the registering address.

Field	Type	Description
namerequired	string	Domain label (3–63 chars, a-z 0-9 hyphens)
ownerrequired	string	Divi testnet address that will own the domain
payment_txrequired	string	Mainchain transaction ID proving DIVI payment
recordsopt	array	Initial DNS records to set on registration

bash

curl -X POST https://divi.cx/testnet/api/v1/domains/register \
  -H "Content-Type: application/json" \
  -H "X-Divi-Signature: <base64sig>" \
  -d '{
    "name": "mysite",
    "owner": "yEnBd9VbtBRjACMcXWVRLKAGT3hbeq6JbF",
    "payment_tx": "a3f2c1d8e9b047...",
    "records": [
      { "record_type": "A", "value": "203.0.113.10", "ttl": 300 }
    ]
  }'

JSON

{
  "success": true,
  "name": "mysite",
  "fqdn": "mysite.testnet.divi.cx",
  "tx_hash": "c8d3a1e7f042...",
  "expires_at": "2027-03-23T10:00:00Z"
}

Try It — Requires Signed Request

This endpoint requires a valid X-Divi-Signature. Use the Manage UI to register domains interactively with WalletConnect.

Request Body (JSON)

X-Divi-Signature

PUT /domains/:name Update DNS records

Authorization required. Replaces the full record set. Sign the request body with the domain owner's private key.

Field	Type	Description
namerequired	path	Domain label to update
recordsrequired	array	Full replacement record set. Each record has `record_type`, `value`, `ttl`

bash

curl -X PUT https://divi.cx/testnet/api/v1/domains/alice \
  -H "Content-Type: application/json" \
  -H "X-Divi-Signature: <base64sig>" \
  -d '{
    "records": [
      { "record_type": "A", "value": "203.0.113.20", "ttl": 300 },
      { "record_type": "CNAME", "value": "alice.testnet.divi.cx.", "ttl": 600 }
    ]
  }'

JSON

{
  "success": true,
  "name": "alice",
  "tx_hash": "d9e4b2a1...",
  "record_count": 2
}

Try It — Requires Signed Request

This endpoint requires a valid X-Divi-Signature. Use the Manage UI to update records interactively.

name (path parameter)

Request Body (JSON)

X-Divi-Signature

Renewals & Transfers

Lifecycle Endpoints

POST /domains/:name/renew Renew domain registration

Authorization required. Extends expiry by one year from the current expiry date. Include a new payment transaction covering the renewal fee.

Field	Type	Description
namerequired	path	Domain label to renew
payment_txrequired	string	Mainchain TX ID proving renewal payment

bash

curl -X POST https://divi.cx/testnet/api/v1/domains/alice/renew \
  -H "Content-Type: application/json" \
  -H "X-Divi-Signature: <base64sig>" \
  -d '{ "payment_tx": "f1a2b3c4d5..." }'

JSON

{
  "success": true,
  "name": "alice",
  "new_expires_at": "2028-02-01T12:34:56Z",
  "tx_hash": "e5f6a7b8..."
}

Try It — Requires Signed Request

Requires a valid X-Divi-Signature and a new payment TX. Use the Manage UI for guided renewal.

name (path parameter)

payment_tx

X-Divi-Signature

POST /domains/:name/transfer Transfer domain to new owner

Authorization required. Must be signed by the current owner. Transfers ownership immediately — the new owner can update records right away.

Field	Type	Description
namerequired	path	Domain label to transfer
new_ownerrequired	string	Divi testnet address of the recipient

bash

curl -X POST https://divi.cx/testnet/api/v1/domains/alice/transfer \
  -H "Content-Type: application/json" \
  -H "X-Divi-Signature: <base64sig>" \
  -d '{ "new_owner": "yJehBfdK9KbrwPRjYrzkrPES9uG5nFLjY4" }'

JSON

{
  "success": true,
  "name": "alice",
  "previous_owner": "yEnBd9VbtBRjACMcXWVRLKAGT3hbeq6JbF",
  "new_owner": "yJehBfdK9KbrwPRjYrzkrPES9uG5nFLjY4",
  "tx_hash": "g2h3i4j5..."
}

Try It — Requires Signed Request

Requires a valid X-Divi-Signature from the current owner.

name (path parameter)

new_owner

X-Divi-Signature

Network

Network Endpoints

GET /activity Recent network activity feed

Parameter	Type	Description
limitopt	integer	Max events (default 20, max 100)
typeopt	string	Filter: `registered` \| `updated` \| `renewed` \| `transferred`

bash

curl "https://divi.cx/testnet/api/v1/activity?limit=5&type=registered"

JSON

{
  "events": [
    {
      "type": "registered",
      "name": "bob",
      "fqdn": "bob.testnet.divi.cx",
      "owner": "yJehBfdK9KbrwPRjYrzkrPES9uG5nFLjY4",
      "at": "2026-03-23T08:42:11Z",
      "tx_hash": "h1i2j3k4..."
    }
  ]
}

Try It — Live Request

limit

type (optional)

GET /pricing Domain pricing tiers

No parameters required.

bash

curl https://divi.cx/testnet/api/v1/pricing

JSON

{
  "prices": [
    { "length": "3 characters",  "price": 1000000000000, "price_display": "10000 DIVI" },
    { "length": "4 characters",  "price": 500000000000,  "price_display": "5000 DIVI" },
    { "length": "5 characters",  "price": 100000000000,  "price_display": "1000 DIVI" },
    { "length": "6+ characters", "price": 50000000000,   "price_display": "500 DIVI" }
  ],
  "registration_period_blocks": 525960,
  "grace_period_blocks": 43830
}

Try It — Live Request

GET /payment/:name Get payment address for registration

Parameter	Type	Description
namerequired	path	Domain label you intend to register

bash

curl https://divi.cx/testnet/api/v1/payment/mysite

JSON

{
  "name": "mysite",
  "payment_address": "yEnBd9VbtBRjACMcXWVRLKAGT3hbeq6JbF",
  "amount_divi": 100,
  "tier": "standard",
  "note": "Send exactly this amount in a single output. Include your registering address in OP_RETURN."
}

Try It — Live Request

name (domain to register)