postIssue action token
Authentication: Send Authorization: Bearer <access_token>.
MFA assurance: action_token.issue. A step-up challenge returns insufficient_user_authentication; authenticate at the requested assurance before retrying.
Issues a short-lived action token that authorises a specific money-movement command. The token is bound to the caller and to the command digest of the requested action. Pass it in the X-Action-Token header when submitting the authorised command (e.g. POST /withdrawals). Pure service callers have no human-confirmation requirement and do not obtain action tokens: issuance requires a human subject and rejects a pure service subject with HTTP 403.
Enterprise/client human callers whose session does not satisfy the scope-level MFA assurance policy receive 401 with code = insufficient_user_authentication; follow the WWW-Authenticate header acr_values and max_age challenge, complete step-up at the IdP, then retry this request. Platform-bound humans always meet a mandatory MFA floor.
Request shapes, in order of preference:
{ action: "<command>", command: { ... } }— edge validates the command and computes the digest server-side. Submit the same command values to the guarded endpoint. Object key order is canonicalized; withdrawal commands also normalize the money and destination fields before hashing. Supported commands:withdrawal.create→POST /withdrawalsconversion.create→POST /conversionsexternal_settlement_conversion.create→POST /external-settlement-conversions
{ action: "withdrawal.create", withdrawal: { ... } }— the original withdrawal-only field name, kept for compatibility; issues the same digest as the generic form.{ command_digest: "..." }— escape hatch for guarded commands with no structured variant yet. Callers must reproduce edge canonicalisation themselves, so prefer the structured form wherever one exists. Digests are hexadecimal SHA-256 values without a sha256: prefix.
Tokens are bound to the human subject and command, expire after five minutes and can be consumed once. Credential issuance bypasses durable idempotency response caching. Each request issues a fresh single-use token; retries must obtain and use a fresh token.
Request
Required request body.
Request body schema
At least one alternative must match.
Request body schema: alternative 1
| Field | Type | Required | Description and constraints |
|---|---|---|---|
action |
"withdrawal.create" | Yes | |
command |
object or object | Yes |
Additional fields are not accepted.
Request body schema: alternative 1.command
At least one alternative must match.
Request body schema: alternative 1.command: alternative 1
| Field | Type | Required | Description and constraints |
|---|---|---|---|
account_ref |
string | Yes | pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ |
amount |
object | Yes | No additional fields |
destination |
object | No | No additional fields |
destination_id |
string | No | format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ |
network |
string | No | minLength: 1 |
rail |
"crypto" / "fiat" | Yes |
Additional fields are not accepted.
Request body schema: alternative 1.command: alternative 1.amount
| Field | Type | Required | Description and constraints |
|---|---|---|---|
currency |
string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$ |
value |
string | Yes | DecimalString pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$ |
Additional fields are not accepted.
Request body schema: alternative 1.command: alternative 1.destination
| Field | Type | Required | Description and constraints |
|---|---|---|---|
address |
string | Yes | minLength: 1 |
memo |
string or null | No |
Additional fields are not accepted.
Request body schema: alternative 1.command: alternative 1.destination.memo
At least one alternative must match.
Request body schema: alternative 1.command: alternative 1.destination.memo: alternative 1
Type: string.
Request body schema: alternative 1.command: alternative 1.destination.memo: alternative 2
Type: null.
Request body schema: alternative 1.command: alternative 2
| Field | Type | Required | Description and constraints |
|---|---|---|---|
account_ref |
string | Yes | pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ |
amount |
object | Yes | No additional fields |
rail |
"fiat" | Yes | |
withdrawal_destination_id |
string | Yes | format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ |
Additional fields are not accepted.
Request body schema: alternative 1.command: alternative 2.amount
| Field | Type | Required | Description and constraints |
|---|---|---|---|
currency |
string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$ |
value |
string | Yes | DecimalString pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$ |
Additional fields are not accepted.
Request body schema: alternative 2
| Field | Type | Required | Description and constraints |
|---|---|---|---|
action |
"conversion.create" | Yes | |
command |
object | Yes | No additional fields |
Additional fields are not accepted.
Request body schema: alternative 2.command
| Field | Type | Required | Description and constraints |
|---|---|---|---|
account_ref |
string | Yes | pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ |
client_idempotency_key |
string | No | minLength: 1 |
from_amount |
object | Yes | No additional fields |
to_currency |
string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$ |
Additional fields are not accepted.
Request body schema: alternative 2.command.from_amount
| Field | Type | Required | Description and constraints |
|---|---|---|---|
currency |
string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$ |
value |
string | Yes | DecimalString pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$ |
Additional fields are not accepted.
Request body schema: alternative 3
| Field | Type | Required | Description and constraints |
|---|---|---|---|
action |
"external_settlement_conversion.create" | Yes | |
command |
object | Yes | No additional fields |
Additional fields are not accepted.
Request body schema: alternative 3.command
| Field | Type | Required | Description and constraints |
|---|---|---|---|
account_ref |
string | Yes | pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ |
client_idempotency_key |
string | No | minLength: 1 |
external_settlement_role |
"external_source_spend" / "external_target_disbursement" | Yes | |
source_amount |
object | Yes | No additional fields |
target_currency |
string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$ |
Additional fields are not accepted.
Request body schema: alternative 3.command.source_amount
| Field | Type | Required | Description and constraints |
|---|---|---|---|
currency |
string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$ |
value |
string | Yes | DecimalString pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$ |
Additional fields are not accepted.
Request body schema: alternative 4
| Field | Type | Required | Description and constraints |
|---|---|---|---|
action |
"withdrawal.create" | Yes | |
withdrawal |
object or object | Yes |
Additional fields are not accepted.
Request body schema: alternative 4.withdrawal
At least one alternative must match.
Request body schema: alternative 4.withdrawal: alternative 1
| Field | Type | Required | Description and constraints |
|---|---|---|---|
account_ref |
string | Yes | pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ |
amount |
object | Yes | No additional fields |
destination |
object | No | No additional fields |
destination_id |
string | No | format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ |
network |
string | No | minLength: 1 |
rail |
"crypto" / "fiat" | Yes |
Additional fields are not accepted.
Request body schema: alternative 4.withdrawal: alternative 1.amount
| Field | Type | Required | Description and constraints |
|---|---|---|---|
currency |
string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$ |
value |
string | Yes | DecimalString pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$ |
Additional fields are not accepted.
Request body schema: alternative 4.withdrawal: alternative 1.destination
| Field | Type | Required | Description and constraints |
|---|---|---|---|
address |
string | Yes | minLength: 1 |
memo |
string or null | No |
Additional fields are not accepted.
Request body schema: alternative 4.withdrawal: alternative 1.destination.memo
At least one alternative must match.
Request body schema: alternative 4.withdrawal: alternative 1.destination.memo: alternative 1
Type: string.
Request body schema: alternative 4.withdrawal: alternative 1.destination.memo: alternative 2
Type: null.
Request body schema: alternative 4.withdrawal: alternative 2
| Field | Type | Required | Description and constraints |
|---|---|---|---|
account_ref |
string | Yes | pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ |
amount |
object | Yes | No additional fields |
rail |
"fiat" | Yes | |
withdrawal_destination_id |
string | Yes | format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ |
Additional fields are not accepted.
Request body schema: alternative 4.withdrawal: alternative 2.amount
| Field | Type | Required | Description and constraints |
|---|---|---|---|
currency |
string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$ |
value |
string | Yes | DecimalString pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$ |
Additional fields are not accepted.
Request body schema: alternative 5
| Field | Type | Required | Description and constraints |
|---|---|---|---|
command_digest |
string | Yes | Pre-computed command digest. Escape hatch for guarded commands with no structured variant yet — prefer the action form, which covers withdrawal.create, conversion.create, external_settlement_conversion.create. minLength: 1 |
Additional fields are not accepted.
Request URL
POST /action-tokensRequest Body
{
"action": "conversion.create",
"command": {
"account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"from_amount": {
"currency": "USDT",
"value": "100.00"
},
"to_currency": "BTC"
}
}Responses
Response
{
"bound_actor": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"bound_command_digest": "a67a92ab1ea536ece3702cb97990040a45948c453aeb585e5ed1d8f2ce7734af",
"expires_at": "2026-05-01T10:00:00Z",
"token": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}Resource created successfully.
Response 201 schema
Content type: application/json.
application/json body
| Field | Type | Required | Description and constraints |
|---|---|---|---|
bound_actor |
string | Yes | |
bound_command_digest |
string | Yes | |
expires_at |
string | Yes | format: date-time; pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ |
token |
string | Yes |
Additional fields are not accepted.
| Response header | Type | Description |
|---|---|---|
Cache-Control |
"no-store" |
Response 400 schema
Content type: application/json.
application/json body
| Field | Type | Required | Description and constraints |
|---|---|---|---|
code |
string | Yes | |
data |
object | No | No additional fields |
details |
object | No | Additional fields allowed |
message |
string | Yes |
Additional fields are not accepted.
application/json body.data
| Field | Type | Required | Description and constraints |
|---|---|---|---|
acr_values |
string | No | RFC 9470 step-up challenge (insufficient_user_authentication). |
blockers |
object[] | No | For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition. |
code |
string | No | For legal refusals: the document code the refusal is about. |
max_age |
string | No | RFC 9470 step-up challenge (insufficient_user_authentication). |
max_source_amount |
object | No | For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum. No additional fields |
min_source_amount |
object | No | For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included. No additional fields |
published_version |
string | No | For document_version_superseded: the version currently published. |
reason |
string | No | Typed refinement of code, from the failing service's contract. |
resource |
string | No | Resource kind a resource_not_found refers to. |
retry_after_ms |
integer | No | Suggested back-off in milliseconds for throttling or temporary unavailability; null means no delay is known. minimum: 0 |
source |
string | No | For not_admissible: the gate that denied (verification, lifecycle, policy, compliance). |
Additional fields are not accepted.
application/json body.data.blockers
For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition.
Type: object[].
application/json body.data.blockers item
| Field | Type | Required | Description and constraints |
|---|---|---|---|
description |
string | Yes | |
type |
"non_zero_balance" / "active_sub_resources" / "pending_operations" / "active_users" / "active_service_accounts" / "active_role_assignments" | Yes | |
assets |
object[] | No | minItems: 1 |
count |
integer | No | minimum: 0; maximum: 9007199254740991 |
Additional fields are not accepted.
application/json body.data.blockers item.assets
Type: object[]. minItems: 1
application/json body.data.blockers item.assets item
| Field | Type | Required | Description and constraints |
|---|---|---|---|
asset |
string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$ |
kind |
"balance" / "held" / "owed" / "unsettled" | Yes |
Additional fields are not accepted.
application/json body.data.max_source_amount
For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
currency |
string | Yes | |
value |
string | Yes |
Additional fields are not accepted.
application/json body.data.min_source_amount
For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
currency |
string | Yes | |
value |
string | Yes |
Additional fields are not accepted.
Response 401 schema
Content type: application/json.
application/json body
| Field | Type | Required | Description and constraints |
|---|---|---|---|
code |
"insufficient_user_authentication" | Yes | |
data |
object | Yes | No additional fields |
message |
string | Yes |
Additional fields are not accepted.
application/json body.data
| Field | Type | Required | Description and constraints |
|---|---|---|---|
acr_values |
string | Yes | |
max_age |
string | Yes |
Additional fields are not accepted.
| Response header | Type | Description |
|---|---|---|
WWW-Authenticate |
string | RFC 9470 challenge. acr_values is urn:yh:acr:mfa for mandatory MFA policy and urn:yh:acr:mfa-if-enrolled for optional critical-step-up policy. |
Response 403 schema
Content type: application/json.
application/json body
| Field | Type | Required | Description and constraints |
|---|---|---|---|
code |
string | Yes | |
data |
object | No | No additional fields |
details |
object | No | Additional fields allowed |
message |
string | Yes |
Additional fields are not accepted.
application/json body.data
| Field | Type | Required | Description and constraints |
|---|---|---|---|
acr_values |
string | No | RFC 9470 step-up challenge (insufficient_user_authentication). |
blockers |
object[] | No | For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition. |
code |
string | No | For legal refusals: the document code the refusal is about. |
max_age |
string | No | RFC 9470 step-up challenge (insufficient_user_authentication). |
max_source_amount |
object or null | No | For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum. No additional fields |
min_source_amount |
object | No | For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included. No additional fields |
published_version |
string | No | For document_version_superseded: the version currently published. |
reason |
string | No | Typed refinement of code, from the failing service's contract. |
resource |
string | No | Resource kind a resource_not_found refers to. |
retry_after_ms |
integer or null | No | Suggested back-off in milliseconds for throttling or temporary unavailability; null means no delay is known. minimum: 0 |
source |
string | No | For not_admissible: the gate that denied (verification, lifecycle, policy, compliance). |
Additional fields are not accepted.
application/json body.data.blockers
For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition.
Type: object[].
application/json body.data.blockers item
| Field | Type | Required | Description and constraints |
|---|---|---|---|
description |
string | Yes | |
type |
"non_zero_balance" / "active_sub_resources" / "pending_operations" / "active_users" / "active_service_accounts" / "active_role_assignments" | Yes | |
assets |
object[] | No | minItems: 1 |
count |
integer | No | minimum: 0; maximum: 9007199254740991 |
Additional fields are not accepted.
application/json body.data.blockers item.assets
Type: object[]. minItems: 1
application/json body.data.blockers item.assets item
| Field | Type | Required | Description and constraints |
|---|---|---|---|
asset |
string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$ |
kind |
"balance" / "held" / "owed" / "unsettled" | Yes |
Additional fields are not accepted.
application/json body.data.max_source_amount
For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
currency |
string | Yes | |
value |
string | Yes |
Additional fields are not accepted.
application/json body.data.min_source_amount
For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
currency |
string | Yes | |
value |
string | Yes |
Additional fields are not accepted.
Response 404 schema
Content type: application/json.
See response 403 schema.
Response 409 schema
Content type: application/json.
See response 403 schema.
Response 500 schema
Content type: application/json.
See response 403 schema.
Response 502 schema
Content type: application/json.
See response 400 schema.
Response 503 schema
Content type: application/json.
See response 400 schema.