nc, follow the WebSocket tunnel to stdout. It uses the same Hello World send pipeline and replaces Cache fetching with a WebSocket session opened before sending.
Choose your starting point
Read a public DID first
A terminal is the text-based application where you type commands. On macOS it is named Terminal. On Windows you can use PowerShell. On Linux it may be named Terminal, Console, or Shell. Ask your Directory operator for:- Its HTTPS base URL
- A confirmed public OpenPayload DID you may use for testing
document, aliases, devices, and registration_status, your connection is working. A 404 means the sample DID is not registered on that Directory; it does not necessarily mean your command is malformed.
Create an identity locally
The remaining steps generate an Ed25519 keypair and public DID document locally, ask the Directory to prepare registration bytes, and sign those bytes on your machine. A public key may be shared. A private key proves control of the identity and must remain secret.POST /register-did creates an ownerless DID using the root-key registration proof. Later Directory updates
use the root or another authorized DID key; they do not require a chain account.Prerequisites
Choose either the Bash or Python workflow.- Bash and OpenSSL
- Python
Install the following command-line tools:If this command returns no match, install or select OpenSSL 3 before continuing. The LibreSSL version bundled with some operating systems may not support the commands in this guide.
- Bash or another POSIX-compatible shell
- OpenSSL 3 with Ed25519 support
- Python 3 for Base58 encoding using only the standard library
jqfor constructing JSONcurlfor submitting the request
Set the Directory URL
Replace the placeholder with the HTTPS URL supplied by your Directory operator:Generate the identity
- Bash and OpenSSL
- Python
Create Make the script executable and run it:
generate-openpayload-identity.sh with the following content:Review the generated files
This quickstart creates a minimal identity with empty
keyAgreement and service arrays. That identity can be registered, but it does not yet advertise an encryption key, Relay, or Cache. Before using it for messaging, publish the components shown in A complete messaging DID document.
Inspect the DID document and unsigned registration input before preparation:
registration-input.json.didequalsdid_document.id.- The first
verificationMethod.idstarts with the same DID. controllerequals the DID.root_pubkeyequals the firstpublicKeyMultibasevalue.registration-input.jsondoes not contain the private key.
Prepare and sign registration
These steps require a Directory and chain runtime supporting v2 DID proofs (runtime spec 125). They do not change how DIDs or keys are generated. The oldDID|timestamp signature is no longer accepted by this version.
Ask the Directory to validate the public input and return the exact registration bytes. Preparation does not register the DID:
request and a 0x-prefixed payload_to_sign. Review the public request, then decode the hex into a binary file; sign the decoded bytes, never the hex text or JSON:
- Bash and OpenSSL
- Python
Sign with the locally generated key, then add the Base64 signature to the returned request:
timestamp field carries v2:0:<expiry-milliseconds>; it is a signing token, not a DID document version. Preparation defaults to a five-minute lifetime. Submit promptly. If it expires or you edit the document, repeat preparation and signing with the existing key; do not regenerate the identity. See Register a DID.
Register the DID
Submit the generated request:202 Accepted with a transaction identifier and a pending registration status:
202 Accepted means the Directory accepted the registration for processing. It does not mean the registration is confirmed.Wait for confirmation
Read the DID from the registration file and URL-encode it for the path:
A
502 response means the Directory could not verify chain state. Retry the status request; do not interpret it as missing.
Resolve the DID
Resolve the public record:425 with recipient_registration_pending, check registration status again. A confirmed record returns 200 and includes:
Send a live Relay message
You can now use the confirmed DID as both the sender’s test destination and the WebSocket recipient. This keeps the first message focused on the live Relay path:- The recipient opens a WebSocket session with the Relay.
- You compose a minimal
Hello World!envelope. - You submit the envelope to
POST /relay. - The Relay delivers it to the connected WebSocket.
WebSocket is the live receiving path in this example. Envelope submission uses
POST /relay; the Relay does not accept outbound envelopes as WebSocket frames.Set the Relay URLs
Ask your Relay operator for its HTTPS and WebSocket base URLs, then set both values:Open the recipient WebSocket
Open a second terminal and connect the DID you registered above. The device identifierhello-world is local to this live session.
This command uses npx, which is included with Node.js. You can use another WebSocket client if you prefer.
Compose the smallest test envelope
Return to your first terminal. Generate a new message identifier and current timestamp, then write the envelope:Submit the message
Send the envelope to the Relay:local_websocket, confirm that the WebSocket is still connected under the same DID and that the DID registration is finalized.
Protect the private key
After registration:- Move
private-key.peminto your secret manager or encrypted key store. - Keep at least one secure recovery copy.
- Do not commit the generated directory to source control.
- Delete unneeded binary intermediates after you confirm your backup and signing workflow.
.gitignore:
Explore the Directory API
Continue with alias, device, DID document, and delivery policy endpoints.

