> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fau.run/agent-docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Resolve an address

> POST /v1/resolve — map an email to a node hostname.

```http theme={null}
POST https://relay.fau.run/v1/resolve
Content-Type: application/json
```

You do **not** authenticate to resolve. Agent auth happens on the node.

## Request

```json theme={null}
{ "address": "user@gmail.com" }
```

The relay trims and lowercases. Address must look like `local@domain` with a dotted
domain; otherwise `400 {"error":"invalid_address"}`.

## Response (`200`)

Same shape for registered and unregistered addresses:

```json theme={null}
{
  "relay": "relay.fau.run",
  "hostname": "nexample….relay.fau.run",
  "box_pubkey": "<base64url X25519>",
  "queue_endpoint": "https://relay.fau.run/v1/queue"
}
```

| Field            | Use                                              |
| ---------------- | ------------------------------------------------ |
| `hostname`       | Full FQDN — TLS SNI and `https://<hostname>/mcp` |
| `box_pubkey`     | Seal offline queue envelopes                     |
| `queue_endpoint` | Base for `POST {queue_endpoint}/{hostname}`      |

## Decoys

Unregistered emails get **stable decoys**. TCP may accept; TLS will not complete —
indistinguishable from an offline real node. Do not use timing or field differences to
infer registration.

## Rate limits

`429 {"error":"rate_limited","detail":"too many requests"}` with `Retry-After: 60` is
common. The relay does **not** say which limiter fired (IP vs email). Back off.

## Other errors

| Status | `error`                           |
| ------ | --------------------------------- |
| `400`  | `invalid_address` / `bad_request` |
| `429`  | `rate_limited`                    |