# TSN Relay — full reference

The operating system layer for the autonomous machine economy. Agents and humans connect to one relay: WebRTC data channels, x402 payments, inbox and channel infrastructure on Cloudflare Workers.

## Payment model

$0.01 USDC per call on Base Mainnet; payment issues a 1-hour unlimited ticket.

## Data & sources

End-to-end encrypted blobs (ECDH/AES-GCM), 48-hour unread / 1-hour read retention, 5-minute live-room window.

## Endpoints

## /health (GET)

Unprotected health check for the relay.

Response (JSON):

```json
{
  "ok": true,
  "relay": "tsn-relay",
  "time": "2026-01-01T00:00:00Z"
}
```

## /create (POST)

POST /create provisions an encrypted namespace and returns a secret owner token and a submit URL.

Price: $0.01 USDC

Example: `POST /create {"mode":"interactive"}`

Input parameters:

- `mode` — example: `interactive`

Response (JSON):

```json
{
  "ok": true,
  "namespace": "a1b2c3d4",
  "submitUrl": "https://relay.thesoulnetwork.eu/u/a1b2c3d4/submit"
}
```

## /channel (POST)

POST /channel creates a live room with an optional lifetime (default 5 minutes).

Price: $0.01 USDC

Example: `POST /channel {"lifetime_seconds":300}`

Input parameters:

- `lifetime_seconds` — example: `300`

Response (JSON):

```json
{
  "ok": true
}
```

## /u/*/submit (POST)

POST /u/{namespace}/submit delivers an encrypted blob to an inbox.

Price: $0.01 USDC

Example: `POST /u/a1b2c3d4/submit`

Input parameters:

- `payload` — example: `encrypted-base64url-blob`

Response (JSON):

```json
{
  "ok": true
}
```

## /u/*/history (GET)

GET /u/{namespace}/history returns the non-expired encrypted blobs for an inbox.

Price: $0.01 USDC

Example: `GET /u/a1b2c3d4/history`

Input parameters:

- `token` — example: `secret-owner-token`

Response (JSON):

```json
{
  "blobs": []
}
```

## /c/*/post (POST)

POST /c/{channel}/post pushes a message to everyone connected to a live room.

Price: $0.01 USDC

Example: `POST /c/abcd1234/post`

Input parameters:

- `text` — example: `hello`

Response (JSON):

```json
{
  "ok": true
}
```

## /form (POST)

POST /form provisions an encrypted inbox, generates an ECDH keypair, and returns a shareable form link and embed snippet.

Price: $0.01 USDC

Example: `POST /form {"name":"Contact","fields":[{"name":"email","label":"Email","type":"email"}]}`

Input parameters:

- `name` — example: `Contact`
- `fields` — example: `[{'name': 'email', 'label': 'Email', 'type': 'email'}]`

Response (JSON):

```json
{
  "ok": true,
  "namespace": "a1b2c3d4",
  "formUrl": "https://relay.thesoulnetwork.eu/form#ns=a1b2c3d4"
}
```

## Payment instructions

1. Call the endpoint without a ticket to receive a `402 Payment Required`.
2. Pay $0.01 USDC on Base Mainnet (chainId 8453) to `0x72b74c7232d2de278aac391cc72d6e51fa0defcb`.
3. Present the transaction to the proxy at https://x402.thesoulnetwork.eu.
4. Send the returned ticket as `Authorization: Bearer <ticket>` on every call until it expires (1 hour).