Redeem value out of an account.

POST

/v1/redemptions

const url = 'https://example.com/v1/redemptions';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"amount":"example","asset":"example","reference":"example","source":"example"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://example.com/v1/redemptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "amount": "example", "asset": "example", "reference": "example", "source": "example" }'

Authorizations

bearer

Parameters

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 Body^required

application/json

redeem (SPEC §8.1): value leaves the book to the issuance counterparty.

object

amount

required

Minor units, as a decimal-integer string.

string

asset

required

The asset.

string

reference

Any of:

unknown
null

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.

source

required

The account debited.

string

Example^generated

{
  "amount": "example",
  "asset": "example",
  "reference": "example",
  "source": "example"
}

Responses

200

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

application/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:

unknown
null

One of:

Terminal: the outcome is final.

string

Allowed value: terminal

Needs-Review: waiting for a human. Not terminal and not refunding.

string

Allowed value: awaiting-human

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:

unknown
null

result

Any of:

object
null

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:

object
null

What an anchoring command produced.

object

checkpoint

Any of:

object
null

A checkpoint on the wire.

object

commitment

required

The commitment, hex.

string

coordinate

Any of:

object
null

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:

object
null

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>

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:

object
null

What a settlement command produced.

object

anchor

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

string | null

attestation

Any of:

object
null

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:

object
null

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>

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:

object
null

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:

object
object

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

object

account

required

string

Another deployment on the same settlement layer (REQ-SL-6).

object

instance

required

object

account_ref

required

The opaque account reference it resolves: 32 bytes of hex.

string

instance

required

Its instance.

integer format: uint32

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:

object
null

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:

object
null

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:

unknown
null

One of:

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

string

Allowed value: applied

The coordinate was seen before (ERR-ObservationDuplicate on the refusal path).

string

Allowed value: already_applied

It relates to nothing aledgent holds (ERR-ObservationUnassociated on the refusal path).

string

Allowed value: not_associated

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

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

application/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

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

application/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

Retry-After

integer

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

Redeem value out of an account.

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Examplegenerated

Responses

200

Example

4XX

Example

5XX

Example

Headers

Request Body^required

Example^generated