API Endpoints

Every DRS node exposes four endpoints. All responses are JSON. All transport is HTTPS.

GET /.well-known/directory.json

Returns the capability manifest — what this node accepts.

Response (200):

{
  "protocol": "directory-v1",
  "domain": "gmail.com",
  "node_type": "standard",
  "accepts": [
    {
      "value_type": "USDC",
      "transfer_type": "ethereum",
      "reference": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "sponsor": "circle.com"
    },
    { "value_type": "ETH", "transfer_type": "ethereum" }
  ]
}

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

Exchange nodes include a pathways array declaring conversion capabilities.

POST /resolve

Resolves an address into a signed routing contract.

Request:

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

For exchange nodes, include the target pair:

{
  "address": "alice@gmail.com",
  "pathway_to": { "value_type": "USD", "transfer_type": "ach" }
}

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": "..."
}

Cache: Cache-Control: no-store — every resolution is fresh.

GET /.well-known/directory/references/:value_type/:transfer_type

Returns reference data for a specific asset pair. Used by sponsors to vouch for asset identity.

Example: GET /.well-known/directory/references/USDC/ethereum

Response (200):

{
  "value_type": "USDC",
  "transfer_type": "ethereum",
  "reference": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "issuer": "Circle",
  "decimals": 6
}

Cache: Cache-Control: public, max-age=3600

The response schema is open-ended. Sponsors may include any metadata useful for the pair.

GET /health

Returns node health status.

Response (200):

{
  "status": "healthy",
  "domain": "gmail.com",
  "node_type": "standard",
  "address_count": 1542,
  "kv_status": "connected"
}

Error Responses

All errors follow the same structure:

{
  "status": 404,
  "code": "ADDRESS_NOT_FOUND",
  "message": "No address found for \"nobody\"",
  "field": "address"
}

Status	Code	When
400	INVALID_REQUEST	Missing or malformed fields
404	ADDRESS_NOT_FOUND	Address does not exist or is not active
404	PATHWAY_NOT_FOUND	Exchange node has no pathway to the requested pair
500	INTERNAL_ERROR	Unexpected server error
503	KV_UNAVAILABLE	Storage layer is unreachable