Skip to main content
Submit a new public DID record.
The Directory submits register_with_document_proof as an ownerless DID-key operation. It does not attach a chain account owner, even if the server environment contains an account seed.
Registration creates the first public record for an identity. First send did, root_pubkey, did_document and optional alias to POST /register-did/prepare. Preparation validates the public fields without submitting a transaction and returns request plus payload_to_sign as 0x-prefixed hex. Decode that hex into binary bytes and sign them locally with the Ed25519 private key corresponding to the root public key. Add the Base64 signature to the returned request and submit it to this endpoint. The proof binds the DID, normalized alias, root key and exact encoded document; changing any of them requires preparing and signing again. See the Quickstart for copyable examples. This flow requires the Directory and runtime supporting v2 DID proofs (runtime spec 125). The former UTF-8 DID|timestamp signature is rejected. Preparation defaults to a five-minute lifetime; prepare and sign again if it expires.

Request

string
required
The canonical did:<platform>:<Base58Address> identifier. The platform must contain 1–32 lowercase ASCII letters or digits. The address must contain 16–96 Bitcoin Base58 characters. The identifier must exactly match did_document.id.
string
required
The returned v2:0:<valid-until-epoch-milliseconds> signing token. It must be unexpired and no more than one hour ahead; copy it unchanged from preparation.
string
required
Base64 Ed25519 signature over the decoded binary payload_to_sign bytes.
object
required
The public DID document.
string
The root Ed25519 public key. If omitted, the Directory selects a supported Ed25519 verification method controlled by this DID. Supply it explicitly for documents containing only application-specific key suites.
string
An optional lowercase public alias. It cannot contain @ or #.

Response

string
required
A human-readable registration status.
string
required
The public registration state.
string
required
The submitted transaction identifier.
string
required
The submitted DID.
object
required
The submitted public DID document.
202 means the Directory accepted the registration for processing. It does not confirm final settlement. Poll Get registration status until the state is confirmed.

Understand the complete document

Learn how each key and service entry participates in encryption, Relay delivery, and Cache retrieval.

Straight to the point

  • Prepare: POST /register-did/prepare with unsigned public registration input
  • Signed bytes: binary hex-decoded payload_to_sign from preparation
  • Submit: returned request plus Base64 signature, unchanged before expiry
  • Signature: Ed25519, Base64 encoded
  • Private key: never submitted
  • Confirmation: poll GET /registration-status/{did}