---
title: "Paid: Knock: Reach a Real Person"
method: POST
path: "/api/x402/knock"
---

# Paid: Knock: Reach a Real Person

`POST /api/x402/knock`

## Request

- Base URL: `https://three.ws`
- URL: `https://three.ws/api/x402/knock`
- Auth: none required

Pay a real person's price and get one message through to them, in person. Every three.ws account can publish a priced door at /knock/<username>; paying it buys exactly one message, delivered out loud and in person by that person's 3D companion, which walks on screen wherever they are on the site and says who you are and what you paid. Call it as POST /api/x402/knock?to=<username>: the challenge quotes that door's own price, and the USDC settles directly to the recipient, not to three.ws. Read GET /api/knock/door?handle=<username> for a door's exact price and limits before you pay, or GET /api/knock/directory for every open door. The response carries a receipt URL you can poll for a reply without needing an account. The price listed here is the representative one a probe with no handle receives.

## Request body

- object
  - `from` string, required: Who is knocking. Shown and spoken to the recipient.
  - `message` string, required: The message. The length ceiling is per-door; read it from /api/knock/door.
  - `subject` string: One line the companion says out loud. The body is shown, never read aloud.
  - `url` string: An http(s) link the recipient can follow to check you out.
  - `sender_kind` 'agent' | 'human' | 'unknown': Self-declared. Shown in the inbox, never trusted for access.
  - `request_id` string: Idempotency key. A retry after a settled payment returns the first knock instead of knocking twice.

## Response `200`

three.ws Knock result JSON

## Other responses

- `400`: Validation error
- `402`: Payment Required (x402)

---

[API](https://skmtc.dev/three/apis/three-ws-api.md) · [All operations](https://skmtc.dev/three/apis/three-ws-api/llms.txt) · [OpenAPI document](https://skmtc.dev/three/apis/three-ws-api/revisions/dbc5e3a81b79?raw)