Skip to content
aledgent by bloquealedgent by bloquealedgent

Operator: name the account by an alias, (source, name), as a seed's aliases do; a system account's role is one. An alias names one account for good. The operator's policy authority alone (REQ-RC-7).

POST
/v1/ops/accounts/{account}/aliases
curl --request POST \
  --url https://example.com/v1/ops/accounts/example/aliases \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "justification": "example", "name": "example", "source": "example" }'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
account
required
string

A did:aledgent identifier.

Header Parameters

Section titled “Header Parameters”
client-key
string
<= 256 characters

The client key (REQ-OP-10). Without one, a key is derived from the request and returned (REQ-OP-11).

on-behalf-of
string

The identity the caller acts for, where different (REQ-PN-1).

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

register_alias (REQ-RC-7, amendment 0024): name the account in the path by (source, name), as a seed’s aliases do. A system account’s role is one (ops/runbooks/system-accounts.md).

object
justification
required

Why.

string
name
required

The name within the source: a role (issuer/fee) or a prior system’s identifier. At most 256 bytes; never personal data (INV-17).

string
source
required

The source: 16 bytes as 32 hex digits, or a name of at most 16 ASCII bytes, zero-padded (system-role for a system account’s role, as the migration’s role aliases).

string
Examplegenerated
{
  "justification": "example",
  "name": "example",
  "source": "example"
}

Responses

Section titled “ Responses ”

200

Section titled “200”

Decided. For a transfer or a reservation, the reply to a repeat once the core has decided (REQ-CS-3).

Media typeapplication/json

The reply to a command (REQ-CS-2): an acknowledgement, not an outcome. Its state may be Received; a caller learns completion by notification or by operation(reference) (REQ-CS-6). There is no blocking “wait until terminal” reply.

object
api_key

The API key a register_credential with scheme api-key issued (F-028): on the one reply that decided it, and never again. aledgent keeps only its hash (REQ-AU-8).

string | null
class
Any of:
One of:

Terminal: the outcome is final.

string
Allowed value: terminal
client_key
required

The client key the command was taken under: the caller’s, or the one derived from the request when the caller gave none (REQ-OP-11). A retry with it gets this reply again.

string
client_key_derived
required

Whether ingress derived the client key.

boolean
operation_reference
required

The operation reference: service-derived, opaque, never supplied by a caller (REQ-OP-10).

string
reference
Any of:

Pass-through data (REQ-PO-5): any one JSON value, at most 1024 bytes of UTF-8 as sent. Kept and echoed exactly as sent; never read by aledgent. Over the bound, or not one JSON value, the command is refused with ERR-MalformedCommand.

result
Any of:

What a decided command produced. Only the fields of the command’s result are present.

object
account

A new ledger account.

string | null
anchoring
Any of:

What an anchoring command produced.

object
checkpoint
Any of:

A checkpoint on the wire.

object
commitment
required

The commitment, hex.

string
coordinate
Any of:

A settlement-layer record cited by its coordinate.

object
digest
required

The entry’s digest, hex.

string
instance
required

The instance.

integer format: uint32
seq
required

The position in its inbox.

integer format: uint64
created_at
required

When it was created.

integer format: uint64
entry_sequence
required

The sequence of the last entry it covers.

integer format: uint64
kernel_root
required

The kernel root, hex.

string
number
required

Its number: the settlement layer’s anchor number.

integer format: uint64
status
required

pending, submitted or final.

string
comparison
Any of:

A settlement comparison at an inbox cut (F-017, REQ-PR-5).

object
anchors
required

The final checkpoints it is the recorded comparison of.

Array<integer>
at
required

When the core compared.

integer format: uint64
cut
required

The cut: the inbox length at the finalized block compared.

integer format: uint64
differs
required

Whether any asset differs.

boolean
height
required

The block’s height.

integer format: uint64
rows
required

Every asset either side holds.

Array<object>

One asset of a settlement comparison (F-017).

object
asset
required

The asset.

string
book
required

What the book records as held on the settlement layer: minor units, a signed decimal-integer string.

string
difference
required

The layer’s less the book’s.

string
layer
required

What the layer holds, minor units.

string
disclosure

The disclosure, hex.

string | null
credential

Its first credential.

string | null
credentials

The credentials an import added, in order (F-028, REQ-MG-7).

Array<string>
effective_at

When that pending change may complete (F-012).

integer | null format: uint64
grant

A new grant.

string | null
identity

A new identity.

string | null
party

An integrating party registered (REQ-ID-7).

string | null
pending

A pending recovery or succession opened or completed (F-012).

string | null
postings

The posting sequence numbers the command appended, in order.

Array<integer>
settlement
Any of:

What a settlement command produced.

object
anchor

Where an anchor’s checkpoint stands: pending, submitted or final (F-017).

string | null
attestation
Any of:

What the core made of an attestation (DEC-20). Informative: nothing is held on it.

object
asset

The registered asset the adapter maps there.

string | null
mismatch

For book_only: why a binding to this location would be refused now (absent, mapping, symbol, decimals, status); absent when it would be admitted.

string | null
verdict
required

unregistered, book_only, binding or bound: where the mapped asset stands.

string
comparison
Any of:

A settlement comparison at an inbox cut (F-017, REQ-PR-5).

object
anchors
required

The final checkpoints it is the recorded comparison of.

Array<integer>
at
required

When the core compared.

integer format: uint64
cut
required

The cut: the inbox length at the finalized block compared.

integer format: uint64
differs
required

Whether any asset differs.

boolean
height
required

The block’s height.

integer format: uint64
rows
required

Every asset either side holds.

Array<object>

One asset of a settlement comparison (F-017).

object
asset
required

The asset.

string
book
required

What the book records as held on the settlement layer: minor units, a signed decimal-integer string.

string
difference
required

The layer’s less the book’s.

string
layer
required

What the layer holds, minor units.

string
condition

A condition a check detected on the way (ERR-AmountMismatch).

string | null
instruction
Any of:

An instruction in the outbox, as the adapter reads it (REQ-SO-5).

object
amount
required

The exact amount: minor units, as a decimal-integer string.

string
asset
required

The asset.

string
destination
required
One of:

A plain account on the settlement layer: 32 bytes of hex.

object
account
required
string
digest
required

Its identity, which the acknowledgement names: 32 bytes of hex.

string
expiry
required

The settlement-layer height after which it can no longer take effect (REQ-SL-4).

integer format: uint64
operation_reference
required

The operation reference, which the layer’s record of the movement carries.

string
reserved
required

That a reservation exists for it: always true (INV-13).

boolean
moved

Operations a finalised head moved.

Array<object>

An operation a finalised head moved.

object
operation_reference
required

The operation.

string
state
required

The state it entered.

string
rescan
Any of:

What a re-scan found.

object
missing
required

Positions the layer holds that were never ingested.

Array<object>

One position of a re-scan and the digest the layer holds there.

object
digest
required

The digest, 32 bytes of hex.

string
seq
required

The position.

integer format: uint64
unassociated
required

Unassociated records of the range.

integer format: uint64
unknown
required

Final coordinates the core holds that the layer no longer shows.

Array<object>

A settlement-layer record cited by its coordinate.

object
digest
required

The entry’s digest, hex.

string
instance
required

The instance.

integer format: uint32
seq
required

The position in its inbox.

integer format: uint64
status
Any of:

The adapter’s status as the core recorded it.

object
declared_at
required

When the core recorded it.

integer format: uint64
fresh_until
required

The first time it no longer holds.

integer format: uint64
serving
required

Whether it serves.

boolean
verdict
Any of:
One of:

Taken as evidence; the operation’s state is the reply’s.

string
Allowed value: applied
state

The operation’s state at the moment of the reply, where the command has a lifecycle.

string | null
terminal
required

Whether this reply is terminal. false whenever the state is not terminal (REQ-OP-7).

boolean
Example
{
  "class": "terminal",
  "result": {
    "settlement": {
      "verdict": "applied"
    }
  }
}

4XX

Section titled “4XX”

Refused, with the named condition. The status is the alternative’s x-http-status.

Media typeapplication/json
One of:
ERR-NotAuthorised
object
description
required
Allowed value: The initiating principal holds no authority that covers this operation, account, asset or bound
error
required
Allowed value: ERR-NotAuthorised
Example
{
  "description": "The initiating principal holds no authority that covers this operation, account, asset or bound",
  "error": "ERR-NotAuthorised"
}

5XX

Section titled “5XX”

Refused, with the named condition. The status is the alternative’s x-http-status.

Media typeapplication/json
One of:
ERR-NotAuthorised
object
description
required
Allowed value: The initiating principal holds no authority that covers this operation, account, asset or bound
error
required
Allowed value: ERR-NotAuthorised
Example
{
  "description": "The initiating principal holds no authority that covers this operation, account, asset or bound",
  "error": "ERR-NotAuthorised"
}

Headers

Section titled “Headers”
Retry-After
integer

On ERR-DecisionUnavailable (503): seconds to wait before retrying with the same client key (DEC-27 (g)).

© 2026 Pagos Cube LLC · Code: Apache-2.0 OR MIT · agents/: AGPL-3.0-or-later · Docs: CC-BY-4.0