API Endpoints

A conforming DRS node exposes one required endpoint and one optional manifest. All responses are JSON over HTTPS. Errors follow RFC 7807 Problem Details.

POST /resolve (required)

Resolves an address into a signed routing contract.

Request headers: Content-Type: application/json. A non-JSON content type MUST produce a 415 UNSUPPORTED_MEDIA_TYPE.

Request body: A JSON object with an address field. Unknown fields MUST be ignored (forward compatibility).

{ "address": "alice@gmail.com" }

Bare domains are valid addresses:

{ "address": "gmail.com" }

Response (200):

{
  "address": "alice@gmail.com",
  "routes": [
    {
      "value_type": "USDC",
      "transfer_type": "ethereum",
      "destination": "0xABC123...",
      "ttl_seconds": 300
    }
  ],
  "issued_at": "2026-03-08T12:00:00Z",
  "expires_at": "2026-03-08T12:05:00Z",
  "signature": "..."
}

The response is canonicalized with RFC 8785 JCS before signing; the signature field is excluded from canonicalization and Ed25519-signed with the key published in DNS.

Cache: Cache-Control: no-store. Every resolution is fresh.

Limits:

• Request body MUST be <= 4 KiB.
• Response MUST be <= 64 KiB.
• Routes per contract MUST be <= 32.
• ttl_seconds MUST be between 30 and 3600.
• Clients SHOULD tolerate ±60 s of clock skew on issued_at / expires_at.

GET /.well-known/directory.json (optional)

Returns an unsigned capability manifest — a hint about what this node accepts. Clients MUST NOT require this endpoint; a node that returns 404 from it is still conforming.

Response (200):

{
  "protocol": "directory-v1",
  "domain": "gmail.com",
  "accepts": [
    { "value_type": "USDC", "transfer_type": "ethereum" },
    { "value_type": "USDC", "transfer_type": "base" },
    { "value_type": "USD", "transfer_type": "ach" }
  ],
  "admin": "directory-admin@gmail.com"
}

Cache: Cache-Control: public, max-age=60.

If the operator does not publish a manifest, the node returns 404 with Problem Details. The reference implementation reuses the ADDRESS_NOT_FOUND code and distinguishes the cause via detail:

{
  "type": "https://drs.xyz/errors/address-not-found",
  "title": "Address not found",
  "status": 404,
  "code": "ADDRESS_NOT_FOUND",
  "detail": "This node does not publish a capability manifest"
}

Error Responses

All error responses use Content-Type: application/problem+json and conform to RFC 7807.

{
  "type": "https://drs.xyz/errors/address-not-found",
  "title": "Address not found",
  "status": 404,
  "code": "ADDRESS_NOT_FOUND"
}

Recognised codes:

Status	Code	When
400	INVALID_REQUEST	Missing or malformed fields
404	ADDRESS_NOT_FOUND	Address does not exist or is not active
413	PAYLOAD_TOO_LARGE	Request body exceeds 4 KiB
415	UNSUPPORTED_MEDIA_TYPE	Content-Type is not application/json
500	INTERNAL_ERROR	Unexpected server error
503	KV_UNAVAILABLE	Storage backend unreachable

Operators MAY extend this list with additional codes; clients MUST treat unknown codes as generic failures of the indicated HTTP status class.