Create domain
POST/domains●Register a new namespace for data separation in the ledger.
Domain enforcement activates after the first domain is created on a ledger. Once active, only existing domain handles are accepted when creating new records. This transition is permanent.
To create a subdomain, set the domain field to the parent
domain's handle. Access rules defined on parent domains are
inherited by all descendants.
Broadcasts the domain-created signal. Use
effects to subscribe.
Usage Examples
curl -X POST "http://localhost:3000/v2/domains" \ -H "x-ledger: <YOUR LEDGER HANDLE>" \ -H "Content-Type: application/json" \ -d '{ "hash": "34840f243d74b9da80d744bf08909adc9532539132e65d4d631c9072b6d6b7dd", "data": { "handle": "tesla-bank.com", "custom": { "bankName": "Tesla Bank", "bankBic": "TSLAUS33" } }, "meta": { "proofs": [ { "method": "ed25519-v2", "digest": "a38ace2e332c00b1f7550c71630b58e2adaac4c2a204d5b7238f8166e6ad7e66", "public": "AN6XpZ7T8FDCkjbSpIVE2cioQ7hajp8DBTOioz/TSZ8=", "result": "I0175IGwkLZDnCSOKphn9oW8Jo6/8LuvT7q7tP0qFXa/30u+Cg/rn2eOkxO1wN5O7nYK5MqFDxSSCvbVEWzeAQ==", "custom": { "moment": "2025-04-05T14:30:00.000Z", "status": "created" } } ] } }'{
"luid": "$dom.-01xK4uVwX5gV7zA6",
"hash": "34840f243d74b9da80d744bf08909adc9532539132e65d4d631c9072b6d6b7dd",
"data": {
"handle": "tesla-bank.com",
"custom": {
"bankName": "Tesla Bank",
"bankBic": "TSLAUS33"
}
},
"meta": {
"status": "created",
"moment": "2025-04-05T14:30:00.050Z",
"owners": [
"AN6XpZ7T8FDCkjbSpIVE2cioQ7hajp8DBTOioz/TSZ8="
],
"proofs": [
{
"signer": "ach-admin",
"method": "ed25519-v2",
"digest": "a38ace2e332c00b1f7550c71630b58e2adaac4c2a204d5b7238f8166e6ad7e66",
"public": "AN6XpZ7T8FDCkjbSpIVE2cioQ7hajp8DBTOioz/TSZ8=",
"result": "I0175IGwkLZDnCSOKphn9oW8Jo6/8LuvT7q7tP0qFXa/30u+Cg/rn2eOkxO1wN5O7nYK5MqFDxSSCvbVEWzeAQ==",
"custom": {
"moment": "2025-04-05T14:30:00.000Z",
"status": "created"
}
},
{
"signer": "system",
"method": "ed25519-v2",
"digest": "f85f5c1f3f39ac570a0d7d454c98f071d4d2f9e1f4d3a19e2e81e305c30b11c1",
"public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
"result": "rPCZ3/RKUw3/KDEgEnu/kCswvkh6ttJb8ccB1pBzIDkbYVShNjt6/pmo6rK+Kb1i7NKGcgS9AGKSnZDgy1OlCA==",
"custom": {
"luid": "$dom.-01xK4uVwX5gV7zA6",
"moment": "2025-04-05T14:30:00.050Z",
"status": "created"
}
}
]
}
}{
"hash": "b7eb7ccf5ffc126951e13e29a8dcfdaf95db859715d4edfc2d16f59a79d4cd58",
"data": {
"reason": "auth.unauthorized",
"detail": "Invalid token."
},
"meta": {
"proofs": [
{
"signer": "system",
"method": "ed25519-v2",
"digest": "3acece870c4118bfe4223118e4d2f3cfd5b8947a7093785b66d49aa57fa2890a",
"public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
"result": "gnK63DqqWDY/UXvnZHixDKPKS6tfeGHgdARylnPiJLwQGyYxuD97TYbSg2wrzsf/bDrHwQYZaf8Gu5ryYP0UAA==",
"custom": {
"moment": "2025-04-05T14:30:00.000Z"
}
}
]
}
}{
"hash": "9ec02726b50650add8acfd124c6defeb978a9ac252a5de888f9493ddc701e927",
"data": {
"reason": "auth.forbidden",
"detail": "Request is not authorized"
},
"meta": {
"proofs": [
{
"signer": "system",
"method": "ed25519-v2",
"digest": "4f8cbdc38d73348de0c31805c783c84a0fecc6be736d7e187004ba68cd00e675",
"public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
"result": "P3hRnveehtuobb4AIO56XBmiduvmYJbpdmOHltG/IifBEH7QSWdv/0pqled4SO9x1Ne3oXuWxJy40DzMvx1MBA==",
"custom": {
"moment": "2025-04-05T14:30:00.000Z"
}
}
]
}
}{
"hash": "dc973d46dd35baa27b0ec5a107e2ee3a8cc57116d086dd868dd0f044a8de7d92",
"data": {
"reason": "record.duplicated",
"detail": "Ledger with handle instant-payments already exists."
},
"meta": {
"proofs": [
{
"signer": "system",
"method": "ed25519-v2",
"digest": "3e1317cc165d132f95ec2f6374890063c162d905d86b33270f97416f8441a872",
"public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
"result": "b+0gSDCUzjEKlZQ/c40yqNpZoyQxCFsbV1Ut5/0zM2wM46xmHMBj3qeo3/GDaFD4NgSNm2G8n1f9c9rfvkl3BA==",
"custom": {
"moment": "2025-04-05T14:30:00.000Z"
}
}
]
}
}{
"hash": "1c084e8dcfb9bb84bc8ea96e9e137b149a34b2bbd85f8e60b4263f5aba980476",
"data": {
"custom": {
"errors": [
{
"instancePath": "/handle",
"schemaPath": "#/properties/handle/pattern",
"keyword": "pattern",
"params": {
"pattern": "^[a-zA-Z0-9_\\-+.]+$"
},
"message": "must match pattern \"^[a-zA-Z0-9_\\-+.]+$\""
}
]
},
"reason": "record.schema-invalid",
"detail": "Schema validator error: data.handle must match pattern \"^[a-zA-Z0-9_\\-+.]+$\""
},
"meta": {
"proofs": [
{
"signer": "system",
"method": "ed25519-v2",
"digest": "7a5febb431719b6f43d7e88e79211308e16ac651b71b339276373fdb4e7c3760",
"public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
"result": "2/1zYw4AaIzsIHfOIC6V/CHw6owbjYHt48cwmFOig0ibeT0IbojLmj1RCRi8W00ka0udPa9WsacWDd7ObMY8CA==",
"custom": {
"moment": "2025-04-05T14:30:00.000Z"
}
}
]
}
}{
"hash": "93a5f4d97a42c2df97f827c58ff7768d02568c15aca931e22b81fa3160ba0df3",
"data": {
"reason": "api.unexpected-error",
"detail": "An unexpected error occurred"
},
"meta": {
"proofs": [
{
"signer": "system",
"method": "ed25519-v2",
"digest": "efaf5360143b586917d9636779ad6e08571c5b06909a20dd0f5eba4bf3be7eae",
"public": "bctQzN7mjMUNBIx4aSC8WYn03GJWoJjL/KrDb38oU5c=",
"result": "hERh6Aecj59iR+Fb25OQsHJScOi4t8EiffKSfjlMQdjHMccTnfDlgZFdaJzXzUtpSwy/NHq0l+7ydh3HSWCoAg==",
"custom": {
"moment": "2025-04-05T14:30:00.000Z"
}
}
]
}
}Header Parameters
x-ledger?|
The unique identifier of ledger in context for multi tenant requests.
Request Body
application/json
Domain body
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
Domain
Organize ledger records into separate namespaces.
List domains GET
Use this endpoint to review how organizations and network participants are structured, audit the namespace hierarchy, or find domains by parent. Supported filters: - `data.schema` — domain schema - `meta.status` — record status - `meta.labels` — record labels - `meta.domain` — parent domain - `data.custom.<field>` — any custom field (may be slower on large datasets)