Paid: Knock: Reach a Real Person

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.

post/api/x402/knock

Request

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

Request body

fromstring required

Who is knocking. Shown and spoken to the recipient.

messagestring required

The message. The length ceiling is per-door; read it from /api/knock/door.

subjectstring

One line the companion says out loud. The body is shown, never read aloud.

urlstring

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_idstring

Idempotency key. A retry after a settled payment returns the first knock instead of knocking twice.

Response

three.ws Knock result JSON

Changes

No recorded changes to this operation across all 1 revision of this API.