# B2B2X Public API

OpenAPI-first public contract for tenant-facing B2B2X API surfaces. Terminology and resource semantics are sourced from b2b2x-mono.

## Servers

- **Sandbox**: `https://b2b2x-sandbox.youhodler.com/api`
- **Production**: `https://b2b.youhodler.com/api`

## Auth

### POST /oauth/revoke

**Revoke a refresh token**

Ends the session of a refresh token (RFC 7009), as on sign-out: every refresh token of that session stops working. Answers `200` with an empty object for any well-formed request, whether or not the token is known, so the endpoint does not reveal which tokens exist. An access token is accepted and ignored: it stays valid until its `exp`. `token_type_hint` is optional; any value is accepted and ignored. A body without `token` is a `400` `invalid_request`. Refusals use the same `{error, error_description}` body as `/oauth/token`, with `Cache-Control: no-store`.

**Authentication:** No bearer token required.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `token` | string | Yes | minLength: 1 |
| `token_type_hint` | string | No |  |

Additional fields are not accepted.

**Request example:**

```json
{
  "token": "yhrt_0000000000000000000000000000000000000000001",
  "token_type_hint": "refresh_token"
}
```

### oauth-revoke Response 200 schema

Content type: `application/json`.

#### application/json body

Type: `object`. No additional fields


### oauth-revoke Response 400 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `error` | "invalid_request" / "invalid_client" / "invalid_grant" / "unsupported_grant_type" / "temporarily_unavailable" / "server_error" | Yes |  |
| `error_description` | string | Yes |  |

Additional fields are not accepted.


### oauth-revoke Response 401 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `error` | "invalid_request" / "invalid_client" / "invalid_grant" / "unsupported_grant_type" / "temporarily_unavailable" / "server_error" | Yes |  |
| `error_description` | string | Yes |  |

Additional fields are not accepted.


### oauth-revoke Response 500 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `error` | "invalid_request" / "invalid_client" / "invalid_grant" / "unsupported_grant_type" / "temporarily_unavailable" / "server_error" | Yes |  |
| `error_description` | string | Yes |  |

Additional fields are not accepted.


### oauth-revoke Response 503 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `error` | "invalid_request" / "invalid_client" / "invalid_grant" / "unsupported_grant_type" / "temporarily_unavailable" / "server_error" | Yes |  |
| `error_description` | string | Yes |  |

Additional fields are not accepted.


**Responses:**

- `200` — Operation succeeded.

  ```json
  {}
  ```
- `400` — The request was refused. On `/oauth/token`, `error` is `invalid_request` (malformed body, or a refused subject token or client), `invalid_grant` (every refused refresh) or `unsupported_grant_type`. On `/oauth/revoke` it is `invalid_request`.

  ```json
  {
    "error": "invalid_grant",
    "error_description": "The authorization grant or refresh token is invalid, expired or revoked."
  }
  ```
- `401` — Client authentication failed (`invalid_client`).

  ```json
  {
    "error": "invalid_client",
    "error_description": "Client authentication failed."
  }
  ```
- `500` — Unexpected server error (`server_error`).

  ```json
  {
    "error": "server_error",
    "error_description": "The server encountered an unexpected error."
  }
  ```
- `503` — The service is temporarily unavailable (`temporarily_unavailable`); retry later.

  ```json
  {
    "error": "temporarily_unavailable",
    "error_description": "The service is temporarily unavailable. Try again later."
  }
  ```

### GET /oauth/federated-sign-in/provider

**Resolve a federated sign-in provider**

Returns authorization-code flow endpoints only when the exact issuer and client ID are registered and active. The endpoints are read from the provider OIDC discovery document by identity-service. This public endpoint also exposes the registered workspace legal name as organization_name; it is null when the name lookup fails or times out. `end_session_endpoint` is the provider’s RP-initiated logout from the same discovery document, `null` when it has none (the console then restarts sign-in with `prompt=login&max_age=0`).

**Authentication:** No bearer token required.

**Parameters:**

- `issuer` `string` (query) *(required)*
- `client_id` `string` (query) *(required)*

### oauth-provider Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `authorization_endpoint` | string | Yes | format: uri |
| `authorization_response_iss_parameter_supported` | boolean | No |  |
| `client_id` | string | Yes | minLength: 1 |
| `end_session_endpoint` | string or null | No |  |
| `issuer` | string | Yes | format: uri |
| `organization_name` | string or null | No |  |
| `token_endpoint` | string | Yes | format: uri |

Additional fields are not accepted.

##### application/json body.end_session_endpoint

At least one alternative must match.

###### application/json body.end_session_endpoint: alternative 1

Type: `string`. format: uri

###### application/json body.end_session_endpoint: alternative 2

Type: `null`. 

##### application/json body.organization_name

At least one alternative must match.

###### application/json body.organization_name: alternative 1

Type: `string`. minLength: 1

###### application/json body.organization_name: alternative 2

Type: `null`.


### oauth-provider 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.


### oauth-provider Response 502 schema

Content type: `application/json`.

See [response 400 schema](#oauth-provider-response-400-schema).


### oauth-provider Response 503 schema

Content type: `application/json`.

See [response 400 schema](#oauth-provider-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "authorization_endpoint": "https://idp.partner.example.com/authorize",
    "client_id": "b2b-admin",
    "end_session_endpoint": "https://idp.partner.example.com/logout",
    "issuer": "https://idp.partner.example.com",
    "organization_name": "Example Organization",
    "token_endpoint": "https://idp.partner.example.com/token"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /oauth/token

**Issue access token**

Issues a bearer access token for a service principal using `client_credentials`, or a federated human access token via `urn:ietf:params:oauth:grant-type:token-exchange`, and renews a human session with `refresh_token`. The `password` grant is not supported (`unsupported_grant_type`): human flows go through an external IdP plus token exchange. An enterprise identity backend authenticates `client_credentials` with `private_key_jwt` (RFC 7523): `client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer` and a `client_assertion` signed with its issuer key, `aud` = this endpoint, no `client_secret`; `401` `invalid_client` for failed client authentication, including a suspended IdP or an assertion issued before its last suspension.

**Refresh.** Only a direct sign-in, a `token-exchange` without client credentials, returns `refresh_token` and `session_expires_in` (whole seconds until the session ends, 12 hours after the sign-in that started it by default); the two fields are present together or not at all. A partner `token-exchange` authenticated with `client_id` and `client_secret`, and `client_credentials`, return an access token only. Renew with `grant_type=refresh_token` and `refresh_token` (`400` `invalid_request` without it). No client authentication is needed and request fields cannot change the stored identity or authentication evidence: the answer carries a new access token and the next refresh token, with the identity and authentication of the original sign-in, or of the session’s latest promotion. A refresh token is single-use and, by default, expires after an hour without renewal. Presenting a used one without its still-active successor ends the whole session. Every refused refresh answers `400` `invalid_grant`, whatever the cause: an unknown, expired, used or revoked token, or a user, identity provider or tenant MFA requirement that changed since sign-in. After it, sign in again. A `503` does not itself revoke the session, but the rotation may already have committed; recover with the persisted successor as described below.

**Recovery after a lost response.** Before refreshing or promoting, generate a cryptographically random 256-bit successor (`yhrt_` followed by 43 base64url characters), persist it together with the current refresh token, and send it as `next_refresh_token`. Keep that pair until a response is safely stored. After a timeout, network error or retryable server error, send an ordinary `refresh_token` grant with the same pair. If rotation committed, possession of the still-active successor recovers it without another rotation or extension of the idle or absolute deadline; all session checks still run. Recovery does not apply new authentication evidence. Without a persisted successor, retrying a spent token revokes the session.

**Promotion.** A `token-exchange` that also carries the session’s current `refresh_token` promotes that session instead of starting a new one. This is how a session answers the `insufficient_user_authentication` challenge after re-authenticating. The `subject_token` is verified as at sign-in. It must be a fresh ID token of the same person, from the same identity provider and in the same tenant, and its `auth_time` must be at most 15 minutes old. The answer is a refresh’s: a new access token carrying the new authentication, the next refresh token, and `session_expires_in` counted to the session’s unchanged end. The presented refresh token now counts as used, and access tokens issued earlier are not upgraded. A partner `token-exchange` has no session to promote. Refusals answer as a refresh does: `400` `invalid_grant` for any refused promotion (another person, an assertion without a recent `auth_time`, a replayed assertion, or an unknown, expired, used or revoked refresh token), `500` `server_error`, or `503` `temporarily_unavailable`. A used refresh token ends the session, as on refresh, but only when the assertion passes the sign-in and its `auth_time` is recent; any other refused promotion consumes nothing. An empty `refresh_token` is `400` `invalid_request`.

**Errors.** Every refusal is `{"error": <code>, "error_description": <text>}` (RFC 6749 §5.2) with `Cache-Control: no-store`. Descriptions are fixed public messages; subject exchange may distinguish suspended providers, authentication predating suspension, missing provisioning and missing MFA. Refresh refusals do not expose the actor’s state. A promotion may also explain missing MFA. Internal reason codes are never returned.

**Authentication:** No bearer token required.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `audience` | string | No |  |
| `client_assertion` | string | No | minLength: 1 |
| `client_assertion_type` | "urn:ietf:params:oauth:client-assertion-type:jwt-bearer" | No |  |
| `client_id` | string | No |  |
| `client_secret` | string | No |  |
| `grant_type` | "client_credentials" / "urn:ietf:params:oauth:grant-type:token-exchange" / "refresh_token" | Yes |  |
| `next_refresh_token` | string | No | pattern: `^yhrt_[A-Za-z0-9_-]{43}$` |
| `refresh_token` | string | No | minLength: 1 |
| `requested_token_type` | "urn:ietf:params:oauth:token-type:access_token" | No |  |
| `subject_token` | string | No |  |
| `subject_token_type` | "urn:ietf:params:oauth:token-type:id_token" / "urn:ietf:params:oauth:token-type:jwt" | No |  |

Additional fields are not accepted.

**Request example:**

```json
{
  "client_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "client_secret": "cs_live_abc123placeholder",
  "grant_type": "client_credentials"
}
```

### oauth-token Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `access_token` | string | Yes | minLength: 1 |
| `expires_in` | integer | Yes | maximum: 9007199254740991; exclusiveMinimum: 0 |
| `issued_token_type` | "urn:ietf:params:oauth:token-type:access_token" | Yes |  |
| `refresh_token` | string | No | minLength: 1 |
| `session_expires_in` | integer | No | maximum: 9007199254740991; exclusiveMinimum: 0 |
| `token_type` | "Bearer" | Yes |  |

Additional fields are not accepted.


### oauth-token Response 400 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `error` | "invalid_request" / "invalid_client" / "invalid_grant" / "unsupported_grant_type" / "temporarily_unavailable" / "server_error" | Yes |  |
| `error_description` | string | Yes |  |

Additional fields are not accepted.


### oauth-token Response 401 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `error` | "invalid_request" / "invalid_client" / "invalid_grant" / "unsupported_grant_type" / "temporarily_unavailable" / "server_error" | Yes |  |
| `error_description` | string | Yes |  |

Additional fields are not accepted.


### oauth-token Response 500 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `error` | "invalid_request" / "invalid_client" / "invalid_grant" / "unsupported_grant_type" / "temporarily_unavailable" / "server_error" | Yes |  |
| `error_description` | string | Yes |  |

Additional fields are not accepted.


### oauth-token Response 503 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `error` | "invalid_request" / "invalid_client" / "invalid_grant" / "unsupported_grant_type" / "temporarily_unavailable" / "server_error" | Yes |  |
| `error_description` | string | Yes |  |

Additional fields are not accepted.


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJiOGUyZjFhMCJ9.sig",
    "expires_in": 3600,
    "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
    "token_type": "Bearer"
  }
  ```
- `400` — The request was refused. On `/oauth/token`, `error` is `invalid_request` (malformed body, or a refused subject token or client), `invalid_grant` (every refused refresh) or `unsupported_grant_type`. On `/oauth/revoke` it is `invalid_request`.

  ```json
  {
    "error": "invalid_grant",
    "error_description": "The authorization grant or refresh token is invalid, expired or revoked."
  }
  ```
- `401` — Client authentication failed (`invalid_client`).

  ```json
  {
    "error": "invalid_client",
    "error_description": "Client authentication failed."
  }
  ```
- `500` — Unexpected server error (`server_error`).

  ```json
  {
    "error": "server_error",
    "error_description": "The server encountered an unexpected error."
  }
  ```
- `503` — The service is temporarily unavailable (`temporarily_unavailable`); retry later.

  ```json
  {
    "error": "temporarily_unavailable",
    "error_description": "The service is temporarily unavailable. Try again later."
  }
  ```

## Me

### GET /me/capabilities

**Get current capabilities**

Returns the current effective RBAC projection: flat capability list and per-grant scope/propagation tuples. Source is the request context populated by AuthGuard; capabilities are resolved against current authority, not read from token claims. Grant anchor_kind is always returned, defaulting to explicit.

**Authentication:** Bearer token required.

### me-capabilities Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `capabilities` | string[] | Yes |  |
| `context` | string or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `scope_grants` | object or object[] | Yes |  |
| `subject` | 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)$` |
| `subject_kind` | "user" / "service" / "system" | Yes |  |

Additional fields are not accepted.

##### application/json body.capabilities

Type: `string[]`. 

###### application/json body.capabilities item

Type: `string`. pattern: `^[a-z0-9]+(?:[._][a-z0-9]+)*$`; minLength: 1

##### application/json body.context

At least one alternative must match.

###### application/json body.context: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.context: alternative 2

Type: `null`. 

##### application/json body.scope_grants

Type: `object or object[]`. 

###### application/json body.scope_grants item

At least one alternative must match.

###### application/json body.scope_grants item: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `anchor_kind` | "explicit" | Yes |  |
| `capabilities` | string[] | Yes |  |
| `propagation` | "self" / "subtree" | Yes |  |
| `scope` | string | Yes | pattern: `^(enterprises\|platform-operators\|clients)\/([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})$` |

Additional fields are not accepted.

###### application/json body.scope_grants item: alternative 1.capabilities

Type: `string[]`. 

###### application/json body.scope_grants item: alternative 1.capabilities item

Type: `string`. pattern: `^[a-z0-9]+(?:[._][a-z0-9]+)*$`; minLength: 1

###### application/json body.scope_grants item: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `anchor_kind` | "enterprise_wildcard" | Yes |  |
| `capabilities` | string[] | Yes |  |
| `propagation` | "subtree" | Yes |  |
| `scope` | string | Yes | pattern: `^(enterprises\|platform-operators)\/([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})$` |

Additional fields are not accepted.

###### application/json body.scope_grants item: alternative 2.capabilities

Type: `string[]`. 

###### application/json body.scope_grants item: alternative 2.capabilities item

Type: `string`. pattern: `^[a-z0-9]+(?:[._][a-z0-9]+)*$`; minLength: 1


### me-capabilities 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.


### me-capabilities Response 401 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.


### me-capabilities Response 403 schema

Content type: `application/json`.

See [response 401 schema](#me-capabilities-response-401-schema).


### me-capabilities Response 500 schema

Content type: `application/json`.

See [response 401 schema](#me-capabilities-response-401-schema).


### me-capabilities Response 502 schema

Content type: `application/json`.

See [response 400 schema](#me-capabilities-response-400-schema).


### me-capabilities Response 503 schema

Content type: `application/json`.

See [response 400 schema](#me-capabilities-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "capabilities": [
      "withdrawals.create",
      "deposits.read",
      "clients.read"
    ],
    "context": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "identity_source": "platform-managed",
    "scope_grants": [
      {
        "anchor_kind": "explicit",
        "capabilities": [
          "withdrawals.create",
          "deposits.read"
        ],
        "propagation": "subtree",
        "scope": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      }
    ],
    "subject": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "subject_kind": "user"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /me/navigation

**Get navigation sections**

Returns UI-friendly section visibility based on the caller's capabilities. The frontend uses this to build the sidebar without embedding an RBAC matrix. Optional `?scope=` selects a platform-operator, enterprise or client context. Visibility comes from effective authority hydrated by AuthGuard, not claims embedded in the token. With scoped grants, capabilities are filtered by coverage of the selected context; an explicit context with no covered capabilities returns 403.

**Authentication:** Bearer token required.

**Parameters:**

- `scope` `string` (query)

### me-navigation Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `context` | string or null | Yes |  |
| `sections` | object[] | Yes |  |
| `subject` | 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.

##### application/json body.context

At least one alternative must match.

###### application/json body.context: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.context: alternative 2

Type: `null`. 

##### application/json body.sections

Type: `object[]`. 

###### application/json body.sections item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `section` | "wallet_balances" / "treasury" / "transactions" / "end_clients" / "access_control" / "integrations" | Yes |  |
| `visibility` | "enabled" / "read_only" / "hidden" | Yes |  |

Additional fields are not accepted.


### me-navigation 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.


### me-navigation Response 401 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.


### me-navigation Response 403 schema

Content type: `application/json`.

See [response 401 schema](#me-navigation-response-401-schema).


### me-navigation Response 500 schema

Content type: `application/json`.

See [response 401 schema](#me-navigation-response-401-schema).


### me-navigation Response 502 schema

Content type: `application/json`.

See [response 400 schema](#me-navigation-response-400-schema).


### me-navigation Response 503 schema

Content type: `application/json`.

See [response 400 schema](#me-navigation-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "context": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "sections": [
      {
        "section": "wallet_balances",
        "visibility": "enabled"
      },
      {
        "section": "treasury",
        "visibility": "enabled"
      },
      {
        "section": "transactions",
        "visibility": "enabled"
      },
      {
        "section": "end_clients",
        "visibility": "read_only"
      },
      {
        "section": "access_control",
        "visibility": "hidden"
      },
      {
        "section": "integrations",
        "visibility": "hidden"
      }
    ],
    "subject": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /me/profile

**Get current session profile**

Returns display metadata for the authenticated principal and its session-bound workspace. Requires authentication but no users.read or enterprises.read capability. Targets are derived exclusively from the verified session; arbitrary principal or workspace IDs cannot be supplied. Metadata lookup failures return null display fields; a bound workspace ref remains present. Service/system principals have null display name and email.

**Authentication:** Bearer token required.

### me-profile Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `principal` | object | Yes | No additional fields |
| `workspace` | object or null | Yes |  |

Additional fields are not accepted.

##### application/json body.principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `display_name` | string or null | Yes |  |
| `email` | string or null | Yes |  |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |

Additional fields are not accepted.

###### application/json body.principal.display_name

At least one alternative must match.

###### application/json body.principal.display_name: alternative 1

Type: `string`. 

###### application/json body.principal.display_name: alternative 2

Type: `null`. 

###### application/json body.principal.email

At least one alternative must match.

###### application/json body.principal.email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.principal.email: alternative 2

Type: `null`. 

##### application/json body.workspace

At least one alternative must match.

###### application/json body.workspace: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `display_name` | string or null | Yes |  |
| `ref` | string | Yes | pattern: `^(enterprises\|platform-operators\|clients)\/([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})$` |

Additional fields are not accepted.

###### application/json body.workspace: alternative 1.display_name

At least one alternative must match.

###### application/json body.workspace: alternative 1.display_name: alternative 1

Type: `string`. 

###### application/json body.workspace: alternative 1.display_name: alternative 2

Type: `null`. 

###### application/json body.workspace: alternative 2

Type: `null`.


| Response header | Type | Description |
| --- | --- | --- |
| `Cache-Control` | "private, no-store" |  |

### me-profile 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.


### me-profile Response 401 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.


### me-profile Response 403 schema

Content type: `application/json`.

See [response 401 schema](#me-profile-response-401-schema).


### me-profile Response 500 schema

Content type: `application/json`.

See [response 401 schema](#me-profile-response-401-schema).


### me-profile Response 502 schema

Content type: `application/json`.

See [response 400 schema](#me-profile-response-400-schema).


### me-profile Response 503 schema

Content type: `application/json`.

See [response 400 schema](#me-profile-response-400-schema).


**Responses:**

- `200` — Operation succeeded.
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Enterprises

### GET /enterprises

**List enterprises**

Lists enterprises under an `enterprise_wildcard` grant anchored at `platform-operators/<id>` for `enterprises.list`. Holding the capability on a narrower scope is insufficient and returns `403 forbidden_capability_scope`. Each row includes `first_access_method` and `iam_hosting`; both are null when the onboarding record is absent or unavailable. Only platform staff can list, so rows always carry `kyc_source`, `kyb_source` and `kyb_state_reason`.

**Required capability:** `enterprises.list`

**Authentication:** Bearer token required.

**Parameters:**

- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.
- `admission_state` `string` (query)
- `restriction_state` `string` (query)
- `restriction_kind` `string` (query)
- `jurisdiction` `string` (query)

### enterprises-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `admission_state` | "admission_review" / "admitted" / "operational" / "restricted" / "offboarding" / "terminated" | Yes |  |
| `created_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))$` |
| `default_master_account` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `external_id` | string or null | No |  |
| `first_access_method` | "magic_link" / "passkey_enrolment" / "enterprise_idp" or null | Yes |  |
| `iam_hosting` | "enterprise" / "platform" or null | Yes |  |
| `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)$` |
| `jurisdiction` | string | Yes | pattern: `^[A-Z]{2}$`; minLength: 2; maxLength: 2 |
| `jurisdiction_selected` | boolean | Yes |  |
| `kyb_source` | "bootstrap" / "sumsub" or null | No | Present only for callers with platform-wide `enterprises.read` authority; omitted for tenant callers. |
| `kyb_stage` | "form_k_ready" / "verified" or null | Yes |  |
| `kyb_state` | "not_started" / "in_progress" / "submitted" / "in_review" / "resubmission_required" / "form_k_ready" / "verified" / "rejected" or null | Yes |  |
| `kyb_state_reason` | string or null | No | Present only for callers with platform-wide `enterprises.read` authority; omitted for tenant callers. |
| `kyb_state_updated_at` | string or null | Yes |  |
| `kyc_source` | "bootstrap" / "sumsub" or null | No | Present only for callers with platform-wide `enterprises.read` authority; omitted for tenant callers. |
| `kyc_stage` | "verified" or null | Yes |  |
| `legal_form` | string or null | Yes |  |
| `legal_name` | string | Yes | minLength: 1 |
| `metadata` | object or null | No |  |
| `resource` | "enterprise" | Yes |  |
| `restriction_kind` | "restricted" / "suspended" or null | Yes |  |
| `restriction_reason` | string or null | Yes |  |
| `restriction_state` | "none" / "restricted" | Yes |  |
| `terminated_at` | string or null | Yes |  |
| `termination_reason` | string or null | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

###### application/json body.items item.default_master_account

At least one alternative must match.

###### application/json body.items item.default_master_account: alternative 1

Type: `string`. pattern: `^(master-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})$`

###### application/json body.items item.default_master_account: alternative 2

Type: `null`. 

###### application/json body.items item.external_id

At least one alternative must match.

###### application/json body.items item.external_id: alternative 1

Type: `string`. 

###### application/json body.items item.external_id: alternative 2

Type: `null`. 

###### application/json body.items item.first_access_method

At least one alternative must match.

###### application/json body.items item.first_access_method: alternative 1

Type: `"magic_link" / "passkey_enrolment" / "enterprise_idp"`. 

###### application/json body.items item.first_access_method: alternative 2

Type: `null`. 

###### application/json body.items item.iam_hosting

At least one alternative must match.

###### application/json body.items item.iam_hosting: alternative 1

Type: `"enterprise" / "platform"`. 

###### application/json body.items item.iam_hosting: alternative 2

Type: `null`. 

###### application/json body.items item.kyb_source

Present only for callers with platform-wide `enterprises.read` authority; omitted for tenant callers.

At least one alternative must match.

###### application/json body.items item.kyb_source: alternative 1

Type: `"bootstrap" / "sumsub"`. 

###### application/json body.items item.kyb_source: alternative 2

Type: `null`. 

###### application/json body.items item.kyb_stage

At least one alternative must match.

###### application/json body.items item.kyb_stage: alternative 1

Type: `"form_k_ready" / "verified"`. 

###### application/json body.items item.kyb_stage: alternative 2

Type: `null`. 

###### application/json body.items item.kyb_state

At least one alternative must match.

###### application/json body.items item.kyb_state: alternative 1

Type: `"not_started" / "in_progress" / "submitted" / "in_review" / "resubmission_required" / "form_k_ready" / "verified" / "rejected"`. 

###### application/json body.items item.kyb_state: alternative 2

Type: `null`. 

###### application/json body.items item.kyb_state_reason

Present only for callers with platform-wide `enterprises.read` authority; omitted for tenant callers.

At least one alternative must match.

###### application/json body.items item.kyb_state_reason: alternative 1

Type: `string`. 

###### application/json body.items item.kyb_state_reason: alternative 2

Type: `null`. 

###### application/json body.items item.kyb_state_updated_at

At least one alternative must match.

###### application/json body.items item.kyb_state_updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.kyb_state_updated_at: alternative 2

Type: `null`. 

###### application/json body.items item.kyc_source

Present only for callers with platform-wide `enterprises.read` authority; omitted for tenant callers.

At least one alternative must match.

###### application/json body.items item.kyc_source: alternative 1

Type: `"bootstrap" / "sumsub"`. 

###### application/json body.items item.kyc_source: alternative 2

Type: `null`. 

###### application/json body.items item.kyc_stage

At least one alternative must match.

###### application/json body.items item.kyc_stage: alternative 1

Type: `"verified"`. 

###### application/json body.items item.kyc_stage: alternative 2

Type: `null`. 

###### application/json body.items item.legal_form

At least one alternative must match.

###### application/json body.items item.legal_form: alternative 1

Type: `string`. minLength: 1

###### application/json body.items item.legal_form: alternative 2

Type: `null`. 

###### application/json body.items item.metadata

At least one alternative must match.

###### application/json body.items item.metadata: alternative 1

Type: `object`. 

###### application/json body.items item.metadata: alternative 2

Type: `null`. 

###### application/json body.items item.restriction_kind

At least one alternative must match.

###### application/json body.items item.restriction_kind: alternative 1

Type: `"restricted" / "suspended"`. 

###### application/json body.items item.restriction_kind: alternative 2

Type: `null`. 

###### application/json body.items item.restriction_reason

At least one alternative must match.

###### application/json body.items item.restriction_reason: alternative 1

Type: `string`. 

###### application/json body.items item.restriction_reason: alternative 2

Type: `null`. 

###### application/json body.items item.terminated_at

At least one alternative must match.

###### application/json body.items item.terminated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.terminated_at: alternative 2

Type: `null`. 

###### application/json body.items item.termination_reason

At least one alternative must match.

###### application/json body.items item.termination_reason: alternative 1

Type: `string`. 

###### application/json body.items item.termination_reason: alternative 2

Type: `null`. 

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. 

###### application/json body.next_page_token: alternative 2

Type: `null`.


### enterprises-list 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.


### enterprises-list Response 401 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.


### enterprises-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-list-response-401-schema).


### enterprises-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-list-response-401-schema).


### enterprises-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#enterprises-list-response-400-schema).


### enterprises-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#enterprises-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "admission_state": "operational",
        "created_at": "2026-05-01T10:00:00Z",
        "default_master_account": "master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "etag": "2026-05-01T10:00:00.000Z",
        "external_id": "ent-ext-0001",
        "first_access_method": "enterprise_idp",
        "iam_hosting": "platform",
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "jurisdiction": "DE",
        "jurisdiction_selected": true,
        "kyb_source": "sumsub",
        "kyb_stage": "verified",
        "kyb_state": "verified",
        "kyb_state_reason": null,
        "kyb_state_updated_at": "2026-05-01T10:00:00.000Z",
        "kyc_source": null,
        "kyc_stage": null,
        "legal_form": "GmbH",
        "legal_name": "Acme Fintech GmbH",
        "metadata": {
          "hq_country": "DE",
          "industry": "fintech"
        },
        "resource": "enterprise",
        "restriction_kind": null,
        "restriction_reason": null,
        "restriction_state": "none",
        "terminated_at": null,
        "termination_reason": null,
        "updated_at": "2026-05-01T10:00:00.000Z"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /enterprises

**Admit enterprise**

Creates the enterprise perimeter and its default master account. Requires a platform-operator binding and an `enterprise_wildcard` grant anchored at `platform-operators/<id>` for `enterprises.create`; otherwise returns `403 forbidden_capability_scope`. Admission does not provision the designated administrator, identity access, roles, or commercial agreements. Call `POST /enterprises/{enterprise_id}/provision` separately to complete that setup.

**Required capability:** `enterprises.create`

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `designated_admin` | object | Yes | No additional fields |
| `external_id` | string or null | No |  |
| `jurisdiction` | string | Yes | pattern: `^[A-Z]{2}$`; minLength: 2; maxLength: 2 |
| `legal_name` | string | Yes | minLength: 1 |
| `metadata` | object or null | No |  |

Additional fields are not accepted.

#### Request body schema.designated_admin

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `display_name` | string or null | No |  |
| `email` | string | Yes | format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$` |

Additional fields are not accepted.

##### Request body schema.designated_admin.display_name

At least one alternative must match.

###### Request body schema.designated_admin.display_name: alternative 1

Type: `string`. 

###### Request body schema.designated_admin.display_name: alternative 2

Type: `null`. 

#### Request body schema.external_id

At least one alternative must match.

##### Request body schema.external_id: alternative 1

Type: `string`. minLength: 1

##### Request body schema.external_id: alternative 2

Type: `null`. 

#### Request body schema.metadata

At least one alternative must match.

##### Request body schema.metadata: alternative 1

Type: `object`. 

##### Request body schema.metadata: alternative 2

Type: `null`.

**Request example:**

```json
{
  "designated_admin": {
    "display_name": "Acme Admin",
    "email": "admin@acme.example"
  },
  "external_id": "ent-ext-0001",
  "jurisdiction": "DE",
  "legal_name": "Acme Fintech GmbH",
  "metadata": {
    "industry": "fintech"
  }
}
```

### enterprises-create Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `enterprise` | object | Yes | No additional fields |
| `master_account` | object | Yes | No additional fields |

Additional fields are not accepted.

##### application/json body.enterprise

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `admission_state` | "admission_review" / "admitted" / "operational" / "restricted" / "offboarding" / "terminated" | Yes |  |
| `created_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))$` |
| `default_master_account` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `external_id` | string or null | No |  |
| `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)$` |
| `jurisdiction` | string | Yes | pattern: `^[A-Z]{2}$`; minLength: 2; maxLength: 2 |
| `jurisdiction_selected` | boolean | Yes |  |
| `kyb_source` | "bootstrap" / "sumsub" or null | Yes |  |
| `kyb_stage` | "form_k_ready" / "verified" or null | Yes |  |
| `kyb_state` | "not_started" / "in_progress" / "submitted" / "in_review" / "resubmission_required" / "form_k_ready" / "verified" / "rejected" or null | Yes |  |
| `kyb_state_reason` | string or null | Yes |  |
| `kyb_state_updated_at` | string or null | Yes |  |
| `kyc_source` | "bootstrap" / "sumsub" or null | Yes |  |
| `kyc_stage` | "verified" or null | Yes |  |
| `legal_form` | string or null | Yes |  |
| `legal_name` | string | Yes | minLength: 1 |
| `metadata` | object or null | No |  |
| `resource` | "enterprise" | Yes |  |
| `restriction_kind` | "restricted" / "suspended" or null | Yes |  |
| `restriction_reason` | string or null | Yes |  |
| `restriction_state` | "none" / "restricted" | Yes |  |
| `terminated_at` | string or null | Yes |  |
| `termination_reason` | string or null | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

###### application/json body.enterprise.default_master_account

At least one alternative must match.

###### application/json body.enterprise.default_master_account: alternative 1

Type: `string`. pattern: `^(master-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})$`

###### application/json body.enterprise.default_master_account: alternative 2

Type: `null`. 

###### application/json body.enterprise.external_id

At least one alternative must match.

###### application/json body.enterprise.external_id: alternative 1

Type: `string`. 

###### application/json body.enterprise.external_id: alternative 2

Type: `null`. 

###### application/json body.enterprise.kyb_source

At least one alternative must match.

###### application/json body.enterprise.kyb_source: alternative 1

Type: `"bootstrap" / "sumsub"`. 

###### application/json body.enterprise.kyb_source: alternative 2

Type: `null`. 

###### application/json body.enterprise.kyb_stage

At least one alternative must match.

###### application/json body.enterprise.kyb_stage: alternative 1

Type: `"form_k_ready" / "verified"`. 

###### application/json body.enterprise.kyb_stage: alternative 2

Type: `null`. 

###### application/json body.enterprise.kyb_state

At least one alternative must match.

###### application/json body.enterprise.kyb_state: alternative 1

Type: `"not_started" / "in_progress" / "submitted" / "in_review" / "resubmission_required" / "form_k_ready" / "verified" / "rejected"`. 

###### application/json body.enterprise.kyb_state: alternative 2

Type: `null`. 

###### application/json body.enterprise.kyb_state_reason

At least one alternative must match.

###### application/json body.enterprise.kyb_state_reason: alternative 1

Type: `string`. 

###### application/json body.enterprise.kyb_state_reason: alternative 2

Type: `null`. 

###### application/json body.enterprise.kyb_state_updated_at

At least one alternative must match.

###### application/json body.enterprise.kyb_state_updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.enterprise.kyb_state_updated_at: alternative 2

Type: `null`. 

###### application/json body.enterprise.kyc_source

At least one alternative must match.

###### application/json body.enterprise.kyc_source: alternative 1

Type: `"bootstrap" / "sumsub"`. 

###### application/json body.enterprise.kyc_source: alternative 2

Type: `null`. 

###### application/json body.enterprise.kyc_stage

At least one alternative must match.

###### application/json body.enterprise.kyc_stage: alternative 1

Type: `"verified"`. 

###### application/json body.enterprise.kyc_stage: alternative 2

Type: `null`. 

###### application/json body.enterprise.legal_form

At least one alternative must match.

###### application/json body.enterprise.legal_form: alternative 1

Type: `string`. minLength: 1

###### application/json body.enterprise.legal_form: alternative 2

Type: `null`. 

###### application/json body.enterprise.metadata

At least one alternative must match.

###### application/json body.enterprise.metadata: alternative 1

Type: `object`. 

###### application/json body.enterprise.metadata: alternative 2

Type: `null`. 

###### application/json body.enterprise.restriction_kind

At least one alternative must match.

###### application/json body.enterprise.restriction_kind: alternative 1

Type: `"restricted" / "suspended"`. 

###### application/json body.enterprise.restriction_kind: alternative 2

Type: `null`. 

###### application/json body.enterprise.restriction_reason

At least one alternative must match.

###### application/json body.enterprise.restriction_reason: alternative 1

Type: `string`. 

###### application/json body.enterprise.restriction_reason: alternative 2

Type: `null`. 

###### application/json body.enterprise.terminated_at

At least one alternative must match.

###### application/json body.enterprise.terminated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.enterprise.terminated_at: alternative 2

Type: `null`. 

###### application/json body.enterprise.termination_reason

At least one alternative must match.

###### application/json body.enterprise.termination_reason: alternative 1

Type: `string`. 

###### application/json body.enterprise.termination_reason: alternative 2

Type: `null`. 

##### application/json body.master_account

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `created_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))$` |
| `display_name` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `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)$` |
| `parent` | string | Yes | pattern: `^(enterprises\|platform-operators)\/([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})$` |
| `resource` | "master_account" | Yes |  |
| `status` | "active" / "suspended" / "closed" | Yes |  |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

###### application/json body.master_account.display_name

At least one alternative must match.

###### application/json body.master_account.display_name: alternative 1

Type: `string`. 

###### application/json body.master_account.display_name: alternative 2

Type: `null`.


### enterprises-create 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.


### enterprises-create Response 401 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.


### enterprises-create Response 403 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-create-response-401-schema).


### enterprises-create Response 409 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-create-response-401-schema).


### enterprises-create Response 500 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-create-response-401-schema).


### enterprises-create Response 502 schema

Content type: `application/json`.

See [response 400 schema](#enterprises-create-response-400-schema).


### enterprises-create Response 503 schema

Content type: `application/json`.

See [response 400 schema](#enterprises-create-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "enterprise": {
      "admission_state": "admitted",
      "created_at": "2026-05-01T10:00:00Z",
      "default_master_account": "master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "etag": "2026-05-01T10:00:00.000Z",
      "external_id": "ent-ext-0001",
      "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "jurisdiction": "DE",
      "jurisdiction_selected": false,
      "kyb_source": null,
      "kyb_stage": null,
      "kyb_state": null,
      "kyb_state_reason": null,
      "kyb_state_updated_at": null,
      "kyc_source": null,
      "kyc_stage": null,
      "legal_form": null,
      "legal_name": "Acme Fintech GmbH",
      "metadata": {
        "hq_country": "DE",
        "industry": "fintech"
      },
      "resource": "enterprise",
      "restriction_kind": null,
      "restriction_reason": null,
      "restriction_state": "none",
      "terminated_at": null,
      "termination_reason": null,
      "updated_at": "2026-05-01T10:00:00.000Z"
    },
    "master_account": {
      "created_at": "2026-05-01T10:00:00Z",
      "display_name": "Acme Fintech GmbH",
      "etag": "2026-05-01T10:00:00.000Z",
      "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "parent": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "resource": "master_account",
      "status": "active",
      "tenant_type": "enterprise",
      "updated_at": "2026-05-01T10:00:00.000Z"
    }
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /enterprises/{enterprise_id}

**Get enterprise**

Carries `first_access_method` from the onboarding record (`magic_link`, `passkey_enrolment` or `enterprise_idp`; `null` when the enterprise has none or it cannot be read), and `iam_hosting`, who hosts the identity stack of an `enterprise_idp` enterprise (`enterprise`: its own; `platform`: the shared platform login; `null` for any other method, for an `enterprise_idp` enterprise whose hosting is not recorded yet, or when there is no readable record). The list rows carry both too. `kyc_source`, `kyb_source` and `kyb_state_reason` (the verification provider and its reason) are present only for callers holding `enterprises.read` through an `enterprise_wildcard` grant anchored at `platform-operators/<id>` (platform staff); a tenant reading its own enterprise receives the response without them.

**Required capability:** `enterprises.read`

**Authentication:** Bearer token required.

**Parameters:**

- `enterprise_id` `string` (path) *(required)*

### enterprises-get Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `admission_state` | "admission_review" / "admitted" / "operational" / "restricted" / "offboarding" / "terminated" | Yes |  |
| `created_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))$` |
| `default_master_account` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `external_id` | string or null | No |  |
| `first_access_method` | "magic_link" / "passkey_enrolment" / "enterprise_idp" or null | Yes |  |
| `iam_hosting` | "enterprise" / "platform" or null | Yes |  |
| `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)$` |
| `jurisdiction` | string | Yes | pattern: `^[A-Z]{2}$`; minLength: 2; maxLength: 2 |
| `jurisdiction_selected` | boolean | Yes |  |
| `kyb_source` | "bootstrap" / "sumsub" or null | No | Present only for callers with platform-wide `enterprises.read` authority; omitted for tenant callers. |
| `kyb_stage` | "form_k_ready" / "verified" or null | Yes |  |
| `kyb_state` | "not_started" / "in_progress" / "submitted" / "in_review" / "resubmission_required" / "form_k_ready" / "verified" / "rejected" or null | Yes |  |
| `kyb_state_reason` | string or null | No | Present only for callers with platform-wide `enterprises.read` authority; omitted for tenant callers. |
| `kyb_state_updated_at` | string or null | Yes |  |
| `kyc_source` | "bootstrap" / "sumsub" or null | No | Present only for callers with platform-wide `enterprises.read` authority; omitted for tenant callers. |
| `kyc_stage` | "verified" or null | Yes |  |
| `legal_form` | string or null | Yes |  |
| `legal_name` | string | Yes | minLength: 1 |
| `metadata` | object or null | No |  |
| `resource` | "enterprise" | Yes |  |
| `restriction_kind` | "restricted" / "suspended" or null | Yes |  |
| `restriction_reason` | string or null | Yes |  |
| `restriction_state` | "none" / "restricted" | Yes |  |
| `terminated_at` | string or null | Yes |  |
| `termination_reason` | string or null | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.default_master_account

At least one alternative must match.

###### application/json body.default_master_account: alternative 1

Type: `string`. pattern: `^(master-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})$`

###### application/json body.default_master_account: alternative 2

Type: `null`. 

##### application/json body.external_id

At least one alternative must match.

###### application/json body.external_id: alternative 1

Type: `string`. 

###### application/json body.external_id: alternative 2

Type: `null`. 

##### application/json body.first_access_method

At least one alternative must match.

###### application/json body.first_access_method: alternative 1

Type: `"magic_link" / "passkey_enrolment" / "enterprise_idp"`. 

###### application/json body.first_access_method: alternative 2

Type: `null`. 

##### application/json body.iam_hosting

At least one alternative must match.

###### application/json body.iam_hosting: alternative 1

Type: `"enterprise" / "platform"`. 

###### application/json body.iam_hosting: alternative 2

Type: `null`. 

##### application/json body.kyb_source

Present only for callers with platform-wide `enterprises.read` authority; omitted for tenant callers.

At least one alternative must match.

###### application/json body.kyb_source: alternative 1

Type: `"bootstrap" / "sumsub"`. 

###### application/json body.kyb_source: alternative 2

Type: `null`. 

##### application/json body.kyb_stage

At least one alternative must match.

###### application/json body.kyb_stage: alternative 1

Type: `"form_k_ready" / "verified"`. 

###### application/json body.kyb_stage: alternative 2

Type: `null`. 

##### application/json body.kyb_state

At least one alternative must match.

###### application/json body.kyb_state: alternative 1

Type: `"not_started" / "in_progress" / "submitted" / "in_review" / "resubmission_required" / "form_k_ready" / "verified" / "rejected"`. 

###### application/json body.kyb_state: alternative 2

Type: `null`. 

##### application/json body.kyb_state_reason

Present only for callers with platform-wide `enterprises.read` authority; omitted for tenant callers.

At least one alternative must match.

###### application/json body.kyb_state_reason: alternative 1

Type: `string`. 

###### application/json body.kyb_state_reason: alternative 2

Type: `null`. 

##### application/json body.kyb_state_updated_at

At least one alternative must match.

###### application/json body.kyb_state_updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.kyb_state_updated_at: alternative 2

Type: `null`. 

##### application/json body.kyc_source

Present only for callers with platform-wide `enterprises.read` authority; omitted for tenant callers.

At least one alternative must match.

###### application/json body.kyc_source: alternative 1

Type: `"bootstrap" / "sumsub"`. 

###### application/json body.kyc_source: alternative 2

Type: `null`. 

##### application/json body.kyc_stage

At least one alternative must match.

###### application/json body.kyc_stage: alternative 1

Type: `"verified"`. 

###### application/json body.kyc_stage: alternative 2

Type: `null`. 

##### application/json body.legal_form

At least one alternative must match.

###### application/json body.legal_form: alternative 1

Type: `string`. minLength: 1

###### application/json body.legal_form: alternative 2

Type: `null`. 

##### application/json body.metadata

At least one alternative must match.

###### application/json body.metadata: alternative 1

Type: `object`. 

###### application/json body.metadata: alternative 2

Type: `null`. 

##### application/json body.restriction_kind

At least one alternative must match.

###### application/json body.restriction_kind: alternative 1

Type: `"restricted" / "suspended"`. 

###### application/json body.restriction_kind: alternative 2

Type: `null`. 

##### application/json body.restriction_reason

At least one alternative must match.

###### application/json body.restriction_reason: alternative 1

Type: `string`. 

###### application/json body.restriction_reason: alternative 2

Type: `null`. 

##### application/json body.terminated_at

At least one alternative must match.

###### application/json body.terminated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.terminated_at: alternative 2

Type: `null`. 

##### application/json body.termination_reason

At least one alternative must match.

###### application/json body.termination_reason: alternative 1

Type: `string`. 

###### application/json body.termination_reason: alternative 2

Type: `null`.


### enterprises-get 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.


### enterprises-get Response 401 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.


### enterprises-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-get-response-401-schema).


### enterprises-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-get-response-401-schema).


### enterprises-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-get-response-401-schema).


### enterprises-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#enterprises-get-response-400-schema).


### enterprises-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#enterprises-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "admission_state": "operational",
    "created_at": "2026-05-01T10:00:00Z",
    "default_master_account": "master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "etag": "2026-05-01T10:00:00.000Z",
    "external_id": "ent-ext-0001",
    "first_access_method": "enterprise_idp",
    "iam_hosting": "platform",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "jurisdiction": "DE",
    "jurisdiction_selected": true,
    "kyb_stage": "verified",
    "kyb_state": "verified",
    "kyb_state_updated_at": "2026-05-01T10:00:00.000Z",
    "kyc_stage": null,
    "legal_form": "GmbH",
    "legal_name": "Acme Fintech GmbH",
    "metadata": {
      "hq_country": "DE",
      "industry": "fintech"
    },
    "resource": "enterprise",
    "restriction_kind": null,
    "restriction_reason": null,
    "restriction_state": "none",
    "terminated_at": null,
    "termination_reason": null,
    "updated_at": "2026-05-01T10:00:00.000Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /enterprises/{enterprise_id}/close

**Close enterprise**

Platform-actor-only; enterprise-scoped actors cannot perform this action. Permanently terminates the enterprise perimeter. A reason is required and audited. Returns the updated enterprise resource. A `503` with reason `termination_outcome_unknown` means the enterprise’s access is already closed but its termination is unconfirmed: repeat the request. A `409` with reason `enterprise_already_terminated` on the repeat confirms the close.

**Required capability:** `enterprises.terminate`

**Authentication:** Bearer token required.

**Parameters:**

- `enterprise_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `reason` | string | Yes | minLength: 3; maxLength: 2000 |

Additional fields are not accepted.

**Request example:**

```json
{
  "reason": "Sanctions screening hit under review (case CMP-1042)"
}
```

### enterprises-close Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `admission_state` | "admission_review" / "admitted" / "operational" / "restricted" / "offboarding" / "terminated" | Yes |  |
| `created_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))$` |
| `default_master_account` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `external_id` | string or null | No |  |
| `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)$` |
| `jurisdiction` | string | Yes | pattern: `^[A-Z]{2}$`; minLength: 2; maxLength: 2 |
| `jurisdiction_selected` | boolean | Yes |  |
| `kyb_source` | "bootstrap" / "sumsub" or null | Yes |  |
| `kyb_stage` | "form_k_ready" / "verified" or null | Yes |  |
| `kyb_state` | "not_started" / "in_progress" / "submitted" / "in_review" / "resubmission_required" / "form_k_ready" / "verified" / "rejected" or null | Yes |  |
| `kyb_state_reason` | string or null | Yes |  |
| `kyb_state_updated_at` | string or null | Yes |  |
| `kyc_source` | "bootstrap" / "sumsub" or null | Yes |  |
| `kyc_stage` | "verified" or null | Yes |  |
| `legal_form` | string or null | Yes |  |
| `legal_name` | string | Yes | minLength: 1 |
| `metadata` | object or null | No |  |
| `resource` | "enterprise" | Yes |  |
| `restriction_kind` | "restricted" / "suspended" or null | Yes |  |
| `restriction_reason` | string or null | Yes |  |
| `restriction_state` | "none" / "restricted" | Yes |  |
| `terminated_at` | string or null | Yes |  |
| `termination_reason` | string or null | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.default_master_account

At least one alternative must match.

###### application/json body.default_master_account: alternative 1

Type: `string`. pattern: `^(master-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})$`

###### application/json body.default_master_account: alternative 2

Type: `null`. 

##### application/json body.external_id

At least one alternative must match.

###### application/json body.external_id: alternative 1

Type: `string`. 

###### application/json body.external_id: alternative 2

Type: `null`. 

##### application/json body.kyb_source

At least one alternative must match.

###### application/json body.kyb_source: alternative 1

Type: `"bootstrap" / "sumsub"`. 

###### application/json body.kyb_source: alternative 2

Type: `null`. 

##### application/json body.kyb_stage

At least one alternative must match.

###### application/json body.kyb_stage: alternative 1

Type: `"form_k_ready" / "verified"`. 

###### application/json body.kyb_stage: alternative 2

Type: `null`. 

##### application/json body.kyb_state

At least one alternative must match.

###### application/json body.kyb_state: alternative 1

Type: `"not_started" / "in_progress" / "submitted" / "in_review" / "resubmission_required" / "form_k_ready" / "verified" / "rejected"`. 

###### application/json body.kyb_state: alternative 2

Type: `null`. 

##### application/json body.kyb_state_reason

At least one alternative must match.

###### application/json body.kyb_state_reason: alternative 1

Type: `string`. 

###### application/json body.kyb_state_reason: alternative 2

Type: `null`. 

##### application/json body.kyb_state_updated_at

At least one alternative must match.

###### application/json body.kyb_state_updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.kyb_state_updated_at: alternative 2

Type: `null`. 

##### application/json body.kyc_source

At least one alternative must match.

###### application/json body.kyc_source: alternative 1

Type: `"bootstrap" / "sumsub"`. 

###### application/json body.kyc_source: alternative 2

Type: `null`. 

##### application/json body.kyc_stage

At least one alternative must match.

###### application/json body.kyc_stage: alternative 1

Type: `"verified"`. 

###### application/json body.kyc_stage: alternative 2

Type: `null`. 

##### application/json body.legal_form

At least one alternative must match.

###### application/json body.legal_form: alternative 1

Type: `string`. minLength: 1

###### application/json body.legal_form: alternative 2

Type: `null`. 

##### application/json body.metadata

At least one alternative must match.

###### application/json body.metadata: alternative 1

Type: `object`. 

###### application/json body.metadata: alternative 2

Type: `null`. 

##### application/json body.restriction_kind

At least one alternative must match.

###### application/json body.restriction_kind: alternative 1

Type: `"restricted" / "suspended"`. 

###### application/json body.restriction_kind: alternative 2

Type: `null`. 

##### application/json body.restriction_reason

At least one alternative must match.

###### application/json body.restriction_reason: alternative 1

Type: `string`. 

###### application/json body.restriction_reason: alternative 2

Type: `null`. 

##### application/json body.terminated_at

At least one alternative must match.

###### application/json body.terminated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.terminated_at: alternative 2

Type: `null`. 

##### application/json body.termination_reason

At least one alternative must match.

###### application/json body.termination_reason: alternative 1

Type: `string`. 

###### application/json body.termination_reason: alternative 2

Type: `null`.


### enterprises-close 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.


### enterprises-close Response 401 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.


### enterprises-close Response 403 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-close-response-401-schema).


### enterprises-close Response 404 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-close-response-401-schema).


### enterprises-close Response 409 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-close-response-401-schema).


### enterprises-close Response 500 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-close-response-401-schema).


### enterprises-close Response 502 schema

Content type: `application/json`.

See [response 400 schema](#enterprises-close-response-400-schema).


### enterprises-close Response 503 schema

Content type: `application/json`.

See [response 400 schema](#enterprises-close-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "admission_state": "terminated",
    "created_at": "2026-05-01T10:00:00Z",
    "default_master_account": "master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "etag": "2026-05-01T10:00:00.000Z",
    "external_id": "ent-ext-0001",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "jurisdiction": "DE",
    "jurisdiction_selected": true,
    "kyb_source": "sumsub",
    "kyb_stage": "verified",
    "kyb_state": "verified",
    "kyb_state_reason": null,
    "kyb_state_updated_at": "2026-05-01T10:00:00.000Z",
    "kyc_source": null,
    "kyc_stage": null,
    "legal_form": "GmbH",
    "legal_name": "Acme Fintech GmbH",
    "metadata": {
      "hq_country": "DE",
      "industry": "fintech"
    },
    "resource": "enterprise",
    "restriction_kind": null,
    "restriction_reason": null,
    "restriction_state": "none",
    "terminated_at": "2026-05-01T10:00:00Z",
    "termination_reason": "Sanctions screening hit under review (case CMP-1042)",
    "updated_at": "2026-05-01T10:00:00.000Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /enterprises/{enterprise_id}/first-access

**Read enterprise first-access status**

Returns registration readiness for an enterprise using `enterprise_idp` first access, whether its provisioning administrator has bound an identity, and the latest first-access command delivery. This applies to both enterprise-hosted and platform-hosted identity stacks. Delivery is null if no delivery exists or that lookup is unavailable. Returns `404` for another first-access method. Requires a platform-operator binding and `enterprises.provision` on an `enterprise_wildcard` grant anchored at `platform-operators/<id>`.

**Required capability:** `enterprises.provision`

**Authentication:** Bearer token required.

**Parameters:**

- `enterprise_id` `string` (path) *(required)*

### enterprises-first-access Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `conflict_reason` | string or null | Yes |  |
| `failing_step` | "identity_provider" / "probe" / "service_account" / "identity_subscription" / "command_subscription" or null | Yes |  |
| `last_delivery` | object or null | Yes |  |
| `last_event_id` | string or null | Yes |  |
| `state` | "waiting_for_stack" / "ready" / "bound" / "conflict" | Yes |  |

Additional fields are not accepted.

##### application/json body.conflict_reason

At least one alternative must match.

###### application/json body.conflict_reason: alternative 1

Type: `string`. 

###### application/json body.conflict_reason: alternative 2

Type: `null`. 

##### application/json body.failing_step

At least one alternative must match.

###### application/json body.failing_step: alternative 1

Type: `"identity_provider" / "probe" / "service_account" / "identity_subscription" / "command_subscription"`. 

###### application/json body.failing_step: alternative 2

Type: `null`. 

##### application/json body.last_delivery

At least one alternative must match.

###### application/json body.last_delivery: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `attempted_at` | string or string or null | Yes |  |
| `delivery_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)$` |
| `status` | "pending" / "delivered" / "failed" / "retrying" / "dlq" | Yes |  |
| `subscription_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.

###### application/json body.last_delivery: alternative 1.attempted_at

At least one alternative must match.

###### application/json body.last_delivery: alternative 1.attempted_at: alternative 1

At least one alternative must match.

###### application/json body.last_delivery: alternative 1.attempted_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.last_delivery: alternative 1.attempted_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.last_delivery: alternative 1.attempted_at: alternative 2

Type: `null`. 

###### application/json body.last_delivery: alternative 2

Type: `null`. 

##### application/json body.last_event_id

At least one alternative must match.

###### application/json body.last_event_id: alternative 1

Type: `string`. 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)$`

###### application/json body.last_event_id: alternative 2

Type: `null`.


### enterprises-first-access 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.


### enterprises-first-access Response 401 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.


### enterprises-first-access Response 403 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-first-access-response-401-schema).


### enterprises-first-access Response 404 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-first-access-response-401-schema).


### enterprises-first-access Response 500 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-first-access-response-401-schema).


### enterprises-first-access Response 502 schema

Content type: `application/json`.

See [response 400 schema](#enterprises-first-access-response-400-schema).


### enterprises-first-access Response 503 schema

Content type: `application/json`.

See [response 400 schema](#enterprises-first-access-response-400-schema).


**Responses:**

- `200` — Operation succeeded.
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /enterprises/{enterprise_id}/first-access/resend

**Resend enterprise first access**

Resends access to the provisioned administrator. Requires a platform-operator binding and an `enterprise_wildcard` grant anchored at `platform-operators/<id>` for `enterprises.provision`. Send no request body. For `enterprise_idp`, the identity stack must be ready and provisioning must have created the administrator; the response contains the emitted `event_id`. That path is limited to one resend per user per five minutes. For a hosted first-access method, returns the enterprise, administrator and first-access delivery result. Hosted resend is unavailable in production (`409 state_conflict`, `data.reason = not_supported`).

**Required capability:** `enterprises.provision`

**Authentication:** Bearer token required.

**Parameters:**

- `enterprise_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

### enterprises-resend-create Response 201 schema

Content type: `application/json`.

#### application/json body

At least one alternative must match.

##### application/json body: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `enterprise_ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |
| `first_access` | object | Yes | No additional fields |
| `human_actor_id` | string | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 1.first_access

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `method` | "magic_link" / "passkey_enrolment" / "enterprise_idp" | Yes |  |
| `sent` | boolean | Yes |  |

Additional fields are not accepted.

##### application/json body: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `event_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.


### enterprises-resend-create 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.


### enterprises-resend-create Response 401 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.


### enterprises-resend-create Response 403 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-resend-create-response-401-schema).


### enterprises-resend-create Response 404 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-resend-create-response-401-schema).


### enterprises-resend-create Response 409 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-resend-create-response-401-schema).


### enterprises-resend-create Response 429 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-resend-create-response-401-schema).


### enterprises-resend-create Response 500 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-resend-create-response-401-schema).


### enterprises-resend-create Response 502 schema

Content type: `application/json`.

See [response 400 schema](#enterprises-resend-create-response-400-schema).


### enterprises-resend-create Response 503 schema

Content type: `application/json`.

See [response 400 schema](#enterprises-resend-create-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "event_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `429` — The request was rate limited; retry according to the returned backoff information.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /enterprises/{enterprise_id}/provision

**Provision an admitted enterprise**

Configures the designated administrator, roles and commercial agreements for an enterprise already created with `POST /enterprises`. Requires a platform-operator binding and an `enterprise_wildcard` grant anchored at `platform-operators/<id>` for `enterprises.provision`. Supply the contracted `service_types` and `platform_fee_bps`; `enterprise_fee_bps` defaults to 0. Provisioning is resumable: completed work is reported as `reused` on later runs. Production supports `first_access_method=enterprise_idp`; hosted magic-link and passkey first access are deployment-dependent. An `enterprise_idp` response reports `first_access.sent=false`; once its identity stack is ready, use the first-access resend endpoint to issue the command.

**Required capability:** `enterprises.provision`

**Authentication:** Bearer token required.

**Parameters:**

- `enterprise_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `designated_admin` | object | Yes | No additional fields |
| `effective_from` | string | No | 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))$` |
| `enterprise_fee_bps` | integer | No | minimum: 0; maximum: 10000; default: `0` |
| `first_access_method` | "magic_link" / "passkey_enrolment" / "enterprise_idp" | No |  |
| `iam_hosting` | "enterprise" / "platform" | No |  |
| `platform_fee_bps` | integer | Yes | minimum: 0; maximum: 10000 |
| `service_types` | "custody" / "conversion" / "withdrawal_crypto" / "withdrawal_fiat" / "deposit_crypto" / "deposit_fiat" / "internal_transfer" / "staking"[] | Yes | minItems: 1 |

Additional fields are not accepted.

#### Request body schema.designated_admin

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `display_name` | string or null | No |  |
| `email` | string | Yes | format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`; maxLength: 254 |

Additional fields are not accepted.

##### Request body schema.designated_admin.display_name

At least one alternative must match.

###### Request body schema.designated_admin.display_name: alternative 1

Type: `string`. minLength: 1; maxLength: 200

###### Request body schema.designated_admin.display_name: alternative 2

Type: `null`. 

#### Request body schema.service_types

Type: `"custody" / "conversion" / "withdrawal_crypto" / "withdrawal_fiat" / "deposit_crypto" / "deposit_fiat" / "internal_transfer" / "staking"[]`. minItems: 1

##### Request body schema.service_types item

Type: `"custody" / "conversion" / "withdrawal_crypto" / "withdrawal_fiat" / "deposit_crypto" / "deposit_fiat" / "internal_transfer" / "staking"`.

**Request example:**

```json
{
  "designated_admin": {
    "display_name": "Acme Admin",
    "email": "admin@acme.example"
  },
  "enterprise_fee_bps": 0,
  "first_access_method": "enterprise_idp",
  "iam_hosting": "enterprise",
  "platform_fee_bps": 10,
  "service_types": [
    "custody",
    "deposit_fiat",
    "withdrawal_fiat"
  ]
}
```

### enterprises-provision Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `admin_role_id` | string | Yes |  |
| `enterprise_ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |
| `first_access` | object | Yes | No additional fields |
| `human_actor_id` | string | Yes |  |
| `identity_provider_id` | string or null | Yes |  |
| `integration_role_id` | string or null | Yes |  |
| `operator_role_id` | string | Yes |  |
| `steps` | object[] | Yes |  |

Additional fields are not accepted.

##### application/json body.first_access

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `method` | "magic_link" / "passkey_enrolment" / "enterprise_idp" | Yes |  |
| `sent` | boolean | Yes |  |

Additional fields are not accepted.

##### application/json body.identity_provider_id

At least one alternative must match.

###### application/json body.identity_provider_id: alternative 1

Type: `string`. 

###### application/json body.identity_provider_id: alternative 2

Type: `null`. 

##### application/json body.integration_role_id

At least one alternative must match.

###### application/json body.integration_role_id: alternative 1

Type: `string`. 

###### application/json body.integration_role_id: alternative 2

Type: `null`. 

##### application/json body.steps

Type: `object[]`. 

###### application/json body.steps item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `status` | "completed" / "reused" | Yes |  |
| `step` | string | Yes |  |

Additional fields are not accepted.


### enterprises-provision 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.


### enterprises-provision Response 401 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.


### enterprises-provision Response 403 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-provision-response-401-schema).


### enterprises-provision Response 404 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-provision-response-401-schema).


### enterprises-provision Response 409 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-provision-response-401-schema).


### enterprises-provision Response 500 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-provision-response-401-schema).


### enterprises-provision Response 502 schema

Content type: `application/json`.

See [response 400 schema](#enterprises-provision-response-400-schema).


### enterprises-provision Response 503 schema

Content type: `application/json`.

See [response 400 schema](#enterprises-provision-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "admin_role_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "enterprise_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "first_access": {
      "method": "enterprise_idp",
      "sent": false
    },
    "human_actor_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "identity_provider_id": null,
    "integration_role_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "operator_role_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "steps": [
      {
        "status": "completed",
        "step": "human_actor"
      }
    ]
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /enterprises/{enterprise_id}/reactivate

**Reactivate enterprise**

Platform-actor-only; enterprise-scoped actors cannot perform this action. Lifts a restriction or suspension and re-enables hosted logins. A reason is required and audited. A `503` with reason `reactivation_outcome_unknown` means the reactivation is unconfirmed and nothing was handed back; edge tried to put the restriction back. Repeat the request; if the repeat is refused as not restricted, suspend the enterprise and reactivate it again.

**Required capability:** `enterprises.reactivate`

**Authentication:** Bearer token required.

**Parameters:**

- `enterprise_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `reason` | string | Yes | minLength: 3; maxLength: 2000 |

Additional fields are not accepted.

**Request example:**

```json
{
  "reason": "Sanctions screening hit under review (case CMP-1042)"
}
```

### enterprises-reactivate Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `admission_state` | "admission_review" / "admitted" / "operational" / "restricted" / "offboarding" / "terminated" | Yes |  |
| `created_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))$` |
| `default_master_account` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `external_id` | string or null | No |  |
| `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)$` |
| `jurisdiction` | string | Yes | pattern: `^[A-Z]{2}$`; minLength: 2; maxLength: 2 |
| `jurisdiction_selected` | boolean | Yes |  |
| `kyb_source` | "bootstrap" / "sumsub" or null | Yes |  |
| `kyb_stage` | "form_k_ready" / "verified" or null | Yes |  |
| `kyb_state` | "not_started" / "in_progress" / "submitted" / "in_review" / "resubmission_required" / "form_k_ready" / "verified" / "rejected" or null | Yes |  |
| `kyb_state_reason` | string or null | Yes |  |
| `kyb_state_updated_at` | string or null | Yes |  |
| `kyc_source` | "bootstrap" / "sumsub" or null | Yes |  |
| `kyc_stage` | "verified" or null | Yes |  |
| `legal_form` | string or null | Yes |  |
| `legal_name` | string | Yes | minLength: 1 |
| `metadata` | object or null | No |  |
| `resource` | "enterprise" | Yes |  |
| `restriction_kind` | "restricted" / "suspended" or null | Yes |  |
| `restriction_reason` | string or null | Yes |  |
| `restriction_state` | "none" / "restricted" | Yes |  |
| `terminated_at` | string or null | Yes |  |
| `termination_reason` | string or null | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.default_master_account

At least one alternative must match.

###### application/json body.default_master_account: alternative 1

Type: `string`. pattern: `^(master-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})$`

###### application/json body.default_master_account: alternative 2

Type: `null`. 

##### application/json body.external_id

At least one alternative must match.

###### application/json body.external_id: alternative 1

Type: `string`. 

###### application/json body.external_id: alternative 2

Type: `null`. 

##### application/json body.kyb_source

At least one alternative must match.

###### application/json body.kyb_source: alternative 1

Type: `"bootstrap" / "sumsub"`. 

###### application/json body.kyb_source: alternative 2

Type: `null`. 

##### application/json body.kyb_stage

At least one alternative must match.

###### application/json body.kyb_stage: alternative 1

Type: `"form_k_ready" / "verified"`. 

###### application/json body.kyb_stage: alternative 2

Type: `null`. 

##### application/json body.kyb_state

At least one alternative must match.

###### application/json body.kyb_state: alternative 1

Type: `"not_started" / "in_progress" / "submitted" / "in_review" / "resubmission_required" / "form_k_ready" / "verified" / "rejected"`. 

###### application/json body.kyb_state: alternative 2

Type: `null`. 

##### application/json body.kyb_state_reason

At least one alternative must match.

###### application/json body.kyb_state_reason: alternative 1

Type: `string`. 

###### application/json body.kyb_state_reason: alternative 2

Type: `null`. 

##### application/json body.kyb_state_updated_at

At least one alternative must match.

###### application/json body.kyb_state_updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.kyb_state_updated_at: alternative 2

Type: `null`. 

##### application/json body.kyc_source

At least one alternative must match.

###### application/json body.kyc_source: alternative 1

Type: `"bootstrap" / "sumsub"`. 

###### application/json body.kyc_source: alternative 2

Type: `null`. 

##### application/json body.kyc_stage

At least one alternative must match.

###### application/json body.kyc_stage: alternative 1

Type: `"verified"`. 

###### application/json body.kyc_stage: alternative 2

Type: `null`. 

##### application/json body.legal_form

At least one alternative must match.

###### application/json body.legal_form: alternative 1

Type: `string`. minLength: 1

###### application/json body.legal_form: alternative 2

Type: `null`. 

##### application/json body.metadata

At least one alternative must match.

###### application/json body.metadata: alternative 1

Type: `object`. 

###### application/json body.metadata: alternative 2

Type: `null`. 

##### application/json body.restriction_kind

At least one alternative must match.

###### application/json body.restriction_kind: alternative 1

Type: `"restricted" / "suspended"`. 

###### application/json body.restriction_kind: alternative 2

Type: `null`. 

##### application/json body.restriction_reason

At least one alternative must match.

###### application/json body.restriction_reason: alternative 1

Type: `string`. 

###### application/json body.restriction_reason: alternative 2

Type: `null`. 

##### application/json body.terminated_at

At least one alternative must match.

###### application/json body.terminated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.terminated_at: alternative 2

Type: `null`. 

##### application/json body.termination_reason

At least one alternative must match.

###### application/json body.termination_reason: alternative 1

Type: `string`. 

###### application/json body.termination_reason: alternative 2

Type: `null`.


### enterprises-reactivate 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.


### enterprises-reactivate Response 401 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.


### enterprises-reactivate Response 403 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-reactivate-response-401-schema).


### enterprises-reactivate Response 404 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-reactivate-response-401-schema).


### enterprises-reactivate Response 409 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-reactivate-response-401-schema).


### enterprises-reactivate Response 500 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-reactivate-response-401-schema).


### enterprises-reactivate Response 502 schema

Content type: `application/json`.

See [response 400 schema](#enterprises-reactivate-response-400-schema).


### enterprises-reactivate Response 503 schema

Content type: `application/json`.

See [response 400 schema](#enterprises-reactivate-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "admission_state": "operational",
    "created_at": "2026-05-01T10:00:00Z",
    "default_master_account": "master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "etag": "2026-05-01T10:00:00.000Z",
    "external_id": "ent-ext-0001",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "jurisdiction": "DE",
    "jurisdiction_selected": true,
    "kyb_source": "sumsub",
    "kyb_stage": "verified",
    "kyb_state": "verified",
    "kyb_state_reason": null,
    "kyb_state_updated_at": "2026-05-01T10:00:00.000Z",
    "kyc_source": null,
    "kyc_stage": null,
    "legal_form": "GmbH",
    "legal_name": "Acme Fintech GmbH",
    "metadata": {
      "hq_country": "DE",
      "industry": "fintech"
    },
    "resource": "enterprise",
    "restriction_kind": null,
    "restriction_reason": null,
    "restriction_state": "none",
    "terminated_at": null,
    "termination_reason": null,
    "updated_at": "2026-05-01T10:00:00.000Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /enterprises/{enterprise_id}/restrict

**Restrict enterprise**

Platform-actor-only; enterprise-scoped actors cannot perform this action. Pauses the enterprise’s operations while its people keep signing in and reading. A reason is required and audited. Returns the updated enterprise resource.

**Required capability:** `enterprises.restrict`

**Authentication:** Bearer token required.

**Parameters:**

- `enterprise_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `reason` | string | Yes | minLength: 3; maxLength: 2000 |

Additional fields are not accepted.

**Request example:**

```json
{
  "reason": "Sanctions screening hit under review (case CMP-1042)"
}
```

### enterprises-restrict Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `admission_state` | "admission_review" / "admitted" / "operational" / "restricted" / "offboarding" / "terminated" | Yes |  |
| `created_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))$` |
| `default_master_account` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `external_id` | string or null | No |  |
| `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)$` |
| `jurisdiction` | string | Yes | pattern: `^[A-Z]{2}$`; minLength: 2; maxLength: 2 |
| `jurisdiction_selected` | boolean | Yes |  |
| `kyb_source` | "bootstrap" / "sumsub" or null | Yes |  |
| `kyb_stage` | "form_k_ready" / "verified" or null | Yes |  |
| `kyb_state` | "not_started" / "in_progress" / "submitted" / "in_review" / "resubmission_required" / "form_k_ready" / "verified" / "rejected" or null | Yes |  |
| `kyb_state_reason` | string or null | Yes |  |
| `kyb_state_updated_at` | string or null | Yes |  |
| `kyc_source` | "bootstrap" / "sumsub" or null | Yes |  |
| `kyc_stage` | "verified" or null | Yes |  |
| `legal_form` | string or null | Yes |  |
| `legal_name` | string | Yes | minLength: 1 |
| `metadata` | object or null | No |  |
| `resource` | "enterprise" | Yes |  |
| `restriction_kind` | "restricted" / "suspended" or null | Yes |  |
| `restriction_reason` | string or null | Yes |  |
| `restriction_state` | "none" / "restricted" | Yes |  |
| `terminated_at` | string or null | Yes |  |
| `termination_reason` | string or null | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.default_master_account

At least one alternative must match.

###### application/json body.default_master_account: alternative 1

Type: `string`. pattern: `^(master-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})$`

###### application/json body.default_master_account: alternative 2

Type: `null`. 

##### application/json body.external_id

At least one alternative must match.

###### application/json body.external_id: alternative 1

Type: `string`. 

###### application/json body.external_id: alternative 2

Type: `null`. 

##### application/json body.kyb_source

At least one alternative must match.

###### application/json body.kyb_source: alternative 1

Type: `"bootstrap" / "sumsub"`. 

###### application/json body.kyb_source: alternative 2

Type: `null`. 

##### application/json body.kyb_stage

At least one alternative must match.

###### application/json body.kyb_stage: alternative 1

Type: `"form_k_ready" / "verified"`. 

###### application/json body.kyb_stage: alternative 2

Type: `null`. 

##### application/json body.kyb_state

At least one alternative must match.

###### application/json body.kyb_state: alternative 1

Type: `"not_started" / "in_progress" / "submitted" / "in_review" / "resubmission_required" / "form_k_ready" / "verified" / "rejected"`. 

###### application/json body.kyb_state: alternative 2

Type: `null`. 

##### application/json body.kyb_state_reason

At least one alternative must match.

###### application/json body.kyb_state_reason: alternative 1

Type: `string`. 

###### application/json body.kyb_state_reason: alternative 2

Type: `null`. 

##### application/json body.kyb_state_updated_at

At least one alternative must match.

###### application/json body.kyb_state_updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.kyb_state_updated_at: alternative 2

Type: `null`. 

##### application/json body.kyc_source

At least one alternative must match.

###### application/json body.kyc_source: alternative 1

Type: `"bootstrap" / "sumsub"`. 

###### application/json body.kyc_source: alternative 2

Type: `null`. 

##### application/json body.kyc_stage

At least one alternative must match.

###### application/json body.kyc_stage: alternative 1

Type: `"verified"`. 

###### application/json body.kyc_stage: alternative 2

Type: `null`. 

##### application/json body.legal_form

At least one alternative must match.

###### application/json body.legal_form: alternative 1

Type: `string`. minLength: 1

###### application/json body.legal_form: alternative 2

Type: `null`. 

##### application/json body.metadata

At least one alternative must match.

###### application/json body.metadata: alternative 1

Type: `object`. 

###### application/json body.metadata: alternative 2

Type: `null`. 

##### application/json body.restriction_kind

At least one alternative must match.

###### application/json body.restriction_kind: alternative 1

Type: `"restricted" / "suspended"`. 

###### application/json body.restriction_kind: alternative 2

Type: `null`. 

##### application/json body.restriction_reason

At least one alternative must match.

###### application/json body.restriction_reason: alternative 1

Type: `string`. 

###### application/json body.restriction_reason: alternative 2

Type: `null`. 

##### application/json body.terminated_at

At least one alternative must match.

###### application/json body.terminated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.terminated_at: alternative 2

Type: `null`. 

##### application/json body.termination_reason

At least one alternative must match.

###### application/json body.termination_reason: alternative 1

Type: `string`. 

###### application/json body.termination_reason: alternative 2

Type: `null`.


### enterprises-restrict 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.


### enterprises-restrict Response 401 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.


### enterprises-restrict Response 403 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-restrict-response-401-schema).


### enterprises-restrict Response 404 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-restrict-response-401-schema).


### enterprises-restrict Response 409 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-restrict-response-401-schema).


### enterprises-restrict Response 500 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-restrict-response-401-schema).


### enterprises-restrict Response 502 schema

Content type: `application/json`.

See [response 400 schema](#enterprises-restrict-response-400-schema).


### enterprises-restrict Response 503 schema

Content type: `application/json`.

See [response 400 schema](#enterprises-restrict-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "admission_state": "operational",
    "created_at": "2026-05-01T10:00:00Z",
    "default_master_account": "master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "etag": "2026-05-01T10:00:00.000Z",
    "external_id": "ent-ext-0001",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "jurisdiction": "DE",
    "jurisdiction_selected": true,
    "kyb_source": "sumsub",
    "kyb_stage": "verified",
    "kyb_state": "verified",
    "kyb_state_reason": null,
    "kyb_state_updated_at": "2026-05-01T10:00:00.000Z",
    "kyc_source": null,
    "kyc_stage": null,
    "legal_form": "GmbH",
    "legal_name": "Acme Fintech GmbH",
    "metadata": {
      "hq_country": "DE",
      "industry": "fintech"
    },
    "resource": "enterprise",
    "restriction_kind": "restricted",
    "restriction_reason": "Sanctions screening hit under review (case CMP-1042)",
    "restriction_state": "restricted",
    "terminated_at": null,
    "termination_reason": null,
    "updated_at": "2026-05-01T10:00:00.000Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /enterprises/{enterprise_id}/suspend

**Suspend enterprise**

Platform-actor-only; enterprise-scoped actors cannot perform this action. Requires `enterprises.restrict`. Restricts the enterprise and ends its hosted logins until it is reactivated. A reason is required and audited. Returns the updated enterprise resource. Suspending an enterprise that is already suspended ends its access again and succeeds; the standing suspension and its reason are kept, and the new reason is not recorded on the enterprise. A `503` with reason `suspension_outcome_unknown` means the suspension may or may not have landed and its logins and sessions were not ended: repeat the request.

**Required capability:** `enterprises.restrict`

**Authentication:** Bearer token required.

**Parameters:**

- `enterprise_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `reason` | string | Yes | minLength: 3; maxLength: 2000 |

Additional fields are not accepted.

**Request example:**

```json
{
  "reason": "Sanctions screening hit under review (case CMP-1042)"
}
```

### enterprises-suspend Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `admission_state` | "admission_review" / "admitted" / "operational" / "restricted" / "offboarding" / "terminated" | Yes |  |
| `created_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))$` |
| `default_master_account` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `external_id` | string or null | No |  |
| `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)$` |
| `jurisdiction` | string | Yes | pattern: `^[A-Z]{2}$`; minLength: 2; maxLength: 2 |
| `jurisdiction_selected` | boolean | Yes |  |
| `kyb_source` | "bootstrap" / "sumsub" or null | Yes |  |
| `kyb_stage` | "form_k_ready" / "verified" or null | Yes |  |
| `kyb_state` | "not_started" / "in_progress" / "submitted" / "in_review" / "resubmission_required" / "form_k_ready" / "verified" / "rejected" or null | Yes |  |
| `kyb_state_reason` | string or null | Yes |  |
| `kyb_state_updated_at` | string or null | Yes |  |
| `kyc_source` | "bootstrap" / "sumsub" or null | Yes |  |
| `kyc_stage` | "verified" or null | Yes |  |
| `legal_form` | string or null | Yes |  |
| `legal_name` | string | Yes | minLength: 1 |
| `metadata` | object or null | No |  |
| `resource` | "enterprise" | Yes |  |
| `restriction_kind` | "restricted" / "suspended" or null | Yes |  |
| `restriction_reason` | string or null | Yes |  |
| `restriction_state` | "none" / "restricted" | Yes |  |
| `terminated_at` | string or null | Yes |  |
| `termination_reason` | string or null | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.default_master_account

At least one alternative must match.

###### application/json body.default_master_account: alternative 1

Type: `string`. pattern: `^(master-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})$`

###### application/json body.default_master_account: alternative 2

Type: `null`. 

##### application/json body.external_id

At least one alternative must match.

###### application/json body.external_id: alternative 1

Type: `string`. 

###### application/json body.external_id: alternative 2

Type: `null`. 

##### application/json body.kyb_source

At least one alternative must match.

###### application/json body.kyb_source: alternative 1

Type: `"bootstrap" / "sumsub"`. 

###### application/json body.kyb_source: alternative 2

Type: `null`. 

##### application/json body.kyb_stage

At least one alternative must match.

###### application/json body.kyb_stage: alternative 1

Type: `"form_k_ready" / "verified"`. 

###### application/json body.kyb_stage: alternative 2

Type: `null`. 

##### application/json body.kyb_state

At least one alternative must match.

###### application/json body.kyb_state: alternative 1

Type: `"not_started" / "in_progress" / "submitted" / "in_review" / "resubmission_required" / "form_k_ready" / "verified" / "rejected"`. 

###### application/json body.kyb_state: alternative 2

Type: `null`. 

##### application/json body.kyb_state_reason

At least one alternative must match.

###### application/json body.kyb_state_reason: alternative 1

Type: `string`. 

###### application/json body.kyb_state_reason: alternative 2

Type: `null`. 

##### application/json body.kyb_state_updated_at

At least one alternative must match.

###### application/json body.kyb_state_updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.kyb_state_updated_at: alternative 2

Type: `null`. 

##### application/json body.kyc_source

At least one alternative must match.

###### application/json body.kyc_source: alternative 1

Type: `"bootstrap" / "sumsub"`. 

###### application/json body.kyc_source: alternative 2

Type: `null`. 

##### application/json body.kyc_stage

At least one alternative must match.

###### application/json body.kyc_stage: alternative 1

Type: `"verified"`. 

###### application/json body.kyc_stage: alternative 2

Type: `null`. 

##### application/json body.legal_form

At least one alternative must match.

###### application/json body.legal_form: alternative 1

Type: `string`. minLength: 1

###### application/json body.legal_form: alternative 2

Type: `null`. 

##### application/json body.metadata

At least one alternative must match.

###### application/json body.metadata: alternative 1

Type: `object`. 

###### application/json body.metadata: alternative 2

Type: `null`. 

##### application/json body.restriction_kind

At least one alternative must match.

###### application/json body.restriction_kind: alternative 1

Type: `"restricted" / "suspended"`. 

###### application/json body.restriction_kind: alternative 2

Type: `null`. 

##### application/json body.restriction_reason

At least one alternative must match.

###### application/json body.restriction_reason: alternative 1

Type: `string`. 

###### application/json body.restriction_reason: alternative 2

Type: `null`. 

##### application/json body.terminated_at

At least one alternative must match.

###### application/json body.terminated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.terminated_at: alternative 2

Type: `null`. 

##### application/json body.termination_reason

At least one alternative must match.

###### application/json body.termination_reason: alternative 1

Type: `string`. 

###### application/json body.termination_reason: alternative 2

Type: `null`.


### enterprises-suspend 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.


### enterprises-suspend Response 401 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.


### enterprises-suspend Response 403 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-suspend-response-401-schema).


### enterprises-suspend Response 404 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-suspend-response-401-schema).


### enterprises-suspend Response 409 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-suspend-response-401-schema).


### enterprises-suspend Response 500 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-suspend-response-401-schema).


### enterprises-suspend Response 502 schema

Content type: `application/json`.

See [response 400 schema](#enterprises-suspend-response-400-schema).


### enterprises-suspend Response 503 schema

Content type: `application/json`.

See [response 400 schema](#enterprises-suspend-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "admission_state": "operational",
    "created_at": "2026-05-01T10:00:00Z",
    "default_master_account": "master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "etag": "2026-05-01T10:00:00.000Z",
    "external_id": "ent-ext-0001",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "jurisdiction": "DE",
    "jurisdiction_selected": true,
    "kyb_source": "sumsub",
    "kyb_stage": "verified",
    "kyb_state": "verified",
    "kyb_state_reason": null,
    "kyb_state_updated_at": "2026-05-01T10:00:00.000Z",
    "kyc_source": null,
    "kyc_stage": null,
    "legal_form": "GmbH",
    "legal_name": "Acme Fintech GmbH",
    "metadata": {
      "hq_country": "DE",
      "industry": "fintech"
    },
    "resource": "enterprise",
    "restriction_kind": "suspended",
    "restriction_reason": "Sanctions screening hit under review (case CMP-1042)",
    "restriction_state": "restricted",
    "terminated_at": null,
    "termination_reason": null,
    "updated_at": "2026-05-01T10:00:00.000Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Master Accounts

### GET /master-accounts

**List master accounts**

List master accounts for a tenant scope. `scope_ref=enterprises/{id}` or `scope_ref=platform-operators/{id}`. The accounts.read grant must cover the requested tenant scope; an existing scope outside authority returns 403 and a missing scope returns 404. Repeat status to filter by multiple states. Page size defaults to 50 and the service caps results at 200.

**Required capability:** `accounts.read`

**Authentication:** Bearer token required.

**Parameters:**

- `scope_ref` `string` (query) *(required)*
- `status` `string` (query)
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### master-accounts-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `created_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))$` |
| `display_name` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `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)$` |
| `resource` | "master_account" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|platform-operators)\/([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})$` |
| `status` | "active" / "suspended" / "closed" | Yes |  |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

###### application/json body.items item.display_name

At least one alternative must match.

###### application/json body.items item.display_name: alternative 1

Type: `string`. 

###### application/json body.items item.display_name: alternative 2

Type: `null`. 

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. 

###### application/json body.next_page_token: alternative 2

Type: `null`.


### master-accounts-list 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.


### master-accounts-list Response 401 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.


### master-accounts-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#master-accounts-list-response-401-schema).


### master-accounts-list Response 404 schema

Content type: `application/json`.

See [response 401 schema](#master-accounts-list-response-401-schema).


### master-accounts-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#master-accounts-list-response-401-schema).


### master-accounts-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#master-accounts-list-response-400-schema).


### master-accounts-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#master-accounts-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "created_at": "2026-05-01T10:00:00Z",
        "display_name": "Primary Settlement Account",
        "etag": "2026-05-01T10:00:00.000Z",
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "resource": "master_account",
        "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "status": "active",
        "tenant_type": "enterprise",
        "updated_at": "2026-05-01T10:00:00Z"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /master-accounts/{master_account_id}

**Get master account**

Returns the master account with its upstream parent exposed as scope_ref. Missing accounts and accounts outside the accounts.read grant return 404.

**Required capability:** `accounts.read`

**Authentication:** Bearer token required.

**Parameters:**

- `master_account_id` `string` (path) *(required)*

### master-accounts-get Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `created_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))$` |
| `display_name` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `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)$` |
| `resource` | "master_account" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|platform-operators)\/([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})$` |
| `status` | "active" / "suspended" / "closed" | Yes |  |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.display_name

At least one alternative must match.

###### application/json body.display_name: alternative 1

Type: `string`. 

###### application/json body.display_name: alternative 2

Type: `null`.


### master-accounts-get 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.


### master-accounts-get Response 401 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.


### master-accounts-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#master-accounts-get-response-401-schema).


### master-accounts-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#master-accounts-get-response-401-schema).


### master-accounts-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#master-accounts-get-response-401-schema).


### master-accounts-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#master-accounts-get-response-400-schema).


### master-accounts-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#master-accounts-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "created_at": "2026-05-01T10:00:00Z",
    "display_name": "Primary Settlement Account",
    "etag": "2026-05-01T10:00:00.000Z",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "resource": "master_account",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "active",
    "tenant_type": "enterprise",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Commercial Agreements

### GET /enterprise-commercial-agreements

**List commercial agreement versions**

Lists versions for one enterprise and one client scope. client_scope defaults to all_clients, which selects only the enterprise-wide agreement series; it does not include every single-client series. single_client requires client_ref belonging to that enterprise. service_type filters bindings; page_size defaults to 100 (maximum 200).

**Required capability:** `commercial_agreements.read`

**Authentication:** Bearer token required.

**Parameters:**

- `enterprise_ref` `string` (query) *(required)*
- `client_scope` `string` (query)
- `client_ref` `string` (query)
- `service_type` `string` (query)
- `page_token` `string` (query) — Opaque cursor returned by a previous page.
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.

### enterprise-commercial-agreements-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `page` | object | Yes | No additional fields |

Additional fields are not accepted.

##### application/json body.page

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.page.items

Type: `object[]`. 

###### application/json body.page.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `client_scope` | object or object | Yes |  |
| `created_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))$` |
| `effective_from` | 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))$` |
| `effective_to` | string or null | Yes |  |
| `enterprise_ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |
| `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)$` |
| `metadata` | object or null | No |  |
| `service_bindings` | object[] | Yes |  |
| `status` | "draft" / "active" / "superseded" | Yes |  |
| `version` | integer | Yes | maximum: 9007199254740991; exclusiveMinimum: 0 |

Additional fields are not accepted.

###### application/json body.page.items item.client_scope

At least one alternative must match.

###### application/json body.page.items item.client_scope: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "all_clients" | Yes |  |

Additional fields are not accepted.

###### application/json body.page.items item.client_scope: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `client_ref` | string | Yes | pattern: `^(clients)\/([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})$` |
| `kind` | "single_client" | Yes |  |

Additional fields are not accepted.

###### application/json body.page.items item.effective_to

At least one alternative must match.

###### application/json body.page.items item.effective_to: alternative 1

Type: `string`. 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))$`

###### application/json body.page.items item.effective_to: alternative 2

Type: `null`. 

###### application/json body.page.items item.metadata

At least one alternative must match.

###### application/json body.page.items item.metadata: alternative 1

Type: `object`. 

###### application/json body.page.items item.metadata: alternative 2

Type: `null`. 

###### application/json body.page.items item.service_bindings

Type: `object[]`. 

###### application/json body.page.items item.service_bindings item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `fee_schedule` | object | Yes | No additional fields |
| `service_type` | "custody" / "conversion" / "withdrawal_crypto" / "withdrawal_fiat" / "deposit_crypto" / "deposit_fiat" / "internal_transfer" / "staking" | Yes |  |

Additional fields are not accepted.

###### application/json body.page.items item.service_bindings item.fee_schedule

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `minimum` | object or null | No |  |
| `maximum` | object or null | No |  |
| `bps` | integer or null | No |  |
| `fixed` | object or null | No |  |
| `metadata` | object or null | No |  |
| `model` | "fixed" / "bps" / "fixed_plus_bps" / "tiered" | Yes |  |
| `rounding_mode` | "half_up" / "up" / "down" or null | No |  |
| `tiers` | object[] or null | No |  |

Additional fields are not accepted.

###### application/json body.page.items item.service_bindings item.fee_schedule.minimum

At least one alternative must match.

###### application/json body.page.items item.service_bindings item.fee_schedule.minimum: alternative 1

| 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.

###### application/json body.page.items item.service_bindings item.fee_schedule.minimum: alternative 2

Type: `null`. 

###### application/json body.page.items item.service_bindings item.fee_schedule.maximum

At least one alternative must match.

###### application/json body.page.items item.service_bindings item.fee_schedule.maximum: alternative 1

| 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.

###### application/json body.page.items item.service_bindings item.fee_schedule.maximum: alternative 2

Type: `null`. 

###### application/json body.page.items item.service_bindings item.fee_schedule.bps

At least one alternative must match.

###### application/json body.page.items item.service_bindings item.fee_schedule.bps: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### application/json body.page.items item.service_bindings item.fee_schedule.bps: alternative 2

Type: `null`. 

###### application/json body.page.items item.service_bindings item.fee_schedule.fixed

At least one alternative must match.

###### application/json body.page.items item.service_bindings item.fee_schedule.fixed: alternative 1

| 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.

###### application/json body.page.items item.service_bindings item.fee_schedule.fixed: alternative 2

Type: `null`. 

###### application/json body.page.items item.service_bindings item.fee_schedule.metadata

At least one alternative must match.

###### application/json body.page.items item.service_bindings item.fee_schedule.metadata: alternative 1

Type: `object`. 

###### application/json body.page.items item.service_bindings item.fee_schedule.metadata: alternative 2

Type: `null`. 

###### application/json body.page.items item.service_bindings item.fee_schedule.rounding_mode

At least one alternative must match.

###### application/json body.page.items item.service_bindings item.fee_schedule.rounding_mode: alternative 1

Type: `"half_up" / "up" / "down"`. 

###### application/json body.page.items item.service_bindings item.fee_schedule.rounding_mode: alternative 2

Type: `null`. 

###### application/json body.page.items item.service_bindings item.fee_schedule.tiers

At least one alternative must match.

###### application/json body.page.items item.service_bindings item.fee_schedule.tiers: alternative 1

Type: `object[]`. 

###### application/json body.page.items item.service_bindings item.fee_schedule.tiers: alternative 1 item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `bps` | integer or null | No |  |
| `fixed` | object or null | No |  |
| `up_to_amount` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.page.items item.service_bindings item.fee_schedule.tiers: alternative 1 item.bps

At least one alternative must match.

###### application/json body.page.items item.service_bindings item.fee_schedule.tiers: alternative 1 item.bps: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### application/json body.page.items item.service_bindings item.fee_schedule.tiers: alternative 1 item.bps: alternative 2

Type: `null`. 

###### application/json body.page.items item.service_bindings item.fee_schedule.tiers: alternative 1 item.fixed

At least one alternative must match.

###### application/json body.page.items item.service_bindings item.fee_schedule.tiers: alternative 1 item.fixed: alternative 1

| 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.

###### application/json body.page.items item.service_bindings item.fee_schedule.tiers: alternative 1 item.fixed: alternative 2

Type: `null`. 

###### application/json body.page.items item.service_bindings item.fee_schedule.tiers: alternative 1 item.up_to_amount

At least one alternative must match.

###### application/json body.page.items item.service_bindings item.fee_schedule.tiers: alternative 1 item.up_to_amount: alternative 1

DecimalString

Type: `string`. pattern: `^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$`

###### application/json body.page.items item.service_bindings item.fee_schedule.tiers: alternative 1 item.up_to_amount: alternative 2

Type: `null`. 

###### application/json body.page.items item.service_bindings item.fee_schedule.tiers: alternative 2

Type: `null`. 

###### application/json body.page.next_page_token

At least one alternative must match.

###### application/json body.page.next_page_token: alternative 1

Type: `string`. 

###### application/json body.page.next_page_token: alternative 2

Type: `null`.


### enterprise-commercial-agreements-list 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.


### enterprise-commercial-agreements-list Response 401 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.


### enterprise-commercial-agreements-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#enterprise-commercial-agreements-list-response-401-schema).


### enterprise-commercial-agreements-list Response 404 schema

Content type: `application/json`.

See [response 401 schema](#enterprise-commercial-agreements-list-response-401-schema).


### enterprise-commercial-agreements-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#enterprise-commercial-agreements-list-response-401-schema).


### enterprise-commercial-agreements-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#enterprise-commercial-agreements-list-response-400-schema).


### enterprise-commercial-agreements-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#enterprise-commercial-agreements-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "page": {
      "items": [
        {
          "client_scope": {
            "kind": "all_clients"
          },
          "created_at": "2026-05-01T10:00:00Z",
          "effective_from": "2026-05-01T10:00:00Z",
          "effective_to": null,
          "enterprise_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
          "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
          "metadata": null,
          "service_bindings": [
            {
              "fee_schedule": {
                "bps": 25,
                "model": "bps"
              },
              "service_type": "conversion"
            }
          ],
          "status": "active",
          "version": 1
        }
      ],
      "next_page_token": null
    }
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /enterprise-commercial-agreements

**Create commercial agreement version**

Creates an active version for the enterprise/client scope. effective_from must not precede the latest version. A new version supersedes the current active version at effective_from. An existing version with the same scope and effective_from is returned unchanged, even if the submitted bindings differ. At least one service binding is required; fee amounts use value and currency.

**Required capability:** `commercial_agreements.create`

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `client_scope` | object or object | Yes |  |
| `effective_from` | string | Yes | format: date-time |
| `enterprise_ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |
| `metadata` | object or null | No |  |
| `service_bindings` | object[] | Yes | minItems: 1 |

Additional fields are not accepted.

#### Request body schema.client_scope

At least one alternative must match.

##### Request body schema.client_scope: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "all_clients" | Yes |  |

Additional fields are not accepted.

##### Request body schema.client_scope: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `client_ref` | string | Yes | pattern: `^(clients)\/([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})$` |
| `kind` | "single_client" | Yes |  |

Additional fields are not accepted.

#### Request body schema.metadata

At least one alternative must match.

##### Request body schema.metadata: alternative 1

Type: `object`. 

##### Request body schema.metadata: alternative 2

Type: `null`. 

#### Request body schema.service_bindings

Type: `object[]`. minItems: 1

##### Request body schema.service_bindings item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `fee_schedule` | object | Yes | No additional fields |
| `service_type` | "custody" / "conversion" / "withdrawal_crypto" / "withdrawal_fiat" / "deposit_crypto" / "deposit_fiat" / "internal_transfer" / "staking" | Yes |  |

Additional fields are not accepted.

###### Request body schema.service_bindings item.fee_schedule

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `minimum` | object or null | No |  |
| `maximum` | object or null | No |  |
| `bps` | integer or null | No |  |
| `fixed` | object or null | No |  |
| `metadata` | object or null | No |  |
| `model` | "fixed" / "bps" / "fixed_plus_bps" / "tiered" | Yes |  |
| `rounding_mode` | "half_up" / "up" / "down" or null | No |  |
| `tiers` | object[] or null | No |  |

Additional fields are not accepted.

###### Request body schema.service_bindings item.fee_schedule.minimum

At least one alternative must match.

###### Request body schema.service_bindings item.fee_schedule.minimum: alternative 1

| 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.service_bindings item.fee_schedule.minimum: alternative 2

Type: `null`. 

###### Request body schema.service_bindings item.fee_schedule.maximum

At least one alternative must match.

###### Request body schema.service_bindings item.fee_schedule.maximum: alternative 1

| 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.service_bindings item.fee_schedule.maximum: alternative 2

Type: `null`. 

###### Request body schema.service_bindings item.fee_schedule.bps

At least one alternative must match.

###### Request body schema.service_bindings item.fee_schedule.bps: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### Request body schema.service_bindings item.fee_schedule.bps: alternative 2

Type: `null`. 

###### Request body schema.service_bindings item.fee_schedule.fixed

At least one alternative must match.

###### Request body schema.service_bindings item.fee_schedule.fixed: alternative 1

| 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.service_bindings item.fee_schedule.fixed: alternative 2

Type: `null`. 

###### Request body schema.service_bindings item.fee_schedule.metadata

At least one alternative must match.

###### Request body schema.service_bindings item.fee_schedule.metadata: alternative 1

Type: `object`. 

###### Request body schema.service_bindings item.fee_schedule.metadata: alternative 2

Type: `null`. 

###### Request body schema.service_bindings item.fee_schedule.rounding_mode

At least one alternative must match.

###### Request body schema.service_bindings item.fee_schedule.rounding_mode: alternative 1

Type: `"half_up" / "up" / "down"`. 

###### Request body schema.service_bindings item.fee_schedule.rounding_mode: alternative 2

Type: `null`. 

###### Request body schema.service_bindings item.fee_schedule.tiers

At least one alternative must match.

###### Request body schema.service_bindings item.fee_schedule.tiers: alternative 1

Type: `object[]`. 

###### Request body schema.service_bindings item.fee_schedule.tiers: alternative 1 item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `bps` | integer or null | No |  |
| `fixed` | object or null | No |  |
| `up_to_amount` | string or null | Yes |  |

Additional fields are not accepted.

###### Request body schema.service_bindings item.fee_schedule.tiers: alternative 1 item.bps

At least one alternative must match.

###### Request body schema.service_bindings item.fee_schedule.tiers: alternative 1 item.bps: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### Request body schema.service_bindings item.fee_schedule.tiers: alternative 1 item.bps: alternative 2

Type: `null`. 

###### Request body schema.service_bindings item.fee_schedule.tiers: alternative 1 item.fixed

At least one alternative must match.

###### Request body schema.service_bindings item.fee_schedule.tiers: alternative 1 item.fixed: alternative 1

| 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.service_bindings item.fee_schedule.tiers: alternative 1 item.fixed: alternative 2

Type: `null`. 

###### Request body schema.service_bindings item.fee_schedule.tiers: alternative 1 item.up_to_amount

At least one alternative must match.

###### Request body schema.service_bindings item.fee_schedule.tiers: alternative 1 item.up_to_amount: alternative 1

DecimalString

Type: `string`. pattern: `^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$`

###### Request body schema.service_bindings item.fee_schedule.tiers: alternative 1 item.up_to_amount: alternative 2

Type: `null`. 

###### Request body schema.service_bindings item.fee_schedule.tiers: alternative 2

Type: `null`.

**Request example:**

```json
{
  "client_scope": {
    "kind": "all_clients"
  },
  "effective_from": "2026-05-01T10:00:00Z",
  "enterprise_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "metadata": null,
  "service_bindings": [
    {
      "fee_schedule": {
        "bps": 25,
        "model": "bps"
      },
      "service_type": "conversion"
    }
  ]
}
```

### enterprise-commercial-agreements-create Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `agreement` | object | Yes | No additional fields |

Additional fields are not accepted.

##### application/json body.agreement

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `client_scope` | object or object | Yes |  |
| `created_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))$` |
| `effective_from` | 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))$` |
| `effective_to` | string or null | Yes |  |
| `enterprise_ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |
| `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)$` |
| `metadata` | object or null | No |  |
| `service_bindings` | object[] | Yes |  |
| `status` | "draft" / "active" / "superseded" | Yes |  |
| `version` | integer | Yes | maximum: 9007199254740991; exclusiveMinimum: 0 |

Additional fields are not accepted.

###### application/json body.agreement.client_scope

At least one alternative must match.

###### application/json body.agreement.client_scope: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "all_clients" | Yes |  |

Additional fields are not accepted.

###### application/json body.agreement.client_scope: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `client_ref` | string | Yes | pattern: `^(clients)\/([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})$` |
| `kind` | "single_client" | Yes |  |

Additional fields are not accepted.

###### application/json body.agreement.effective_to

At least one alternative must match.

###### application/json body.agreement.effective_to: alternative 1

Type: `string`. 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))$`

###### application/json body.agreement.effective_to: alternative 2

Type: `null`. 

###### application/json body.agreement.metadata

At least one alternative must match.

###### application/json body.agreement.metadata: alternative 1

Type: `object`. 

###### application/json body.agreement.metadata: alternative 2

Type: `null`. 

###### application/json body.agreement.service_bindings

Type: `object[]`. 

###### application/json body.agreement.service_bindings item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `fee_schedule` | object | Yes | No additional fields |
| `service_type` | "custody" / "conversion" / "withdrawal_crypto" / "withdrawal_fiat" / "deposit_crypto" / "deposit_fiat" / "internal_transfer" / "staking" | Yes |  |

Additional fields are not accepted.

###### application/json body.agreement.service_bindings item.fee_schedule

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `minimum` | object or null | No |  |
| `maximum` | object or null | No |  |
| `bps` | integer or null | No |  |
| `fixed` | object or null | No |  |
| `metadata` | object or null | No |  |
| `model` | "fixed" / "bps" / "fixed_plus_bps" / "tiered" | Yes |  |
| `rounding_mode` | "half_up" / "up" / "down" or null | No |  |
| `tiers` | object[] or null | No |  |

Additional fields are not accepted.

###### application/json body.agreement.service_bindings item.fee_schedule.minimum

At least one alternative must match.

###### application/json body.agreement.service_bindings item.fee_schedule.minimum: alternative 1

| 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.

###### application/json body.agreement.service_bindings item.fee_schedule.minimum: alternative 2

Type: `null`. 

###### application/json body.agreement.service_bindings item.fee_schedule.maximum

At least one alternative must match.

###### application/json body.agreement.service_bindings item.fee_schedule.maximum: alternative 1

| 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.

###### application/json body.agreement.service_bindings item.fee_schedule.maximum: alternative 2

Type: `null`. 

###### application/json body.agreement.service_bindings item.fee_schedule.bps

At least one alternative must match.

###### application/json body.agreement.service_bindings item.fee_schedule.bps: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### application/json body.agreement.service_bindings item.fee_schedule.bps: alternative 2

Type: `null`. 

###### application/json body.agreement.service_bindings item.fee_schedule.fixed

At least one alternative must match.

###### application/json body.agreement.service_bindings item.fee_schedule.fixed: alternative 1

| 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.

###### application/json body.agreement.service_bindings item.fee_schedule.fixed: alternative 2

Type: `null`. 

###### application/json body.agreement.service_bindings item.fee_schedule.metadata

At least one alternative must match.

###### application/json body.agreement.service_bindings item.fee_schedule.metadata: alternative 1

Type: `object`. 

###### application/json body.agreement.service_bindings item.fee_schedule.metadata: alternative 2

Type: `null`. 

###### application/json body.agreement.service_bindings item.fee_schedule.rounding_mode

At least one alternative must match.

###### application/json body.agreement.service_bindings item.fee_schedule.rounding_mode: alternative 1

Type: `"half_up" / "up" / "down"`. 

###### application/json body.agreement.service_bindings item.fee_schedule.rounding_mode: alternative 2

Type: `null`. 

###### application/json body.agreement.service_bindings item.fee_schedule.tiers

At least one alternative must match.

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1

Type: `object[]`. 

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `bps` | integer or null | No |  |
| `fixed` | object or null | No |  |
| `up_to_amount` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.bps

At least one alternative must match.

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.bps: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.bps: alternative 2

Type: `null`. 

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.fixed

At least one alternative must match.

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.fixed: alternative 1

| 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.

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.fixed: alternative 2

Type: `null`. 

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.up_to_amount

At least one alternative must match.

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.up_to_amount: alternative 1

DecimalString

Type: `string`. pattern: `^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$`

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.up_to_amount: alternative 2

Type: `null`. 

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 2

Type: `null`.


### enterprise-commercial-agreements-create 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.


### enterprise-commercial-agreements-create Response 401 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.


### enterprise-commercial-agreements-create Response 403 schema

Content type: `application/json`.

See [response 401 schema](#enterprise-commercial-agreements-create-response-401-schema).


### enterprise-commercial-agreements-create Response 404 schema

Content type: `application/json`.

See [response 401 schema](#enterprise-commercial-agreements-create-response-401-schema).


### enterprise-commercial-agreements-create Response 409 schema

Content type: `application/json`.

See [response 401 schema](#enterprise-commercial-agreements-create-response-401-schema).


### enterprise-commercial-agreements-create Response 500 schema

Content type: `application/json`.

See [response 401 schema](#enterprise-commercial-agreements-create-response-401-schema).


### enterprise-commercial-agreements-create Response 502 schema

Content type: `application/json`.

See [response 400 schema](#enterprise-commercial-agreements-create-response-400-schema).


### enterprise-commercial-agreements-create Response 503 schema

Content type: `application/json`.

See [response 400 schema](#enterprise-commercial-agreements-create-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "agreement": {
      "client_scope": {
        "kind": "all_clients"
      },
      "created_at": "2026-05-01T10:00:00Z",
      "effective_from": "2026-05-01T10:00:00Z",
      "effective_to": null,
      "enterprise_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "metadata": null,
      "service_bindings": [
        {
          "fee_schedule": {
            "bps": 25,
            "model": "bps"
          },
          "service_type": "conversion"
        }
      ],
      "status": "active",
      "version": 1
    }
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /enterprise-commercial-agreements/{agreement_id}

**Get commercial agreement version**

**Required capability:** `commercial_agreements.read`

**Authentication:** Bearer token required.

**Parameters:**

- `agreement_id` `string` (path) *(required)*

### enterprise-commercial-agreements-get Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `agreement` | object | Yes | No additional fields |

Additional fields are not accepted.

##### application/json body.agreement

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `client_scope` | object or object | Yes |  |
| `created_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))$` |
| `effective_from` | 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))$` |
| `effective_to` | string or null | Yes |  |
| `enterprise_ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |
| `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)$` |
| `metadata` | object or null | No |  |
| `service_bindings` | object[] | Yes |  |
| `status` | "draft" / "active" / "superseded" | Yes |  |
| `version` | integer | Yes | maximum: 9007199254740991; exclusiveMinimum: 0 |

Additional fields are not accepted.

###### application/json body.agreement.client_scope

At least one alternative must match.

###### application/json body.agreement.client_scope: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "all_clients" | Yes |  |

Additional fields are not accepted.

###### application/json body.agreement.client_scope: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `client_ref` | string | Yes | pattern: `^(clients)\/([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})$` |
| `kind` | "single_client" | Yes |  |

Additional fields are not accepted.

###### application/json body.agreement.effective_to

At least one alternative must match.

###### application/json body.agreement.effective_to: alternative 1

Type: `string`. 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))$`

###### application/json body.agreement.effective_to: alternative 2

Type: `null`. 

###### application/json body.agreement.metadata

At least one alternative must match.

###### application/json body.agreement.metadata: alternative 1

Type: `object`. 

###### application/json body.agreement.metadata: alternative 2

Type: `null`. 

###### application/json body.agreement.service_bindings

Type: `object[]`. 

###### application/json body.agreement.service_bindings item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `fee_schedule` | object | Yes | No additional fields |
| `service_type` | "custody" / "conversion" / "withdrawal_crypto" / "withdrawal_fiat" / "deposit_crypto" / "deposit_fiat" / "internal_transfer" / "staking" | Yes |  |

Additional fields are not accepted.

###### application/json body.agreement.service_bindings item.fee_schedule

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `minimum` | object or null | No |  |
| `maximum` | object or null | No |  |
| `bps` | integer or null | No |  |
| `fixed` | object or null | No |  |
| `metadata` | object or null | No |  |
| `model` | "fixed" / "bps" / "fixed_plus_bps" / "tiered" | Yes |  |
| `rounding_mode` | "half_up" / "up" / "down" or null | No |  |
| `tiers` | object[] or null | No |  |

Additional fields are not accepted.

###### application/json body.agreement.service_bindings item.fee_schedule.minimum

At least one alternative must match.

###### application/json body.agreement.service_bindings item.fee_schedule.minimum: alternative 1

| 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.

###### application/json body.agreement.service_bindings item.fee_schedule.minimum: alternative 2

Type: `null`. 

###### application/json body.agreement.service_bindings item.fee_schedule.maximum

At least one alternative must match.

###### application/json body.agreement.service_bindings item.fee_schedule.maximum: alternative 1

| 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.

###### application/json body.agreement.service_bindings item.fee_schedule.maximum: alternative 2

Type: `null`. 

###### application/json body.agreement.service_bindings item.fee_schedule.bps

At least one alternative must match.

###### application/json body.agreement.service_bindings item.fee_schedule.bps: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### application/json body.agreement.service_bindings item.fee_schedule.bps: alternative 2

Type: `null`. 

###### application/json body.agreement.service_bindings item.fee_schedule.fixed

At least one alternative must match.

###### application/json body.agreement.service_bindings item.fee_schedule.fixed: alternative 1

| 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.

###### application/json body.agreement.service_bindings item.fee_schedule.fixed: alternative 2

Type: `null`. 

###### application/json body.agreement.service_bindings item.fee_schedule.metadata

At least one alternative must match.

###### application/json body.agreement.service_bindings item.fee_schedule.metadata: alternative 1

Type: `object`. 

###### application/json body.agreement.service_bindings item.fee_schedule.metadata: alternative 2

Type: `null`. 

###### application/json body.agreement.service_bindings item.fee_schedule.rounding_mode

At least one alternative must match.

###### application/json body.agreement.service_bindings item.fee_schedule.rounding_mode: alternative 1

Type: `"half_up" / "up" / "down"`. 

###### application/json body.agreement.service_bindings item.fee_schedule.rounding_mode: alternative 2

Type: `null`. 

###### application/json body.agreement.service_bindings item.fee_schedule.tiers

At least one alternative must match.

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1

Type: `object[]`. 

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `bps` | integer or null | No |  |
| `fixed` | object or null | No |  |
| `up_to_amount` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.bps

At least one alternative must match.

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.bps: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.bps: alternative 2

Type: `null`. 

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.fixed

At least one alternative must match.

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.fixed: alternative 1

| 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.

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.fixed: alternative 2

Type: `null`. 

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.up_to_amount

At least one alternative must match.

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.up_to_amount: alternative 1

DecimalString

Type: `string`. pattern: `^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$`

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.up_to_amount: alternative 2

Type: `null`. 

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 2

Type: `null`.


### enterprise-commercial-agreements-get 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.


### enterprise-commercial-agreements-get Response 401 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.


### enterprise-commercial-agreements-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#enterprise-commercial-agreements-get-response-401-schema).


### enterprise-commercial-agreements-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#enterprise-commercial-agreements-get-response-401-schema).


### enterprise-commercial-agreements-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#enterprise-commercial-agreements-get-response-401-schema).


### enterprise-commercial-agreements-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#enterprise-commercial-agreements-get-response-400-schema).


### enterprise-commercial-agreements-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#enterprise-commercial-agreements-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "agreement": {
      "client_scope": {
        "kind": "all_clients"
      },
      "created_at": "2026-05-01T10:00:00Z",
      "effective_from": "2026-05-01T10:00:00Z",
      "effective_to": null,
      "enterprise_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "metadata": null,
      "service_bindings": [
        {
          "fee_schedule": {
            "bps": 25,
            "model": "bps"
          },
          "service_type": "conversion"
        }
      ],
      "status": "active",
      "version": 1
    }
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /enterprise-commercial-agreements/{agreement_id}/supersede

**Supersede commercial agreement version**

Closes an agreement version by setting status to superseded and effective_to. Requires commercial_agreements.manage and read access because the controller reads the current agreement first. effective_to must not precede effective_from or be more than five minutes in the past. An already closed version returns 409.

**Required capability:** `commercial_agreements.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `agreement_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `effective_to` | string | Yes | format: date-time |

Additional fields are not accepted.

**Request example:**

```json
{
  "effective_to": "2026-05-01T10:00:00Z"
}
```

### enterprise-commercial-agreements-supersede Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `agreement` | object | Yes | No additional fields |

Additional fields are not accepted.

##### application/json body.agreement

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `client_scope` | object or object | Yes |  |
| `created_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))$` |
| `effective_from` | 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))$` |
| `effective_to` | string or null | Yes |  |
| `enterprise_ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |
| `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)$` |
| `metadata` | object or null | No |  |
| `service_bindings` | object[] | Yes |  |
| `status` | "draft" / "active" / "superseded" | Yes |  |
| `version` | integer | Yes | maximum: 9007199254740991; exclusiveMinimum: 0 |

Additional fields are not accepted.

###### application/json body.agreement.client_scope

At least one alternative must match.

###### application/json body.agreement.client_scope: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "all_clients" | Yes |  |

Additional fields are not accepted.

###### application/json body.agreement.client_scope: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `client_ref` | string | Yes | pattern: `^(clients)\/([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})$` |
| `kind` | "single_client" | Yes |  |

Additional fields are not accepted.

###### application/json body.agreement.effective_to

At least one alternative must match.

###### application/json body.agreement.effective_to: alternative 1

Type: `string`. 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))$`

###### application/json body.agreement.effective_to: alternative 2

Type: `null`. 

###### application/json body.agreement.metadata

At least one alternative must match.

###### application/json body.agreement.metadata: alternative 1

Type: `object`. 

###### application/json body.agreement.metadata: alternative 2

Type: `null`. 

###### application/json body.agreement.service_bindings

Type: `object[]`. 

###### application/json body.agreement.service_bindings item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `fee_schedule` | object | Yes | No additional fields |
| `service_type` | "custody" / "conversion" / "withdrawal_crypto" / "withdrawal_fiat" / "deposit_crypto" / "deposit_fiat" / "internal_transfer" / "staking" | Yes |  |

Additional fields are not accepted.

###### application/json body.agreement.service_bindings item.fee_schedule

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `minimum` | object or null | No |  |
| `maximum` | object or null | No |  |
| `bps` | integer or null | No |  |
| `fixed` | object or null | No |  |
| `metadata` | object or null | No |  |
| `model` | "fixed" / "bps" / "fixed_plus_bps" / "tiered" | Yes |  |
| `rounding_mode` | "half_up" / "up" / "down" or null | No |  |
| `tiers` | object[] or null | No |  |

Additional fields are not accepted.

###### application/json body.agreement.service_bindings item.fee_schedule.minimum

At least one alternative must match.

###### application/json body.agreement.service_bindings item.fee_schedule.minimum: alternative 1

| 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.

###### application/json body.agreement.service_bindings item.fee_schedule.minimum: alternative 2

Type: `null`. 

###### application/json body.agreement.service_bindings item.fee_schedule.maximum

At least one alternative must match.

###### application/json body.agreement.service_bindings item.fee_schedule.maximum: alternative 1

| 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.

###### application/json body.agreement.service_bindings item.fee_schedule.maximum: alternative 2

Type: `null`. 

###### application/json body.agreement.service_bindings item.fee_schedule.bps

At least one alternative must match.

###### application/json body.agreement.service_bindings item.fee_schedule.bps: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### application/json body.agreement.service_bindings item.fee_schedule.bps: alternative 2

Type: `null`. 

###### application/json body.agreement.service_bindings item.fee_schedule.fixed

At least one alternative must match.

###### application/json body.agreement.service_bindings item.fee_schedule.fixed: alternative 1

| 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.

###### application/json body.agreement.service_bindings item.fee_schedule.fixed: alternative 2

Type: `null`. 

###### application/json body.agreement.service_bindings item.fee_schedule.metadata

At least one alternative must match.

###### application/json body.agreement.service_bindings item.fee_schedule.metadata: alternative 1

Type: `object`. 

###### application/json body.agreement.service_bindings item.fee_schedule.metadata: alternative 2

Type: `null`. 

###### application/json body.agreement.service_bindings item.fee_schedule.rounding_mode

At least one alternative must match.

###### application/json body.agreement.service_bindings item.fee_schedule.rounding_mode: alternative 1

Type: `"half_up" / "up" / "down"`. 

###### application/json body.agreement.service_bindings item.fee_schedule.rounding_mode: alternative 2

Type: `null`. 

###### application/json body.agreement.service_bindings item.fee_schedule.tiers

At least one alternative must match.

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1

Type: `object[]`. 

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `bps` | integer or null | No |  |
| `fixed` | object or null | No |  |
| `up_to_amount` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.bps

At least one alternative must match.

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.bps: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.bps: alternative 2

Type: `null`. 

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.fixed

At least one alternative must match.

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.fixed: alternative 1

| 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.

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.fixed: alternative 2

Type: `null`. 

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.up_to_amount

At least one alternative must match.

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.up_to_amount: alternative 1

DecimalString

Type: `string`. pattern: `^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$`

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 1 item.up_to_amount: alternative 2

Type: `null`. 

###### application/json body.agreement.service_bindings item.fee_schedule.tiers: alternative 2

Type: `null`.


### enterprise-commercial-agreements-supersede 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.


### enterprise-commercial-agreements-supersede Response 401 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.


### enterprise-commercial-agreements-supersede Response 403 schema

Content type: `application/json`.

See [response 401 schema](#enterprise-commercial-agreements-supersede-response-401-schema).


### enterprise-commercial-agreements-supersede Response 404 schema

Content type: `application/json`.

See [response 401 schema](#enterprise-commercial-agreements-supersede-response-401-schema).


### enterprise-commercial-agreements-supersede Response 409 schema

Content type: `application/json`.

See [response 401 schema](#enterprise-commercial-agreements-supersede-response-401-schema).


### enterprise-commercial-agreements-supersede Response 500 schema

Content type: `application/json`.

See [response 401 schema](#enterprise-commercial-agreements-supersede-response-401-schema).


### enterprise-commercial-agreements-supersede Response 502 schema

Content type: `application/json`.

See [response 400 schema](#enterprise-commercial-agreements-supersede-response-400-schema).


### enterprise-commercial-agreements-supersede Response 503 schema

Content type: `application/json`.

See [response 400 schema](#enterprise-commercial-agreements-supersede-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "agreement": {
      "client_scope": {
        "kind": "all_clients"
      },
      "created_at": "2026-05-01T10:00:00Z",
      "effective_from": "2026-05-01T10:00:00Z",
      "effective_to": "2026-05-01T10:00:00Z",
      "enterprise_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "metadata": null,
      "service_bindings": [
        {
          "fee_schedule": {
            "bps": 25,
            "model": "bps"
          },
          "service_type": "conversion"
        }
      ],
      "status": "superseded",
      "version": 1
    }
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Clients

### GET /clients

**List clients**

List tenant clients under an enterprise scope. `kyc_source`, `kyb_source` and `kyb_state_reason` (the verification provider and its reason) are present only for callers holding this operation’s capability through an `enterprise_wildcard` grant anchored at `platform-operators/<id>` (platform staff); other callers receive the client without them.

**Required capability:** `clients.read`

**Authentication:** Bearer token required.

**Parameters:**

- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.
- `scope_ref` `string` (query) *(required)*
- `status` `string` (query)
- `external_id` `string` (query)
- `q` `string` (query)
- `verification` `string` (query)

### clients-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `created_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))$` |
| `default_client_account` | string or null | No |  |
| `display_name` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `external_id` | string or null | No |  |
| `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)$` |
| `kyb_source` | "bootstrap" / "sumsub" or null | No | Present only for callers with platform-wide authority; omitted for tenant callers. |
| `kyb_stage` | "form_k_ready" / "verified" or null | Yes |  |
| `kyb_state` | "not_started" / "in_progress" / "submitted" / "in_review" / "resubmission_required" / "form_k_ready" / "verified" / "rejected" or null | Yes |  |
| `kyb_state_reason` | string or null | No | Present only for callers with platform-wide authority; omitted for tenant callers. |
| `kyb_state_updated_at` | string or null | Yes |  |
| `kyc_source` | "bootstrap" / "sumsub" or null | No | Present only for callers with platform-wide authority; omitted for tenant callers. |
| `kyc_stage` | "verified" or null | Yes |  |
| `metadata` | object or null | No |  |
| `resource` | "client" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |
| `status` | "active" / "suspended" / "closed" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

###### application/json body.items item.default_client_account

At least one alternative must match.

###### application/json body.items item.default_client_account: alternative 1

Type: `string`. pattern: `^(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})$`

###### application/json body.items item.default_client_account: alternative 2

Type: `null`. 

###### application/json body.items item.display_name

At least one alternative must match.

###### application/json body.items item.display_name: alternative 1

Type: `string`. 

###### application/json body.items item.display_name: alternative 2

Type: `null`. 

###### application/json body.items item.external_id

At least one alternative must match.

###### application/json body.items item.external_id: alternative 1

Type: `string`. 

###### application/json body.items item.external_id: alternative 2

Type: `null`. 

###### application/json body.items item.kyb_source

Present only for callers with platform-wide authority; omitted for tenant callers.

At least one alternative must match.

###### application/json body.items item.kyb_source: alternative 1

Type: `"bootstrap" / "sumsub"`. 

###### application/json body.items item.kyb_source: alternative 2

Type: `null`. 

###### application/json body.items item.kyb_stage

At least one alternative must match.

###### application/json body.items item.kyb_stage: alternative 1

Type: `"form_k_ready" / "verified"`. 

###### application/json body.items item.kyb_stage: alternative 2

Type: `null`. 

###### application/json body.items item.kyb_state

At least one alternative must match.

###### application/json body.items item.kyb_state: alternative 1

Type: `"not_started" / "in_progress" / "submitted" / "in_review" / "resubmission_required" / "form_k_ready" / "verified" / "rejected"`. 

###### application/json body.items item.kyb_state: alternative 2

Type: `null`. 

###### application/json body.items item.kyb_state_reason

Present only for callers with platform-wide authority; omitted for tenant callers.

At least one alternative must match.

###### application/json body.items item.kyb_state_reason: alternative 1

Type: `string`. 

###### application/json body.items item.kyb_state_reason: alternative 2

Type: `null`. 

###### application/json body.items item.kyb_state_updated_at

At least one alternative must match.

###### application/json body.items item.kyb_state_updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.kyb_state_updated_at: alternative 2

Type: `null`. 

###### application/json body.items item.kyc_source

Present only for callers with platform-wide authority; omitted for tenant callers.

At least one alternative must match.

###### application/json body.items item.kyc_source: alternative 1

Type: `"bootstrap" / "sumsub"`. 

###### application/json body.items item.kyc_source: alternative 2

Type: `null`. 

###### application/json body.items item.kyc_stage

At least one alternative must match.

###### application/json body.items item.kyc_stage: alternative 1

Type: `"verified"`. 

###### application/json body.items item.kyc_stage: alternative 2

Type: `null`. 

###### application/json body.items item.metadata

At least one alternative must match.

###### application/json body.items item.metadata: alternative 1

Type: `object`. 

###### application/json body.items item.metadata: alternative 2

Type: `null`. 

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. 

###### application/json body.next_page_token: alternative 2

Type: `null`.


### clients-list 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.


### clients-list Response 401 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.


### clients-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#clients-list-response-401-schema).


### clients-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#clients-list-response-401-schema).


### clients-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#clients-list-response-400-schema).


### clients-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#clients-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "created_at": "2026-05-01T10:00:00Z",
        "default_client_account": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "display_name": "Acme Corp",
        "etag": "2026-05-01T10:00:00Z",
        "external_id": "ext-client-0042",
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kyb_stage": null,
        "kyb_state": null,
        "kyb_state_updated_at": null,
        "kyc_stage": null,
        "metadata": {
          "crm_id": "CRM-001",
          "tier": "premium"
        },
        "resource": "client",
        "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "status": "active",
        "updated_at": "2026-05-01T10:00:00Z"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /clients

**Create client**

Create a client under an enterprise. The first default client account is provisioned atomically. Requires the Idempotency-Key header. Read-only verification stamps and workflow state are returned separately from partner-writable metadata. `kyc_source`, `kyb_source` and `kyb_state_reason` (the verification provider and its reason) are present only for callers holding this operation’s capability through an `enterprise_wildcard` grant anchored at `platform-operators/<id>` (platform staff); other callers receive the client without them.

**Required capability:** `clients.create`

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) *(required)* — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `display_name` | string or null | No |  |
| `external_id` | string or null | No |  |
| `metadata` | object or null | No |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |

Additional fields are not accepted.

#### Request body schema.display_name

At least one alternative must match.

##### Request body schema.display_name: alternative 1

Type: `string`. 

##### Request body schema.display_name: alternative 2

Type: `null`. 

#### Request body schema.external_id

At least one alternative must match.

##### Request body schema.external_id: alternative 1

Type: `string`. minLength: 1

##### Request body schema.external_id: alternative 2

Type: `null`. 

#### Request body schema.metadata

At least one alternative must match.

##### Request body schema.metadata: alternative 1

Type: `object`. 

##### Request body schema.metadata: alternative 2

Type: `null`.

**Request example:**

```json
{
  "display_name": "Acme Corp",
  "external_id": "ext-client-0042",
  "metadata": {
    "crm_id": "CRM-001",
    "tier": "premium"
  },
  "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}
```

### clients-create Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `created_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))$` |
| `default_client_account` | string or null | No |  |
| `display_name` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `external_id` | string or null | No |  |
| `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)$` |
| `kyb_source` | "bootstrap" / "sumsub" or null | No | Present only for callers with platform-wide authority; omitted for tenant callers. |
| `kyb_stage` | "form_k_ready" / "verified" or null | Yes |  |
| `kyb_state` | "not_started" / "in_progress" / "submitted" / "in_review" / "resubmission_required" / "form_k_ready" / "verified" / "rejected" or null | Yes |  |
| `kyb_state_reason` | string or null | No | Present only for callers with platform-wide authority; omitted for tenant callers. |
| `kyb_state_updated_at` | string or null | Yes |  |
| `kyc_source` | "bootstrap" / "sumsub" or null | No | Present only for callers with platform-wide authority; omitted for tenant callers. |
| `kyc_stage` | "verified" or null | Yes |  |
| `metadata` | object or null | No |  |
| `resource` | "client" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |
| `status` | "active" / "suspended" / "closed" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.default_client_account

At least one alternative must match.

###### application/json body.default_client_account: alternative 1

Type: `string`. pattern: `^(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})$`

###### application/json body.default_client_account: alternative 2

Type: `null`. 

##### application/json body.display_name

At least one alternative must match.

###### application/json body.display_name: alternative 1

Type: `string`. 

###### application/json body.display_name: alternative 2

Type: `null`. 

##### application/json body.external_id

At least one alternative must match.

###### application/json body.external_id: alternative 1

Type: `string`. 

###### application/json body.external_id: alternative 2

Type: `null`. 

##### application/json body.kyb_source

Present only for callers with platform-wide authority; omitted for tenant callers.

At least one alternative must match.

###### application/json body.kyb_source: alternative 1

Type: `"bootstrap" / "sumsub"`. 

###### application/json body.kyb_source: alternative 2

Type: `null`. 

##### application/json body.kyb_stage

At least one alternative must match.

###### application/json body.kyb_stage: alternative 1

Type: `"form_k_ready" / "verified"`. 

###### application/json body.kyb_stage: alternative 2

Type: `null`. 

##### application/json body.kyb_state

At least one alternative must match.

###### application/json body.kyb_state: alternative 1

Type: `"not_started" / "in_progress" / "submitted" / "in_review" / "resubmission_required" / "form_k_ready" / "verified" / "rejected"`. 

###### application/json body.kyb_state: alternative 2

Type: `null`. 

##### application/json body.kyb_state_reason

Present only for callers with platform-wide authority; omitted for tenant callers.

At least one alternative must match.

###### application/json body.kyb_state_reason: alternative 1

Type: `string`. 

###### application/json body.kyb_state_reason: alternative 2

Type: `null`. 

##### application/json body.kyb_state_updated_at

At least one alternative must match.

###### application/json body.kyb_state_updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.kyb_state_updated_at: alternative 2

Type: `null`. 

##### application/json body.kyc_source

Present only for callers with platform-wide authority; omitted for tenant callers.

At least one alternative must match.

###### application/json body.kyc_source: alternative 1

Type: `"bootstrap" / "sumsub"`. 

###### application/json body.kyc_source: alternative 2

Type: `null`. 

##### application/json body.kyc_stage

At least one alternative must match.

###### application/json body.kyc_stage: alternative 1

Type: `"verified"`. 

###### application/json body.kyc_stage: alternative 2

Type: `null`. 

##### application/json body.metadata

At least one alternative must match.

###### application/json body.metadata: alternative 1

Type: `object`. 

###### application/json body.metadata: alternative 2

Type: `null`.


### clients-create 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.


### clients-create Response 401 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.


### clients-create Response 403 schema

Content type: `application/json`.

See [response 401 schema](#clients-create-response-401-schema).


### clients-create Response 404 schema

Content type: `application/json`.

See [response 401 schema](#clients-create-response-401-schema).


### clients-create Response 409 schema

Content type: `application/json`.

See [response 401 schema](#clients-create-response-401-schema).


### clients-create Response 500 schema

Content type: `application/json`.

See [response 401 schema](#clients-create-response-401-schema).


### clients-create Response 502 schema

Content type: `application/json`.

See [response 400 schema](#clients-create-response-400-schema).


### clients-create Response 503 schema

Content type: `application/json`.

See [response 400 schema](#clients-create-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "created_at": "2026-05-01T10:00:00Z",
    "default_client_account": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "display_name": "Acme Corp",
    "etag": "2026-05-01T10:00:00Z",
    "external_id": "ext-client-0042",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "kyb_stage": null,
    "kyb_state": null,
    "kyb_state_updated_at": null,
    "kyc_stage": null,
    "metadata": {
      "crm_id": "CRM-001",
      "tier": "premium"
    },
    "resource": "client",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /clients/{client_id}

**Get client**

Carries `first_access_method` of the client’s enterprise, from its onboarding record (`null` when there is none or it cannot be read). `kyc_source`, `kyb_source` and `kyb_state_reason` (the verification provider and its reason) are present only for callers holding this operation’s capability through an `enterprise_wildcard` grant anchored at `platform-operators/<id>` (platform staff); other callers receive the client without them.

**Required capability:** `clients.read`

**Authentication:** Bearer token required.

**Parameters:**

- `client_id` `string` (path) *(required)*

### clients-get Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `created_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))$` |
| `default_client_account` | string or null | No |  |
| `display_name` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `external_id` | string or null | No |  |
| `first_access_method` | "magic_link" / "passkey_enrolment" / "enterprise_idp" or null | Yes |  |
| `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)$` |
| `kyb_source` | "bootstrap" / "sumsub" or null | No | Present only for callers with platform-wide authority; omitted for tenant callers. |
| `kyb_stage` | "form_k_ready" / "verified" or null | Yes |  |
| `kyb_state` | "not_started" / "in_progress" / "submitted" / "in_review" / "resubmission_required" / "form_k_ready" / "verified" / "rejected" or null | Yes |  |
| `kyb_state_reason` | string or null | No | Present only for callers with platform-wide authority; omitted for tenant callers. |
| `kyb_state_updated_at` | string or null | Yes |  |
| `kyc_source` | "bootstrap" / "sumsub" or null | No | Present only for callers with platform-wide authority; omitted for tenant callers. |
| `kyc_stage` | "verified" or null | Yes |  |
| `metadata` | object or null | No |  |
| `resource` | "client" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |
| `status` | "active" / "suspended" / "closed" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.default_client_account

At least one alternative must match.

###### application/json body.default_client_account: alternative 1

Type: `string`. pattern: `^(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})$`

###### application/json body.default_client_account: alternative 2

Type: `null`. 

##### application/json body.display_name

At least one alternative must match.

###### application/json body.display_name: alternative 1

Type: `string`. 

###### application/json body.display_name: alternative 2

Type: `null`. 

##### application/json body.external_id

At least one alternative must match.

###### application/json body.external_id: alternative 1

Type: `string`. 

###### application/json body.external_id: alternative 2

Type: `null`. 

##### application/json body.first_access_method

At least one alternative must match.

###### application/json body.first_access_method: alternative 1

Type: `"magic_link" / "passkey_enrolment" / "enterprise_idp"`. 

###### application/json body.first_access_method: alternative 2

Type: `null`. 

##### application/json body.kyb_source

Present only for callers with platform-wide authority; omitted for tenant callers.

At least one alternative must match.

###### application/json body.kyb_source: alternative 1

Type: `"bootstrap" / "sumsub"`. 

###### application/json body.kyb_source: alternative 2

Type: `null`. 

##### application/json body.kyb_stage

At least one alternative must match.

###### application/json body.kyb_stage: alternative 1

Type: `"form_k_ready" / "verified"`. 

###### application/json body.kyb_stage: alternative 2

Type: `null`. 

##### application/json body.kyb_state

At least one alternative must match.

###### application/json body.kyb_state: alternative 1

Type: `"not_started" / "in_progress" / "submitted" / "in_review" / "resubmission_required" / "form_k_ready" / "verified" / "rejected"`. 

###### application/json body.kyb_state: alternative 2

Type: `null`. 

##### application/json body.kyb_state_reason

Present only for callers with platform-wide authority; omitted for tenant callers.

At least one alternative must match.

###### application/json body.kyb_state_reason: alternative 1

Type: `string`. 

###### application/json body.kyb_state_reason: alternative 2

Type: `null`. 

##### application/json body.kyb_state_updated_at

At least one alternative must match.

###### application/json body.kyb_state_updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.kyb_state_updated_at: alternative 2

Type: `null`. 

##### application/json body.kyc_source

Present only for callers with platform-wide authority; omitted for tenant callers.

At least one alternative must match.

###### application/json body.kyc_source: alternative 1

Type: `"bootstrap" / "sumsub"`. 

###### application/json body.kyc_source: alternative 2

Type: `null`. 

##### application/json body.kyc_stage

At least one alternative must match.

###### application/json body.kyc_stage: alternative 1

Type: `"verified"`. 

###### application/json body.kyc_stage: alternative 2

Type: `null`. 

##### application/json body.metadata

At least one alternative must match.

###### application/json body.metadata: alternative 1

Type: `object`. 

###### application/json body.metadata: alternative 2

Type: `null`.


### clients-get 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.


### clients-get Response 401 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.


### clients-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#clients-get-response-401-schema).


### clients-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#clients-get-response-401-schema).


### clients-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#clients-get-response-401-schema).


### clients-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#clients-get-response-400-schema).


### clients-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#clients-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "created_at": "2026-05-01T10:00:00Z",
    "default_client_account": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "display_name": "Acme Corp",
    "etag": "2026-05-01T10:00:00Z",
    "external_id": "ext-client-0042",
    "first_access_method": "enterprise_idp",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "kyb_stage": null,
    "kyb_state": null,
    "kyb_state_updated_at": null,
    "kyc_stage": null,
    "metadata": {
      "crm_id": "CRM-001",
      "tier": "premium"
    },
    "resource": "client",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### PATCH /clients/{client_id}

**Update client**

Patch tenant client. Requires `If-Match` for optimistic concurrency. `kyc_source`, `kyb_source` and `kyb_state_reason` (the verification provider and its reason) are present only for callers holding this operation’s capability through an `enterprise_wildcard` grant anchored at `platform-operators/<id>` (platform staff); other callers receive the client without them.

**Required capability:** `clients.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `client_id` `string` (path) *(required)*
- `If-Match` `string` (header) *(required)* — Weak entity tag from a prior GET. Mismatch causes the request to fail with 412 Precondition Failed.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `display_name` | string or null | No |  |
| `external_id` | string or null | No |  |
| `metadata` | object or null | No |  |

Additional fields are not accepted.

#### Request body schema.display_name

At least one alternative must match.

##### Request body schema.display_name: alternative 1

Type: `string`. 

##### Request body schema.display_name: alternative 2

Type: `null`. 

#### Request body schema.external_id

At least one alternative must match.

##### Request body schema.external_id: alternative 1

Type: `string`. 

##### Request body schema.external_id: alternative 2

Type: `null`. 

#### Request body schema.metadata

At least one alternative must match.

##### Request body schema.metadata: alternative 1

Type: `object`. 

##### Request body schema.metadata: alternative 2

Type: `null`.

**Request example:**

```json
{
  "display_name": "Acme Corp Updated",
  "metadata": {
    "crm_id": "CRM-002"
  }
}
```

### clients-update Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `created_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))$` |
| `default_client_account` | string or null | No |  |
| `display_name` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `external_id` | string or null | No |  |
| `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)$` |
| `kyb_source` | "bootstrap" / "sumsub" or null | No | Present only for callers with platform-wide authority; omitted for tenant callers. |
| `kyb_stage` | "form_k_ready" / "verified" or null | Yes |  |
| `kyb_state` | "not_started" / "in_progress" / "submitted" / "in_review" / "resubmission_required" / "form_k_ready" / "verified" / "rejected" or null | Yes |  |
| `kyb_state_reason` | string or null | No | Present only for callers with platform-wide authority; omitted for tenant callers. |
| `kyb_state_updated_at` | string or null | Yes |  |
| `kyc_source` | "bootstrap" / "sumsub" or null | No | Present only for callers with platform-wide authority; omitted for tenant callers. |
| `kyc_stage` | "verified" or null | Yes |  |
| `metadata` | object or null | No |  |
| `resource` | "client" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |
| `status` | "active" / "suspended" / "closed" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.default_client_account

At least one alternative must match.

###### application/json body.default_client_account: alternative 1

Type: `string`. pattern: `^(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})$`

###### application/json body.default_client_account: alternative 2

Type: `null`. 

##### application/json body.display_name

At least one alternative must match.

###### application/json body.display_name: alternative 1

Type: `string`. 

###### application/json body.display_name: alternative 2

Type: `null`. 

##### application/json body.external_id

At least one alternative must match.

###### application/json body.external_id: alternative 1

Type: `string`. 

###### application/json body.external_id: alternative 2

Type: `null`. 

##### application/json body.kyb_source

Present only for callers with platform-wide authority; omitted for tenant callers.

At least one alternative must match.

###### application/json body.kyb_source: alternative 1

Type: `"bootstrap" / "sumsub"`. 

###### application/json body.kyb_source: alternative 2

Type: `null`. 

##### application/json body.kyb_stage

At least one alternative must match.

###### application/json body.kyb_stage: alternative 1

Type: `"form_k_ready" / "verified"`. 

###### application/json body.kyb_stage: alternative 2

Type: `null`. 

##### application/json body.kyb_state

At least one alternative must match.

###### application/json body.kyb_state: alternative 1

Type: `"not_started" / "in_progress" / "submitted" / "in_review" / "resubmission_required" / "form_k_ready" / "verified" / "rejected"`. 

###### application/json body.kyb_state: alternative 2

Type: `null`. 

##### application/json body.kyb_state_reason

Present only for callers with platform-wide authority; omitted for tenant callers.

At least one alternative must match.

###### application/json body.kyb_state_reason: alternative 1

Type: `string`. 

###### application/json body.kyb_state_reason: alternative 2

Type: `null`. 

##### application/json body.kyb_state_updated_at

At least one alternative must match.

###### application/json body.kyb_state_updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.kyb_state_updated_at: alternative 2

Type: `null`. 

##### application/json body.kyc_source

Present only for callers with platform-wide authority; omitted for tenant callers.

At least one alternative must match.

###### application/json body.kyc_source: alternative 1

Type: `"bootstrap" / "sumsub"`. 

###### application/json body.kyc_source: alternative 2

Type: `null`. 

##### application/json body.kyc_stage

At least one alternative must match.

###### application/json body.kyc_stage: alternative 1

Type: `"verified"`. 

###### application/json body.kyc_stage: alternative 2

Type: `null`. 

##### application/json body.metadata

At least one alternative must match.

###### application/json body.metadata: alternative 1

Type: `object`. 

###### application/json body.metadata: alternative 2

Type: `null`.


### clients-update 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.


### clients-update Response 401 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.


### clients-update Response 403 schema

Content type: `application/json`.

See [response 401 schema](#clients-update-response-401-schema).


### clients-update Response 404 schema

Content type: `application/json`.

See [response 401 schema](#clients-update-response-401-schema).


### clients-update Response 409 schema

Content type: `application/json`.

See [response 401 schema](#clients-update-response-401-schema).


### clients-update Response 412 schema

Content type: `application/json`.

See [response 401 schema](#clients-update-response-401-schema).


### clients-update Response 500 schema

Content type: `application/json`.

See [response 401 schema](#clients-update-response-401-schema).


### clients-update Response 502 schema

Content type: `application/json`.

See [response 400 schema](#clients-update-response-400-schema).


### clients-update Response 503 schema

Content type: `application/json`.

See [response 400 schema](#clients-update-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "created_at": "2026-05-01T10:00:00Z",
    "default_client_account": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "display_name": "Acme Corp Updated",
    "etag": "2026-05-01T10:00:00Z",
    "external_id": "ext-client-0042",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "kyb_stage": null,
    "kyb_state": null,
    "kyb_state_updated_at": null,
    "kyc_stage": null,
    "metadata": {
      "crm_id": "CRM-002"
    },
    "resource": "client",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `412` — If-Match check failed; the resource has changed since the cached etag.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /clients/{client_id}/close

**Close client**

`kyc_source`, `kyb_source` and `kyb_state_reason` (the verification provider and its reason) are present only for callers holding this operation’s capability through an `enterprise_wildcard` grant anchored at `platform-operators/<id>` (platform staff); other callers receive the client without them.

**Required capability:** `clients.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `client_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `reason` | string or null | No |  |

Additional fields are not accepted.

#### Request body schema.reason

At least one alternative must match.

##### Request body schema.reason: alternative 1

Type: `string`. 

##### Request body schema.reason: alternative 2

Type: `null`.

### clients-close Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `created_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))$` |
| `default_client_account` | string or null | No |  |
| `display_name` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `external_id` | string or null | No |  |
| `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)$` |
| `kyb_source` | "bootstrap" / "sumsub" or null | No | Present only for callers with platform-wide authority; omitted for tenant callers. |
| `kyb_stage` | "form_k_ready" / "verified" or null | Yes |  |
| `kyb_state` | "not_started" / "in_progress" / "submitted" / "in_review" / "resubmission_required" / "form_k_ready" / "verified" / "rejected" or null | Yes |  |
| `kyb_state_reason` | string or null | No | Present only for callers with platform-wide authority; omitted for tenant callers. |
| `kyb_state_updated_at` | string or null | Yes |  |
| `kyc_source` | "bootstrap" / "sumsub" or null | No | Present only for callers with platform-wide authority; omitted for tenant callers. |
| `kyc_stage` | "verified" or null | Yes |  |
| `metadata` | object or null | No |  |
| `resource` | "client" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |
| `status` | "active" / "suspended" / "closed" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.default_client_account

At least one alternative must match.

###### application/json body.default_client_account: alternative 1

Type: `string`. pattern: `^(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})$`

###### application/json body.default_client_account: alternative 2

Type: `null`. 

##### application/json body.display_name

At least one alternative must match.

###### application/json body.display_name: alternative 1

Type: `string`. 

###### application/json body.display_name: alternative 2

Type: `null`. 

##### application/json body.external_id

At least one alternative must match.

###### application/json body.external_id: alternative 1

Type: `string`. 

###### application/json body.external_id: alternative 2

Type: `null`. 

##### application/json body.kyb_source

Present only for callers with platform-wide authority; omitted for tenant callers.

At least one alternative must match.

###### application/json body.kyb_source: alternative 1

Type: `"bootstrap" / "sumsub"`. 

###### application/json body.kyb_source: alternative 2

Type: `null`. 

##### application/json body.kyb_stage

At least one alternative must match.

###### application/json body.kyb_stage: alternative 1

Type: `"form_k_ready" / "verified"`. 

###### application/json body.kyb_stage: alternative 2

Type: `null`. 

##### application/json body.kyb_state

At least one alternative must match.

###### application/json body.kyb_state: alternative 1

Type: `"not_started" / "in_progress" / "submitted" / "in_review" / "resubmission_required" / "form_k_ready" / "verified" / "rejected"`. 

###### application/json body.kyb_state: alternative 2

Type: `null`. 

##### application/json body.kyb_state_reason

Present only for callers with platform-wide authority; omitted for tenant callers.

At least one alternative must match.

###### application/json body.kyb_state_reason: alternative 1

Type: `string`. 

###### application/json body.kyb_state_reason: alternative 2

Type: `null`. 

##### application/json body.kyb_state_updated_at

At least one alternative must match.

###### application/json body.kyb_state_updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.kyb_state_updated_at: alternative 2

Type: `null`. 

##### application/json body.kyc_source

Present only for callers with platform-wide authority; omitted for tenant callers.

At least one alternative must match.

###### application/json body.kyc_source: alternative 1

Type: `"bootstrap" / "sumsub"`. 

###### application/json body.kyc_source: alternative 2

Type: `null`. 

##### application/json body.kyc_stage

At least one alternative must match.

###### application/json body.kyc_stage: alternative 1

Type: `"verified"`. 

###### application/json body.kyc_stage: alternative 2

Type: `null`. 

##### application/json body.metadata

At least one alternative must match.

###### application/json body.metadata: alternative 1

Type: `object`. 

###### application/json body.metadata: alternative 2

Type: `null`.


### clients-close 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.


### clients-close Response 401 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.


### clients-close Response 403 schema

Content type: `application/json`.

See [response 401 schema](#clients-close-response-401-schema).


### clients-close Response 404 schema

Content type: `application/json`.

See [response 401 schema](#clients-close-response-401-schema).


### clients-close Response 409 schema

Content type: `application/json`.

See [response 401 schema](#clients-close-response-401-schema).


### clients-close Response 500 schema

Content type: `application/json`.

See [response 401 schema](#clients-close-response-401-schema).


### clients-close Response 502 schema

Content type: `application/json`.

See [response 400 schema](#clients-close-response-400-schema).


### clients-close Response 503 schema

Content type: `application/json`.

See [response 400 schema](#clients-close-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "created_at": "2026-05-01T10:00:00Z",
    "default_client_account": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "display_name": "Acme Corp",
    "etag": "2026-05-01T10:00:00Z",
    "external_id": "ext-client-0042",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "kyb_stage": null,
    "kyb_state": null,
    "kyb_state_updated_at": null,
    "kyc_stage": null,
    "metadata": {
      "crm_id": "CRM-001",
      "tier": "premium"
    },
    "resource": "client",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "closed",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /clients/{client_id}/reactivate

**Reactivate client**

`kyc_source`, `kyb_source` and `kyb_state_reason` (the verification provider and its reason) are present only for callers holding this operation’s capability through an `enterprise_wildcard` grant anchored at `platform-operators/<id>` (platform staff); other callers receive the client without them.

**Required capability:** `clients.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `client_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `reason` | string or null | No |  |

Additional fields are not accepted.

#### Request body schema.reason

At least one alternative must match.

##### Request body schema.reason: alternative 1

Type: `string`. 

##### Request body schema.reason: alternative 2

Type: `null`.

### clients-reactivate Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `created_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))$` |
| `default_client_account` | string or null | No |  |
| `display_name` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `external_id` | string or null | No |  |
| `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)$` |
| `kyb_source` | "bootstrap" / "sumsub" or null | No | Present only for callers with platform-wide authority; omitted for tenant callers. |
| `kyb_stage` | "form_k_ready" / "verified" or null | Yes |  |
| `kyb_state` | "not_started" / "in_progress" / "submitted" / "in_review" / "resubmission_required" / "form_k_ready" / "verified" / "rejected" or null | Yes |  |
| `kyb_state_reason` | string or null | No | Present only for callers with platform-wide authority; omitted for tenant callers. |
| `kyb_state_updated_at` | string or null | Yes |  |
| `kyc_source` | "bootstrap" / "sumsub" or null | No | Present only for callers with platform-wide authority; omitted for tenant callers. |
| `kyc_stage` | "verified" or null | Yes |  |
| `metadata` | object or null | No |  |
| `resource` | "client" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |
| `status` | "active" / "suspended" / "closed" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.default_client_account

At least one alternative must match.

###### application/json body.default_client_account: alternative 1

Type: `string`. pattern: `^(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})$`

###### application/json body.default_client_account: alternative 2

Type: `null`. 

##### application/json body.display_name

At least one alternative must match.

###### application/json body.display_name: alternative 1

Type: `string`. 

###### application/json body.display_name: alternative 2

Type: `null`. 

##### application/json body.external_id

At least one alternative must match.

###### application/json body.external_id: alternative 1

Type: `string`. 

###### application/json body.external_id: alternative 2

Type: `null`. 

##### application/json body.kyb_source

Present only for callers with platform-wide authority; omitted for tenant callers.

At least one alternative must match.

###### application/json body.kyb_source: alternative 1

Type: `"bootstrap" / "sumsub"`. 

###### application/json body.kyb_source: alternative 2

Type: `null`. 

##### application/json body.kyb_stage

At least one alternative must match.

###### application/json body.kyb_stage: alternative 1

Type: `"form_k_ready" / "verified"`. 

###### application/json body.kyb_stage: alternative 2

Type: `null`. 

##### application/json body.kyb_state

At least one alternative must match.

###### application/json body.kyb_state: alternative 1

Type: `"not_started" / "in_progress" / "submitted" / "in_review" / "resubmission_required" / "form_k_ready" / "verified" / "rejected"`. 

###### application/json body.kyb_state: alternative 2

Type: `null`. 

##### application/json body.kyb_state_reason

Present only for callers with platform-wide authority; omitted for tenant callers.

At least one alternative must match.

###### application/json body.kyb_state_reason: alternative 1

Type: `string`. 

###### application/json body.kyb_state_reason: alternative 2

Type: `null`. 

##### application/json body.kyb_state_updated_at

At least one alternative must match.

###### application/json body.kyb_state_updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.kyb_state_updated_at: alternative 2

Type: `null`. 

##### application/json body.kyc_source

Present only for callers with platform-wide authority; omitted for tenant callers.

At least one alternative must match.

###### application/json body.kyc_source: alternative 1

Type: `"bootstrap" / "sumsub"`. 

###### application/json body.kyc_source: alternative 2

Type: `null`. 

##### application/json body.kyc_stage

At least one alternative must match.

###### application/json body.kyc_stage: alternative 1

Type: `"verified"`. 

###### application/json body.kyc_stage: alternative 2

Type: `null`. 

##### application/json body.metadata

At least one alternative must match.

###### application/json body.metadata: alternative 1

Type: `object`. 

###### application/json body.metadata: alternative 2

Type: `null`.


### clients-reactivate 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.


### clients-reactivate Response 401 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.


### clients-reactivate Response 403 schema

Content type: `application/json`.

See [response 401 schema](#clients-reactivate-response-401-schema).


### clients-reactivate Response 404 schema

Content type: `application/json`.

See [response 401 schema](#clients-reactivate-response-401-schema).


### clients-reactivate Response 409 schema

Content type: `application/json`.

See [response 401 schema](#clients-reactivate-response-401-schema).


### clients-reactivate Response 500 schema

Content type: `application/json`.

See [response 401 schema](#clients-reactivate-response-401-schema).


### clients-reactivate Response 502 schema

Content type: `application/json`.

See [response 400 schema](#clients-reactivate-response-400-schema).


### clients-reactivate Response 503 schema

Content type: `application/json`.

See [response 400 schema](#clients-reactivate-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "created_at": "2026-05-01T10:00:00Z",
    "default_client_account": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "display_name": "Acme Corp",
    "etag": "2026-05-01T10:00:00Z",
    "external_id": "ext-client-0042",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "kyb_stage": null,
    "kyb_state": null,
    "kyb_state_updated_at": null,
    "kyc_stage": null,
    "metadata": {
      "crm_id": "CRM-001",
      "tier": "premium"
    },
    "resource": "client",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /clients/{client_id}/suspend

**Suspend client**

`kyc_source`, `kyb_source` and `kyb_state_reason` (the verification provider and its reason) are present only for callers holding this operation’s capability through an `enterprise_wildcard` grant anchored at `platform-operators/<id>` (platform staff); other callers receive the client without them.

**Required capability:** `clients.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `client_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `reason` | string or null | No |  |

Additional fields are not accepted.

#### Request body schema.reason

At least one alternative must match.

##### Request body schema.reason: alternative 1

Type: `string`. 

##### Request body schema.reason: alternative 2

Type: `null`.

### clients-suspend Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `created_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))$` |
| `default_client_account` | string or null | No |  |
| `display_name` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `external_id` | string or null | No |  |
| `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)$` |
| `kyb_source` | "bootstrap" / "sumsub" or null | No | Present only for callers with platform-wide authority; omitted for tenant callers. |
| `kyb_stage` | "form_k_ready" / "verified" or null | Yes |  |
| `kyb_state` | "not_started" / "in_progress" / "submitted" / "in_review" / "resubmission_required" / "form_k_ready" / "verified" / "rejected" or null | Yes |  |
| `kyb_state_reason` | string or null | No | Present only for callers with platform-wide authority; omitted for tenant callers. |
| `kyb_state_updated_at` | string or null | Yes |  |
| `kyc_source` | "bootstrap" / "sumsub" or null | No | Present only for callers with platform-wide authority; omitted for tenant callers. |
| `kyc_stage` | "verified" or null | Yes |  |
| `metadata` | object or null | No |  |
| `resource` | "client" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |
| `status` | "active" / "suspended" / "closed" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.default_client_account

At least one alternative must match.

###### application/json body.default_client_account: alternative 1

Type: `string`. pattern: `^(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})$`

###### application/json body.default_client_account: alternative 2

Type: `null`. 

##### application/json body.display_name

At least one alternative must match.

###### application/json body.display_name: alternative 1

Type: `string`. 

###### application/json body.display_name: alternative 2

Type: `null`. 

##### application/json body.external_id

At least one alternative must match.

###### application/json body.external_id: alternative 1

Type: `string`. 

###### application/json body.external_id: alternative 2

Type: `null`. 

##### application/json body.kyb_source

Present only for callers with platform-wide authority; omitted for tenant callers.

At least one alternative must match.

###### application/json body.kyb_source: alternative 1

Type: `"bootstrap" / "sumsub"`. 

###### application/json body.kyb_source: alternative 2

Type: `null`. 

##### application/json body.kyb_stage

At least one alternative must match.

###### application/json body.kyb_stage: alternative 1

Type: `"form_k_ready" / "verified"`. 

###### application/json body.kyb_stage: alternative 2

Type: `null`. 

##### application/json body.kyb_state

At least one alternative must match.

###### application/json body.kyb_state: alternative 1

Type: `"not_started" / "in_progress" / "submitted" / "in_review" / "resubmission_required" / "form_k_ready" / "verified" / "rejected"`. 

###### application/json body.kyb_state: alternative 2

Type: `null`. 

##### application/json body.kyb_state_reason

Present only for callers with platform-wide authority; omitted for tenant callers.

At least one alternative must match.

###### application/json body.kyb_state_reason: alternative 1

Type: `string`. 

###### application/json body.kyb_state_reason: alternative 2

Type: `null`. 

##### application/json body.kyb_state_updated_at

At least one alternative must match.

###### application/json body.kyb_state_updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.kyb_state_updated_at: alternative 2

Type: `null`. 

##### application/json body.kyc_source

Present only for callers with platform-wide authority; omitted for tenant callers.

At least one alternative must match.

###### application/json body.kyc_source: alternative 1

Type: `"bootstrap" / "sumsub"`. 

###### application/json body.kyc_source: alternative 2

Type: `null`. 

##### application/json body.kyc_stage

At least one alternative must match.

###### application/json body.kyc_stage: alternative 1

Type: `"verified"`. 

###### application/json body.kyc_stage: alternative 2

Type: `null`. 

##### application/json body.metadata

At least one alternative must match.

###### application/json body.metadata: alternative 1

Type: `object`. 

###### application/json body.metadata: alternative 2

Type: `null`.


### clients-suspend 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.


### clients-suspend Response 401 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.


### clients-suspend Response 403 schema

Content type: `application/json`.

See [response 401 schema](#clients-suspend-response-401-schema).


### clients-suspend Response 404 schema

Content type: `application/json`.

See [response 401 schema](#clients-suspend-response-401-schema).


### clients-suspend Response 409 schema

Content type: `application/json`.

See [response 401 schema](#clients-suspend-response-401-schema).


### clients-suspend Response 500 schema

Content type: `application/json`.

See [response 401 schema](#clients-suspend-response-401-schema).


### clients-suspend Response 502 schema

Content type: `application/json`.

See [response 400 schema](#clients-suspend-response-400-schema).


### clients-suspend Response 503 schema

Content type: `application/json`.

See [response 400 schema](#clients-suspend-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "created_at": "2026-05-01T10:00:00Z",
    "default_client_account": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "display_name": "Acme Corp",
    "etag": "2026-05-01T10:00:00Z",
    "external_id": "ext-client-0042",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "kyb_stage": null,
    "kyb_state": null,
    "kyb_state_updated_at": null,
    "kyc_stage": null,
    "metadata": {
      "crm_id": "CRM-001",
      "tier": "premium"
    },
    "resource": "client",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "suspended",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Client Accounts

### GET /client-accounts

**List client accounts**

List financial operating accounts attached to a client. The `scope_ref` query parameter is required and accepts a `clients/{uuid}` resource ref.

**Required capability:** `accounts.read`

**Authentication:** Bearer token required.

**Parameters:**

- `scope_ref` `string` (query) *(required)*
- `status` `string` (query)
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### client-accounts-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `created_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))$` |
| `display_name` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `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)$` |
| `resource` | "client_account" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(clients)\/([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})$` |
| `status` | "active" / "suspended" / "closed" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

###### application/json body.items item.display_name

At least one alternative must match.

###### application/json body.items item.display_name: alternative 1

Type: `string`. 

###### application/json body.items item.display_name: alternative 2

Type: `null`. 

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. 

###### application/json body.next_page_token: alternative 2

Type: `null`.


### client-accounts-list 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.


### client-accounts-list Response 401 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.


### client-accounts-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#client-accounts-list-response-401-schema).


### client-accounts-list Response 404 schema

Content type: `application/json`.

See [response 401 schema](#client-accounts-list-response-401-schema).


### client-accounts-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#client-accounts-list-response-401-schema).


### client-accounts-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#client-accounts-list-response-400-schema).


### client-accounts-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#client-accounts-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "created_at": "2026-05-01T10:00:00Z",
        "display_name": "Operating Account",
        "etag": "2026-05-01T10:00:00Z",
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "resource": "client_account",
        "scope_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "status": "active",
        "updated_at": "2026-05-01T10:00:00Z"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /client-accounts

**Create client account**

The metadata field is accepted but is currently ignored and not persisted. Creates an additional operating account under the named active client. The first default account is created with the client; this route adds a sibling. Requires the Idempotency-Key header.

**Required capability:** `accounts.create`

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) *(required)* — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `display_name` | string or null | No |  |
| `metadata` | object or null | No |  |
| `scope_ref` | string | Yes | pattern: `^(clients)\/([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})$` |

Additional fields are not accepted.

#### Request body schema.display_name

At least one alternative must match.

##### Request body schema.display_name: alternative 1

Type: `string`. 

##### Request body schema.display_name: alternative 2

Type: `null`. 

#### Request body schema.metadata

At least one alternative must match.

##### Request body schema.metadata: alternative 1

Type: `object`. 

##### Request body schema.metadata: alternative 2

Type: `null`.

**Request example:**

```json
{
  "display_name": "Operating Account EUR",
  "scope_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}
```

### client-accounts-create Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `created_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))$` |
| `display_name` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `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)$` |
| `resource` | "client_account" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(clients)\/([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})$` |
| `status` | "active" / "suspended" / "closed" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.display_name

At least one alternative must match.

###### application/json body.display_name: alternative 1

Type: `string`. 

###### application/json body.display_name: alternative 2

Type: `null`.


### client-accounts-create 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.


### client-accounts-create Response 401 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.


### client-accounts-create Response 403 schema

Content type: `application/json`.

See [response 401 schema](#client-accounts-create-response-401-schema).


### client-accounts-create Response 404 schema

Content type: `application/json`.

See [response 401 schema](#client-accounts-create-response-401-schema).


### client-accounts-create Response 409 schema

Content type: `application/json`.

See [response 401 schema](#client-accounts-create-response-401-schema).


### client-accounts-create Response 500 schema

Content type: `application/json`.

See [response 401 schema](#client-accounts-create-response-401-schema).


### client-accounts-create Response 502 schema

Content type: `application/json`.

See [response 400 schema](#client-accounts-create-response-400-schema).


### client-accounts-create Response 503 schema

Content type: `application/json`.

See [response 400 schema](#client-accounts-create-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "created_at": "2026-05-01T10:00:00Z",
    "display_name": "Operating Account",
    "etag": "2026-05-01T10:00:00Z",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "resource": "client_account",
    "scope_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /client-accounts/{client_account_id}

**Get client account**

**Required capability:** `accounts.read`

**Authentication:** Bearer token required.

**Parameters:**

- `client_account_id` `string` (path) *(required)*

### client-accounts-get Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `created_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))$` |
| `display_name` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `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)$` |
| `resource` | "client_account" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(clients)\/([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})$` |
| `status` | "active" / "suspended" / "closed" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.display_name

At least one alternative must match.

###### application/json body.display_name: alternative 1

Type: `string`. 

###### application/json body.display_name: alternative 2

Type: `null`.


### client-accounts-get 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.


### client-accounts-get Response 401 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.


### client-accounts-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#client-accounts-get-response-401-schema).


### client-accounts-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#client-accounts-get-response-401-schema).


### client-accounts-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#client-accounts-get-response-401-schema).


### client-accounts-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#client-accounts-get-response-400-schema).


### client-accounts-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#client-accounts-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "created_at": "2026-05-01T10:00:00Z",
    "display_name": "Operating Account",
    "etag": "2026-05-01T10:00:00Z",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "resource": "client_account",
    "scope_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /client-accounts/{client_account_id}/close

**Close client account**

**Required capability:** `accounts.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `client_account_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `reason` | string or null | No |  |

Additional fields are not accepted.

#### Request body schema.reason

At least one alternative must match.

##### Request body schema.reason: alternative 1

Type: `string`. 

##### Request body schema.reason: alternative 2

Type: `null`.

### client-accounts-close Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `created_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))$` |
| `display_name` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `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)$` |
| `resource` | "client_account" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(clients)\/([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})$` |
| `status` | "active" / "suspended" / "closed" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.display_name

At least one alternative must match.

###### application/json body.display_name: alternative 1

Type: `string`. 

###### application/json body.display_name: alternative 2

Type: `null`.


### client-accounts-close 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.


### client-accounts-close Response 401 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.


### client-accounts-close Response 403 schema

Content type: `application/json`.

See [response 401 schema](#client-accounts-close-response-401-schema).


### client-accounts-close Response 404 schema

Content type: `application/json`.

See [response 401 schema](#client-accounts-close-response-401-schema).


### client-accounts-close Response 409 schema

Content type: `application/json`.

See [response 401 schema](#client-accounts-close-response-401-schema).


### client-accounts-close Response 500 schema

Content type: `application/json`.

See [response 401 schema](#client-accounts-close-response-401-schema).


### client-accounts-close Response 502 schema

Content type: `application/json`.

See [response 400 schema](#client-accounts-close-response-400-schema).


### client-accounts-close Response 503 schema

Content type: `application/json`.

See [response 400 schema](#client-accounts-close-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "created_at": "2026-05-01T10:00:00Z",
    "display_name": "Operating Account",
    "etag": "2026-05-01T10:00:00Z",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "resource": "client_account",
    "scope_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "closed",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /client-accounts/{client_account_id}/reactivate

**Reactivate client account**

**Required capability:** `accounts.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `client_account_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `reason` | string or null | No |  |

Additional fields are not accepted.

#### Request body schema.reason

At least one alternative must match.

##### Request body schema.reason: alternative 1

Type: `string`. 

##### Request body schema.reason: alternative 2

Type: `null`.

### client-accounts-reactivate Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `created_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))$` |
| `display_name` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `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)$` |
| `resource` | "client_account" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(clients)\/([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})$` |
| `status` | "active" / "suspended" / "closed" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.display_name

At least one alternative must match.

###### application/json body.display_name: alternative 1

Type: `string`. 

###### application/json body.display_name: alternative 2

Type: `null`.


### client-accounts-reactivate 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.


### client-accounts-reactivate Response 401 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.


### client-accounts-reactivate Response 403 schema

Content type: `application/json`.

See [response 401 schema](#client-accounts-reactivate-response-401-schema).


### client-accounts-reactivate Response 404 schema

Content type: `application/json`.

See [response 401 schema](#client-accounts-reactivate-response-401-schema).


### client-accounts-reactivate Response 409 schema

Content type: `application/json`.

See [response 401 schema](#client-accounts-reactivate-response-401-schema).


### client-accounts-reactivate Response 500 schema

Content type: `application/json`.

See [response 401 schema](#client-accounts-reactivate-response-401-schema).


### client-accounts-reactivate Response 502 schema

Content type: `application/json`.

See [response 400 schema](#client-accounts-reactivate-response-400-schema).


### client-accounts-reactivate Response 503 schema

Content type: `application/json`.

See [response 400 schema](#client-accounts-reactivate-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "created_at": "2026-05-01T10:00:00Z",
    "display_name": "Operating Account",
    "etag": "2026-05-01T10:00:00Z",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "resource": "client_account",
    "scope_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /client-accounts/{client_account_id}/suspend

**Suspend client account**

**Required capability:** `accounts.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `client_account_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `reason` | string or null | No |  |

Additional fields are not accepted.

#### Request body schema.reason

At least one alternative must match.

##### Request body schema.reason: alternative 1

Type: `string`. 

##### Request body schema.reason: alternative 2

Type: `null`.

### client-accounts-suspend Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `created_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))$` |
| `display_name` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `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)$` |
| `resource` | "client_account" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(clients)\/([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})$` |
| `status` | "active" / "suspended" / "closed" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.display_name

At least one alternative must match.

###### application/json body.display_name: alternative 1

Type: `string`. 

###### application/json body.display_name: alternative 2

Type: `null`.


### client-accounts-suspend 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.


### client-accounts-suspend Response 401 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.


### client-accounts-suspend Response 403 schema

Content type: `application/json`.

See [response 401 schema](#client-accounts-suspend-response-401-schema).


### client-accounts-suspend Response 404 schema

Content type: `application/json`.

See [response 401 schema](#client-accounts-suspend-response-401-schema).


### client-accounts-suspend Response 409 schema

Content type: `application/json`.

See [response 401 schema](#client-accounts-suspend-response-401-schema).


### client-accounts-suspend Response 500 schema

Content type: `application/json`.

See [response 401 schema](#client-accounts-suspend-response-401-schema).


### client-accounts-suspend Response 502 schema

Content type: `application/json`.

See [response 400 schema](#client-accounts-suspend-response-400-schema).


### client-accounts-suspend Response 503 schema

Content type: `application/json`.

See [response 400 schema](#client-accounts-suspend-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "created_at": "2026-05-01T10:00:00Z",
    "display_name": "Operating Account",
    "etag": "2026-05-01T10:00:00Z",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "resource": "client_account",
    "scope_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "suspended",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Financial Accounts

### GET /financial-accounts

**List financial accounts**

Cursor-paginated financial accounts and their owner labels within a topology scope. Master accounts are listed first, then client accounts, each ordered by account_ref. Including enterprise client accounts additionally requires clients.read; account scope grants restrict returned owners. The owner fields owner_display_name and client_status also require clients.read: when clients.read does not cover a client scope_ref, its accounts are still returned with both fields set to null, the owner label is not searched, and a client_status filter is rejected with 403 scope_not_covered.

**Required capability:** `accounts.read`

**Authentication:** Bearer token required.

**Parameters:**

- `scope_ref` `string` (query) *(required)*
- `type` `string` (query)
- `status` `string` (query)
- `client_status` `string` (query)
- `q` `string` (query)
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### financial-accounts-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `type` | "master_account" / "client_account" | Yes |  |
| `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_status` | "active" / "suspended" / "closed" or null | Yes |  |
| `display_name` | string or null | Yes |  |
| `owner_display_name` | string or null | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|platform-operators\|clients)\/([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})$` |
| `status` | "active" / "suspended" / "closed" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.client_status

At least one alternative must match.

###### application/json body.items item.client_status: alternative 1

Type: `"active" / "suspended" / "closed"`. 

###### application/json body.items item.client_status: alternative 2

Type: `null`. 

###### application/json body.items item.display_name

At least one alternative must match.

###### application/json body.items item.display_name: alternative 1

Type: `string`. 

###### application/json body.items item.display_name: alternative 2

Type: `null`. 

###### application/json body.items item.owner_display_name

At least one alternative must match.

###### application/json body.items item.owner_display_name: alternative 1

Type: `string`. 

###### application/json body.items item.owner_display_name: alternative 2

Type: `null`. 

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. 

###### application/json body.next_page_token: alternative 2

Type: `null`.


### financial-accounts-list 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.


### financial-accounts-list Response 401 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.


### financial-accounts-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#financial-accounts-list-response-401-schema).


### financial-accounts-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#financial-accounts-list-response-401-schema).


### financial-accounts-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#financial-accounts-list-response-400-schema).


### financial-accounts-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#financial-accounts-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Users

### GET /users

**List users**

Lists users directly under `scope_ref`. With `include_descendants=true`, `scope_ref` must identify an enterprise and the response includes users of that enterprise and its clients in one page sequence. Subtree mode requires `users.read` over the subtree and does not apply the `status` or `identity_source` filters; those filters apply only to the direct-scope listing.

**Required capability:** `users.read`

**Authentication:** Bearer token required.

**Parameters:**

- `scope_ref` `string` (query) *(required)*
- `status` `string` (query)
- `identity_source` `string` (query)
- `include_descendants` `string` (query)
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### users-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `access_resend_event_id` | string or null | No |  |
| `created_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))$` |
| `display_name` | string or null | No |  |
| `email` | string or null | No |  |
| `email_changed_at` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `federation` | object or null | No |  |
| `federation_conflict` | string or null | No |  |
| `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)$` |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `last_suspended_at` | string or null | No |  |
| `previous_email` | string or null | No |  |
| `recovered_at` | string or null | No |  |
| `recovery_id` | string or null | No |  |
| `recovery_request` | object or null | No |  |
| `recovery_requested_at` | string or null | No |  |
| `resource` | "human_actor" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|clients\|platform-operators)\/([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})$` |
| `status` | "active" / "suspended" / "deactivated" / "pending_activation" / "invited" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

###### application/json body.items item.access_resend_event_id

At least one alternative must match.

###### application/json body.items item.access_resend_event_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item.access_resend_event_id: alternative 2

Type: `null`. 

###### application/json body.items item.display_name

At least one alternative must match.

###### application/json body.items item.display_name: alternative 1

Type: `string`. 

###### application/json body.items item.display_name: alternative 2

Type: `null`. 

###### application/json body.items item.email

At least one alternative must match.

###### application/json body.items item.email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.items item.email: alternative 2

Type: `null`. 

###### application/json body.items item.email_changed_at

At least one alternative must match.

###### application/json body.items item.email_changed_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.email_changed_at: alternative 2

Type: `null`. 

###### application/json body.items item.federation

At least one alternative must match.

###### application/json body.items item.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.items item.federation: alternative 2

Type: `null`. 

###### application/json body.items item.federation_conflict

At least one alternative must match.

###### application/json body.items item.federation_conflict: alternative 1

Type: `string`. 

###### application/json body.items item.federation_conflict: alternative 2

Type: `null`. 

###### application/json body.items item.last_suspended_at

At least one alternative must match.

###### application/json body.items item.last_suspended_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.last_suspended_at: alternative 2

Type: `null`. 

###### application/json body.items item.previous_email

At least one alternative must match.

###### application/json body.items item.previous_email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.items item.previous_email: alternative 2

Type: `null`. 

###### application/json body.items item.recovered_at

At least one alternative must match.

###### application/json body.items item.recovered_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.recovered_at: alternative 2

Type: `null`. 

###### application/json body.items item.recovery_id

At least one alternative must match.

###### application/json body.items item.recovery_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item.recovery_id: alternative 2

Type: `null`. 

###### application/json body.items item.recovery_request

At least one alternative must match.

###### application/json body.items item.recovery_request: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_id` | string or null | Yes |  |
| `created_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))$` |
| `new_email` | string or null | Yes |  |
| `reason` | string or null | Yes |  |
| `request_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)$` |
| `state` | "awaiting" / "executed" / "completed" / "failed" / "rejected" / "expired" / "cancelled" / "aborted" / "superseded" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.recovery_request: alternative 1.approval_id

At least one alternative must match.

###### application/json body.items item.recovery_request: alternative 1.approval_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item.recovery_request: alternative 1.approval_id: alternative 2

Type: `null`. 

###### application/json body.items item.recovery_request: alternative 1.new_email

At least one alternative must match.

###### application/json body.items item.recovery_request: alternative 1.new_email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.items item.recovery_request: alternative 1.new_email: alternative 2

Type: `null`. 

###### application/json body.items item.recovery_request: alternative 1.reason

At least one alternative must match.

###### application/json body.items item.recovery_request: alternative 1.reason: alternative 1

Type: `string`. 

###### application/json body.items item.recovery_request: alternative 1.reason: alternative 2

Type: `null`. 

###### application/json body.items item.recovery_request: alternative 2

Type: `null`. 

###### application/json body.items item.recovery_requested_at

At least one alternative must match.

###### application/json body.items item.recovery_requested_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.recovery_requested_at: alternative 2

Type: `null`. 

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. 

###### application/json body.next_page_token: alternative 2

Type: `null`.


### users-list 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.


### users-list Response 401 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.


### users-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#users-list-response-401-schema).


### users-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#users-list-response-401-schema).


### users-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#users-list-response-400-schema).


### users-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#users-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "created_at": "2026-05-01T10:00:00Z",
        "display_name": "Jane Doe",
        "email": "jane.doe@acme.example",
        "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
        "federation": null,
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "identity_source": "platform-managed",
        "resource": "human_actor",
        "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "status": "active",
        "updated_at": "2026-05-01T10:00:00.000Z"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /users

**Create user**

**Required capability:** `users.create`

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `display_name` | string or null | No |  |
| `email` | string | Yes | format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$` |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|clients\|platform-operators)\/([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})$` |

Additional fields are not accepted.

#### Request body schema.display_name

At least one alternative must match.

##### Request body schema.display_name: alternative 1

Type: `string`. 

##### Request body schema.display_name: alternative 2

Type: `null`.

**Request example:**

```json
{
  "display_name": "Jane Doe",
  "email": "jane.doe@acme.example",
  "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}
```

### users-create Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `access_resend_event_id` | string or null | No |  |
| `created_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))$` |
| `display_name` | string or null | No |  |
| `email` | string or null | No |  |
| `email_changed_at` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `federation` | object or null | No |  |
| `federation_conflict` | string or null | No |  |
| `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)$` |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `last_suspended_at` | string or null | No |  |
| `previous_email` | string or null | No |  |
| `recovered_at` | string or null | No |  |
| `recovery_id` | string or null | No |  |
| `recovery_request` | object or null | No |  |
| `recovery_requested_at` | string or null | No |  |
| `resource` | "human_actor" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|clients\|platform-operators)\/([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})$` |
| `status` | "active" / "suspended" / "deactivated" / "pending_activation" / "invited" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.access_resend_event_id

At least one alternative must match.

###### application/json body.access_resend_event_id: alternative 1

Type: `string`. 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)$`

###### application/json body.access_resend_event_id: alternative 2

Type: `null`. 

##### application/json body.display_name

At least one alternative must match.

###### application/json body.display_name: alternative 1

Type: `string`. 

###### application/json body.display_name: alternative 2

Type: `null`. 

##### application/json body.email

At least one alternative must match.

###### application/json body.email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.email: alternative 2

Type: `null`. 

##### application/json body.email_changed_at

At least one alternative must match.

###### application/json body.email_changed_at: alternative 1

Type: `string`. 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))$`

###### application/json body.email_changed_at: alternative 2

Type: `null`. 

##### application/json body.federation

At least one alternative must match.

###### application/json body.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.federation: alternative 2

Type: `null`. 

##### application/json body.federation_conflict

At least one alternative must match.

###### application/json body.federation_conflict: alternative 1

Type: `string`. 

###### application/json body.federation_conflict: alternative 2

Type: `null`. 

##### application/json body.last_suspended_at

At least one alternative must match.

###### application/json body.last_suspended_at: alternative 1

Type: `string`. 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))$`

###### application/json body.last_suspended_at: alternative 2

Type: `null`. 

##### application/json body.previous_email

At least one alternative must match.

###### application/json body.previous_email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.previous_email: alternative 2

Type: `null`. 

##### application/json body.recovered_at

At least one alternative must match.

###### application/json body.recovered_at: alternative 1

Type: `string`. 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))$`

###### application/json body.recovered_at: alternative 2

Type: `null`. 

##### application/json body.recovery_id

At least one alternative must match.

###### application/json body.recovery_id: alternative 1

Type: `string`. 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)$`

###### application/json body.recovery_id: alternative 2

Type: `null`. 

##### application/json body.recovery_request

At least one alternative must match.

###### application/json body.recovery_request: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_id` | string or null | Yes |  |
| `created_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))$` |
| `new_email` | string or null | Yes |  |
| `reason` | string or null | Yes |  |
| `request_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)$` |
| `state` | "awaiting" / "executed" / "completed" / "failed" / "rejected" / "expired" / "cancelled" / "aborted" / "superseded" | Yes |  |

Additional fields are not accepted.

###### application/json body.recovery_request: alternative 1.approval_id

At least one alternative must match.

###### application/json body.recovery_request: alternative 1.approval_id: alternative 1

Type: `string`. 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)$`

###### application/json body.recovery_request: alternative 1.approval_id: alternative 2

Type: `null`. 

###### application/json body.recovery_request: alternative 1.new_email

At least one alternative must match.

###### application/json body.recovery_request: alternative 1.new_email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.recovery_request: alternative 1.new_email: alternative 2

Type: `null`. 

###### application/json body.recovery_request: alternative 1.reason

At least one alternative must match.

###### application/json body.recovery_request: alternative 1.reason: alternative 1

Type: `string`. 

###### application/json body.recovery_request: alternative 1.reason: alternative 2

Type: `null`. 

###### application/json body.recovery_request: alternative 2

Type: `null`. 

##### application/json body.recovery_requested_at

At least one alternative must match.

###### application/json body.recovery_requested_at: alternative 1

Type: `string`. 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))$`

###### application/json body.recovery_requested_at: alternative 2

Type: `null`.


### users-create 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.


### users-create Response 401 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.


### users-create Response 403 schema

Content type: `application/json`.

See [response 401 schema](#users-create-response-401-schema).


### users-create Response 409 schema

Content type: `application/json`.

See [response 401 schema](#users-create-response-401-schema).


### users-create Response 500 schema

Content type: `application/json`.

See [response 401 schema](#users-create-response-401-schema).


### users-create Response 502 schema

Content type: `application/json`.

See [response 400 schema](#users-create-response-400-schema).


### users-create Response 503 schema

Content type: `application/json`.

See [response 400 schema](#users-create-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "created_at": "2026-05-01T10:00:00Z",
    "display_name": "Jane Doe",
    "email": "jane.doe@acme.example",
    "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
    "federation": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "identity_source": "platform-managed",
    "resource": "human_actor",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00.000Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /users/{user_id}

**Get user**

**Required capability:** `users.read`

**Authentication:** Bearer token required.

**Parameters:**

- `user_id` `string` (path) *(required)*

### users-get Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `access_resend_event_id` | string or null | No |  |
| `created_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))$` |
| `display_name` | string or null | No |  |
| `email` | string or null | No |  |
| `email_changed_at` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `federation` | object or null | No |  |
| `federation_conflict` | string or null | No |  |
| `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)$` |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `last_suspended_at` | string or null | No |  |
| `previous_email` | string or null | No |  |
| `recovered_at` | string or null | No |  |
| `recovery_id` | string or null | No |  |
| `recovery_request` | object or null | No |  |
| `recovery_requested_at` | string or null | No |  |
| `resource` | "human_actor" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|clients\|platform-operators)\/([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})$` |
| `status` | "active" / "suspended" / "deactivated" / "pending_activation" / "invited" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.access_resend_event_id

At least one alternative must match.

###### application/json body.access_resend_event_id: alternative 1

Type: `string`. 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)$`

###### application/json body.access_resend_event_id: alternative 2

Type: `null`. 

##### application/json body.display_name

At least one alternative must match.

###### application/json body.display_name: alternative 1

Type: `string`. 

###### application/json body.display_name: alternative 2

Type: `null`. 

##### application/json body.email

At least one alternative must match.

###### application/json body.email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.email: alternative 2

Type: `null`. 

##### application/json body.email_changed_at

At least one alternative must match.

###### application/json body.email_changed_at: alternative 1

Type: `string`. 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))$`

###### application/json body.email_changed_at: alternative 2

Type: `null`. 

##### application/json body.federation

At least one alternative must match.

###### application/json body.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.federation: alternative 2

Type: `null`. 

##### application/json body.federation_conflict

At least one alternative must match.

###### application/json body.federation_conflict: alternative 1

Type: `string`. 

###### application/json body.federation_conflict: alternative 2

Type: `null`. 

##### application/json body.last_suspended_at

At least one alternative must match.

###### application/json body.last_suspended_at: alternative 1

Type: `string`. 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))$`

###### application/json body.last_suspended_at: alternative 2

Type: `null`. 

##### application/json body.previous_email

At least one alternative must match.

###### application/json body.previous_email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.previous_email: alternative 2

Type: `null`. 

##### application/json body.recovered_at

At least one alternative must match.

###### application/json body.recovered_at: alternative 1

Type: `string`. 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))$`

###### application/json body.recovered_at: alternative 2

Type: `null`. 

##### application/json body.recovery_id

At least one alternative must match.

###### application/json body.recovery_id: alternative 1

Type: `string`. 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)$`

###### application/json body.recovery_id: alternative 2

Type: `null`. 

##### application/json body.recovery_request

At least one alternative must match.

###### application/json body.recovery_request: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_id` | string or null | Yes |  |
| `created_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))$` |
| `new_email` | string or null | Yes |  |
| `reason` | string or null | Yes |  |
| `request_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)$` |
| `state` | "awaiting" / "executed" / "completed" / "failed" / "rejected" / "expired" / "cancelled" / "aborted" / "superseded" | Yes |  |

Additional fields are not accepted.

###### application/json body.recovery_request: alternative 1.approval_id

At least one alternative must match.

###### application/json body.recovery_request: alternative 1.approval_id: alternative 1

Type: `string`. 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)$`

###### application/json body.recovery_request: alternative 1.approval_id: alternative 2

Type: `null`. 

###### application/json body.recovery_request: alternative 1.new_email

At least one alternative must match.

###### application/json body.recovery_request: alternative 1.new_email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.recovery_request: alternative 1.new_email: alternative 2

Type: `null`. 

###### application/json body.recovery_request: alternative 1.reason

At least one alternative must match.

###### application/json body.recovery_request: alternative 1.reason: alternative 1

Type: `string`. 

###### application/json body.recovery_request: alternative 1.reason: alternative 2

Type: `null`. 

###### application/json body.recovery_request: alternative 2

Type: `null`. 

##### application/json body.recovery_requested_at

At least one alternative must match.

###### application/json body.recovery_requested_at: alternative 1

Type: `string`. 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))$`

###### application/json body.recovery_requested_at: alternative 2

Type: `null`.


### users-get 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.


### users-get Response 401 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.


### users-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#users-get-response-401-schema).


### users-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#users-get-response-401-schema).


### users-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#users-get-response-401-schema).


### users-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#users-get-response-400-schema).


### users-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#users-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "created_at": "2026-05-01T10:00:00Z",
    "display_name": "Jane Doe",
    "email": "jane.doe@acme.example",
    "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
    "federation": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "identity_source": "platform-managed",
    "resource": "human_actor",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00.000Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### PATCH /users/{user_id}

**Update user**

Patch a user. Requires `If-Match`.

**Required capability:** `users.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `user_id` `string` (path) *(required)*
- `If-Match` `string` (header) *(required)* — Weak entity tag from a prior GET. Mismatch causes the request to fail with 412 Precondition Failed.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `display_name` | string or null | No |  |
| `email` | string or null | No |  |

Additional fields are not accepted.

#### Request body schema.display_name

At least one alternative must match.

##### Request body schema.display_name: alternative 1

Type: `string`. 

##### Request body schema.display_name: alternative 2

Type: `null`. 

#### Request body schema.email

At least one alternative must match.

##### Request body schema.email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

##### Request body schema.email: alternative 2

Type: `null`.

**Request example:**

```json
{
  "display_name": "Jane Doe Updated",
  "email": "jane.new@acme.example"
}
```

### users-update Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `access_resend_event_id` | string or null | No |  |
| `created_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))$` |
| `display_name` | string or null | No |  |
| `email` | string or null | No |  |
| `email_changed_at` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `federation` | object or null | No |  |
| `federation_conflict` | string or null | No |  |
| `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)$` |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `last_suspended_at` | string or null | No |  |
| `previous_email` | string or null | No |  |
| `recovered_at` | string or null | No |  |
| `recovery_id` | string or null | No |  |
| `recovery_request` | object or null | No |  |
| `recovery_requested_at` | string or null | No |  |
| `resource` | "human_actor" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|clients\|platform-operators)\/([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})$` |
| `status` | "active" / "suspended" / "deactivated" / "pending_activation" / "invited" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.access_resend_event_id

At least one alternative must match.

###### application/json body.access_resend_event_id: alternative 1

Type: `string`. 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)$`

###### application/json body.access_resend_event_id: alternative 2

Type: `null`. 

##### application/json body.display_name

At least one alternative must match.

###### application/json body.display_name: alternative 1

Type: `string`. 

###### application/json body.display_name: alternative 2

Type: `null`. 

##### application/json body.email

At least one alternative must match.

###### application/json body.email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.email: alternative 2

Type: `null`. 

##### application/json body.email_changed_at

At least one alternative must match.

###### application/json body.email_changed_at: alternative 1

Type: `string`. 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))$`

###### application/json body.email_changed_at: alternative 2

Type: `null`. 

##### application/json body.federation

At least one alternative must match.

###### application/json body.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.federation: alternative 2

Type: `null`. 

##### application/json body.federation_conflict

At least one alternative must match.

###### application/json body.federation_conflict: alternative 1

Type: `string`. 

###### application/json body.federation_conflict: alternative 2

Type: `null`. 

##### application/json body.last_suspended_at

At least one alternative must match.

###### application/json body.last_suspended_at: alternative 1

Type: `string`. 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))$`

###### application/json body.last_suspended_at: alternative 2

Type: `null`. 

##### application/json body.previous_email

At least one alternative must match.

###### application/json body.previous_email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.previous_email: alternative 2

Type: `null`. 

##### application/json body.recovered_at

At least one alternative must match.

###### application/json body.recovered_at: alternative 1

Type: `string`. 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))$`

###### application/json body.recovered_at: alternative 2

Type: `null`. 

##### application/json body.recovery_id

At least one alternative must match.

###### application/json body.recovery_id: alternative 1

Type: `string`. 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)$`

###### application/json body.recovery_id: alternative 2

Type: `null`. 

##### application/json body.recovery_request

At least one alternative must match.

###### application/json body.recovery_request: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_id` | string or null | Yes |  |
| `created_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))$` |
| `new_email` | string or null | Yes |  |
| `reason` | string or null | Yes |  |
| `request_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)$` |
| `state` | "awaiting" / "executed" / "completed" / "failed" / "rejected" / "expired" / "cancelled" / "aborted" / "superseded" | Yes |  |

Additional fields are not accepted.

###### application/json body.recovery_request: alternative 1.approval_id

At least one alternative must match.

###### application/json body.recovery_request: alternative 1.approval_id: alternative 1

Type: `string`. 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)$`

###### application/json body.recovery_request: alternative 1.approval_id: alternative 2

Type: `null`. 

###### application/json body.recovery_request: alternative 1.new_email

At least one alternative must match.

###### application/json body.recovery_request: alternative 1.new_email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.recovery_request: alternative 1.new_email: alternative 2

Type: `null`. 

###### application/json body.recovery_request: alternative 1.reason

At least one alternative must match.

###### application/json body.recovery_request: alternative 1.reason: alternative 1

Type: `string`. 

###### application/json body.recovery_request: alternative 1.reason: alternative 2

Type: `null`. 

###### application/json body.recovery_request: alternative 2

Type: `null`. 

##### application/json body.recovery_requested_at

At least one alternative must match.

###### application/json body.recovery_requested_at: alternative 1

Type: `string`. 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))$`

###### application/json body.recovery_requested_at: alternative 2

Type: `null`.


### users-update 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.


### users-update Response 401 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.


### users-update Response 403 schema

Content type: `application/json`.

See [response 401 schema](#users-update-response-401-schema).


### users-update Response 404 schema

Content type: `application/json`.

See [response 401 schema](#users-update-response-401-schema).


### users-update Response 409 schema

Content type: `application/json`.

See [response 401 schema](#users-update-response-401-schema).


### users-update Response 412 schema

Content type: `application/json`.

See [response 401 schema](#users-update-response-401-schema).


### users-update Response 500 schema

Content type: `application/json`.

See [response 401 schema](#users-update-response-401-schema).


### users-update Response 502 schema

Content type: `application/json`.

See [response 400 schema](#users-update-response-400-schema).


### users-update Response 503 schema

Content type: `application/json`.

See [response 400 schema](#users-update-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "created_at": "2026-05-01T10:00:00Z",
    "display_name": "Jane Doe",
    "email": "jane.doe@acme.example",
    "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
    "federation": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "identity_source": "platform-managed",
    "resource": "human_actor",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00.000Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `412` — If-Match check failed; the resource has changed since the cached etag.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /users/{user_id}/access-resend

**Re-send access to a recovering user**

Emits the recovery command again for a user in `pending_activation` with a `recovery_id`. Requires `users.recovery_initiate`; one per user per five minutes (`429 resend_rate_limited`).

**Required capability:** `users.recovery_initiate`

**Authentication:** Bearer token required.

**Parameters:**

- `user_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

### users-access-resend Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `event_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.


### users-access-resend 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.


### users-access-resend Response 401 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.


### users-access-resend Response 403 schema

Content type: `application/json`.

See [response 401 schema](#users-access-resend-response-401-schema).


### users-access-resend Response 404 schema

Content type: `application/json`.

See [response 401 schema](#users-access-resend-response-401-schema).


### users-access-resend Response 409 schema

Content type: `application/json`.

See [response 401 schema](#users-access-resend-response-401-schema).


### users-access-resend Response 429 schema

Content type: `application/json`.

See [response 401 schema](#users-access-resend-response-401-schema).


### users-access-resend Response 500 schema

Content type: `application/json`.

See [response 401 schema](#users-access-resend-response-401-schema).


### users-access-resend Response 502 schema

Content type: `application/json`.

See [response 400 schema](#users-access-resend-response-400-schema).


### users-access-resend Response 503 schema

Content type: `application/json`.

See [response 400 schema](#users-access-resend-response-400-schema).


**Responses:**

- `200` — Operation succeeded.
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `429` — The request was rate limited; retry according to the returned backoff information.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /users/{user_id}/activate-federated

**Activate a user and bind their federated identity**

Called by an enterprise’s own identity backend (service principal, `private_key_jwt`) once the user finished first access or a recovery. The caller’s IdP row is taken from its verified token; `recovery_id` is forwarded unchanged.

**Required capability:** `users.activate_federated`

**Authentication:** Bearer token required.

**Parameters:**

- `user_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer_uri` | string | Yes | format: uri |
| `recovery_id` | string or null | No |  |

Additional fields are not accepted.

#### Request body schema.recovery_id

At least one alternative must match.

##### Request body schema.recovery_id: alternative 1

Type: `string`. 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)$`

##### Request body schema.recovery_id: alternative 2

Type: `null`.

### users-activate-federated Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `human_actor_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)$` |
| `invitation_id` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.invitation_id

At least one alternative must match.

###### application/json body.invitation_id: alternative 1

Type: `string`. 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)$`

###### application/json body.invitation_id: alternative 2

Type: `null`.


### users-activate-federated 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.


### users-activate-federated Response 401 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.


### users-activate-federated Response 403 schema

Content type: `application/json`.

See [response 401 schema](#users-activate-federated-response-401-schema).


### users-activate-federated Response 404 schema

Content type: `application/json`.

See [response 401 schema](#users-activate-federated-response-401-schema).


### users-activate-federated Response 409 schema

Content type: `application/json`.

See [response 401 schema](#users-activate-federated-response-401-schema).


### users-activate-federated Response 500 schema

Content type: `application/json`.

See [response 401 schema](#users-activate-federated-response-401-schema).


### users-activate-federated Response 502 schema

Content type: `application/json`.

See [response 400 schema](#users-activate-federated-response-400-schema).


### users-activate-federated Response 503 schema

Content type: `application/json`.

See [response 400 schema](#users-activate-federated-response-400-schema).


**Responses:**

- `200` — Operation succeeded.
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /users/{user_id}/deactivate

**Deactivate user**

**Required capability:** `users.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `user_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `reason` | string or null | No |  |

Additional fields are not accepted.

#### Request body schema.reason

At least one alternative must match.

##### Request body schema.reason: alternative 1

Type: `string`. 

##### Request body schema.reason: alternative 2

Type: `null`.

### users-deactivate Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `access_resend_event_id` | string or null | No |  |
| `created_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))$` |
| `display_name` | string or null | No |  |
| `email` | string or null | No |  |
| `email_changed_at` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `federation` | object or null | No |  |
| `federation_conflict` | string or null | No |  |
| `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)$` |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `last_suspended_at` | string or null | No |  |
| `previous_email` | string or null | No |  |
| `recovered_at` | string or null | No |  |
| `recovery_id` | string or null | No |  |
| `recovery_request` | object or null | No |  |
| `recovery_requested_at` | string or null | No |  |
| `resource` | "human_actor" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|clients\|platform-operators)\/([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})$` |
| `status` | "active" / "suspended" / "deactivated" / "pending_activation" / "invited" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.access_resend_event_id

At least one alternative must match.

###### application/json body.access_resend_event_id: alternative 1

Type: `string`. 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)$`

###### application/json body.access_resend_event_id: alternative 2

Type: `null`. 

##### application/json body.display_name

At least one alternative must match.

###### application/json body.display_name: alternative 1

Type: `string`. 

###### application/json body.display_name: alternative 2

Type: `null`. 

##### application/json body.email

At least one alternative must match.

###### application/json body.email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.email: alternative 2

Type: `null`. 

##### application/json body.email_changed_at

At least one alternative must match.

###### application/json body.email_changed_at: alternative 1

Type: `string`. 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))$`

###### application/json body.email_changed_at: alternative 2

Type: `null`. 

##### application/json body.federation

At least one alternative must match.

###### application/json body.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.federation: alternative 2

Type: `null`. 

##### application/json body.federation_conflict

At least one alternative must match.

###### application/json body.federation_conflict: alternative 1

Type: `string`. 

###### application/json body.federation_conflict: alternative 2

Type: `null`. 

##### application/json body.last_suspended_at

At least one alternative must match.

###### application/json body.last_suspended_at: alternative 1

Type: `string`. 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))$`

###### application/json body.last_suspended_at: alternative 2

Type: `null`. 

##### application/json body.previous_email

At least one alternative must match.

###### application/json body.previous_email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.previous_email: alternative 2

Type: `null`. 

##### application/json body.recovered_at

At least one alternative must match.

###### application/json body.recovered_at: alternative 1

Type: `string`. 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))$`

###### application/json body.recovered_at: alternative 2

Type: `null`. 

##### application/json body.recovery_id

At least one alternative must match.

###### application/json body.recovery_id: alternative 1

Type: `string`. 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)$`

###### application/json body.recovery_id: alternative 2

Type: `null`. 

##### application/json body.recovery_request

At least one alternative must match.

###### application/json body.recovery_request: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_id` | string or null | Yes |  |
| `created_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))$` |
| `new_email` | string or null | Yes |  |
| `reason` | string or null | Yes |  |
| `request_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)$` |
| `state` | "awaiting" / "executed" / "completed" / "failed" / "rejected" / "expired" / "cancelled" / "aborted" / "superseded" | Yes |  |

Additional fields are not accepted.

###### application/json body.recovery_request: alternative 1.approval_id

At least one alternative must match.

###### application/json body.recovery_request: alternative 1.approval_id: alternative 1

Type: `string`. 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)$`

###### application/json body.recovery_request: alternative 1.approval_id: alternative 2

Type: `null`. 

###### application/json body.recovery_request: alternative 1.new_email

At least one alternative must match.

###### application/json body.recovery_request: alternative 1.new_email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.recovery_request: alternative 1.new_email: alternative 2

Type: `null`. 

###### application/json body.recovery_request: alternative 1.reason

At least one alternative must match.

###### application/json body.recovery_request: alternative 1.reason: alternative 1

Type: `string`. 

###### application/json body.recovery_request: alternative 1.reason: alternative 2

Type: `null`. 

###### application/json body.recovery_request: alternative 2

Type: `null`. 

##### application/json body.recovery_requested_at

At least one alternative must match.

###### application/json body.recovery_requested_at: alternative 1

Type: `string`. 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))$`

###### application/json body.recovery_requested_at: alternative 2

Type: `null`.


### users-deactivate 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.


### users-deactivate Response 401 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.


### users-deactivate Response 403 schema

Content type: `application/json`.

See [response 401 schema](#users-deactivate-response-401-schema).


### users-deactivate Response 404 schema

Content type: `application/json`.

See [response 401 schema](#users-deactivate-response-401-schema).


### users-deactivate Response 409 schema

Content type: `application/json`.

See [response 401 schema](#users-deactivate-response-401-schema).


### users-deactivate Response 500 schema

Content type: `application/json`.

See [response 401 schema](#users-deactivate-response-401-schema).


### users-deactivate Response 502 schema

Content type: `application/json`.

See [response 400 schema](#users-deactivate-response-400-schema).


### users-deactivate Response 503 schema

Content type: `application/json`.

See [response 400 schema](#users-deactivate-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "created_at": "2026-05-01T10:00:00Z",
    "display_name": "Jane Doe",
    "email": "jane.doe@acme.example",
    "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
    "federation": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "identity_source": "platform-managed",
    "resource": "human_actor",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "deactivated",
    "updated_at": "2026-05-01T10:00:00.000Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /users/{user_id}/federation-binding

**Bind a user to a federated identity**

Binds the user to the supplied issuer and external subject and returns the updated user. This route is closed for users of an enterprise whose first-access method is `enterprise_idp`: use `POST /users/{user_id}/activate-federated` for that path. Such requests return `409 state_conflict` with `data.reason = route_closed_for_enterprise_idp`.

**Required capability:** `users.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `user_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer_uri` | string | Yes | format: uri |

Additional fields are not accepted.

**Request example:**

```json
{
  "external_subject": "acme-user-123",
  "issuer_uri": "https://identity.acme.example"
}
```

### users-federation-binding Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `access_resend_event_id` | string or null | No |  |
| `created_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))$` |
| `display_name` | string or null | No |  |
| `email` | string or null | No |  |
| `email_changed_at` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `federation` | object or null | No |  |
| `federation_conflict` | string or null | No |  |
| `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)$` |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `last_suspended_at` | string or null | No |  |
| `previous_email` | string or null | No |  |
| `recovered_at` | string or null | No |  |
| `recovery_id` | string or null | No |  |
| `recovery_request` | object or null | No |  |
| `recovery_requested_at` | string or null | No |  |
| `resource` | "human_actor" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|clients\|platform-operators)\/([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})$` |
| `status` | "active" / "suspended" / "deactivated" / "pending_activation" / "invited" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.access_resend_event_id

At least one alternative must match.

###### application/json body.access_resend_event_id: alternative 1

Type: `string`. 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)$`

###### application/json body.access_resend_event_id: alternative 2

Type: `null`. 

##### application/json body.display_name

At least one alternative must match.

###### application/json body.display_name: alternative 1

Type: `string`. 

###### application/json body.display_name: alternative 2

Type: `null`. 

##### application/json body.email

At least one alternative must match.

###### application/json body.email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.email: alternative 2

Type: `null`. 

##### application/json body.email_changed_at

At least one alternative must match.

###### application/json body.email_changed_at: alternative 1

Type: `string`. 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))$`

###### application/json body.email_changed_at: alternative 2

Type: `null`. 

##### application/json body.federation

At least one alternative must match.

###### application/json body.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.federation: alternative 2

Type: `null`. 

##### application/json body.federation_conflict

At least one alternative must match.

###### application/json body.federation_conflict: alternative 1

Type: `string`. 

###### application/json body.federation_conflict: alternative 2

Type: `null`. 

##### application/json body.last_suspended_at

At least one alternative must match.

###### application/json body.last_suspended_at: alternative 1

Type: `string`. 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))$`

###### application/json body.last_suspended_at: alternative 2

Type: `null`. 

##### application/json body.previous_email

At least one alternative must match.

###### application/json body.previous_email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.previous_email: alternative 2

Type: `null`. 

##### application/json body.recovered_at

At least one alternative must match.

###### application/json body.recovered_at: alternative 1

Type: `string`. 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))$`

###### application/json body.recovered_at: alternative 2

Type: `null`. 

##### application/json body.recovery_id

At least one alternative must match.

###### application/json body.recovery_id: alternative 1

Type: `string`. 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)$`

###### application/json body.recovery_id: alternative 2

Type: `null`. 

##### application/json body.recovery_request

At least one alternative must match.

###### application/json body.recovery_request: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_id` | string or null | Yes |  |
| `created_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))$` |
| `new_email` | string or null | Yes |  |
| `reason` | string or null | Yes |  |
| `request_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)$` |
| `state` | "awaiting" / "executed" / "completed" / "failed" / "rejected" / "expired" / "cancelled" / "aborted" / "superseded" | Yes |  |

Additional fields are not accepted.

###### application/json body.recovery_request: alternative 1.approval_id

At least one alternative must match.

###### application/json body.recovery_request: alternative 1.approval_id: alternative 1

Type: `string`. 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)$`

###### application/json body.recovery_request: alternative 1.approval_id: alternative 2

Type: `null`. 

###### application/json body.recovery_request: alternative 1.new_email

At least one alternative must match.

###### application/json body.recovery_request: alternative 1.new_email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.recovery_request: alternative 1.new_email: alternative 2

Type: `null`. 

###### application/json body.recovery_request: alternative 1.reason

At least one alternative must match.

###### application/json body.recovery_request: alternative 1.reason: alternative 1

Type: `string`. 

###### application/json body.recovery_request: alternative 1.reason: alternative 2

Type: `null`. 

###### application/json body.recovery_request: alternative 2

Type: `null`. 

##### application/json body.recovery_requested_at

At least one alternative must match.

###### application/json body.recovery_requested_at: alternative 1

Type: `string`. 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))$`

###### application/json body.recovery_requested_at: alternative 2

Type: `null`.


### users-federation-binding 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.


### users-federation-binding Response 401 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.


### users-federation-binding Response 403 schema

Content type: `application/json`.

See [response 401 schema](#users-federation-binding-response-401-schema).


### users-federation-binding Response 404 schema

Content type: `application/json`.

See [response 401 schema](#users-federation-binding-response-401-schema).


### users-federation-binding Response 409 schema

Content type: `application/json`.

See [response 401 schema](#users-federation-binding-response-401-schema).


### users-federation-binding Response 500 schema

Content type: `application/json`.

See [response 401 schema](#users-federation-binding-response-401-schema).


### users-federation-binding Response 502 schema

Content type: `application/json`.

See [response 400 schema](#users-federation-binding-response-400-schema).


### users-federation-binding Response 503 schema

Content type: `application/json`.

See [response 400 schema](#users-federation-binding-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "created_at": "2026-05-01T10:00:00Z",
    "display_name": "Jane Doe",
    "email": "jane.doe@acme.example",
    "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
    "federation": {
      "external_subject": "acme-user-123",
      "issuer": "https://identity.acme.example"
    },
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "identity_source": "federated",
    "resource": "human_actor",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00.000Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /users/{user_id}/federation-conflict

**Report a federation conflict**

The enterprise identity backend reports an identity it will not overwrite. Shown on the enterprise card; only platform staff clear it.

**Required capability:** `users.activate_federated`

**Authentication:** Bearer token required.

**Parameters:**

- `user_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `code` | string or null | No |  |
| `reason` | "email_taken_by_other_actor" / "email_taken_by_unbound_identity" / "activation_refused" | Yes |  |

Additional fields are not accepted.

#### Request body schema.code

At least one alternative must match.

##### Request body schema.code: alternative 1

Type: `string`. maxLength: 128

##### Request body schema.code: alternative 2

Type: `null`.

### users-federation-conflict Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `access_resend_event_id` | string or null | No |  |
| `created_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))$` |
| `display_name` | string or null | No |  |
| `email` | string or null | No |  |
| `email_changed_at` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `federation` | object or null | No |  |
| `federation_conflict` | string or null | No |  |
| `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)$` |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `last_suspended_at` | string or null | No |  |
| `previous_email` | string or null | No |  |
| `recovered_at` | string or null | No |  |
| `recovery_id` | string or null | No |  |
| `recovery_request` | object or null | No |  |
| `recovery_requested_at` | string or null | No |  |
| `resource` | "human_actor" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|clients\|platform-operators)\/([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})$` |
| `status` | "active" / "suspended" / "deactivated" / "pending_activation" / "invited" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.access_resend_event_id

At least one alternative must match.

###### application/json body.access_resend_event_id: alternative 1

Type: `string`. 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)$`

###### application/json body.access_resend_event_id: alternative 2

Type: `null`. 

##### application/json body.display_name

At least one alternative must match.

###### application/json body.display_name: alternative 1

Type: `string`. 

###### application/json body.display_name: alternative 2

Type: `null`. 

##### application/json body.email

At least one alternative must match.

###### application/json body.email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.email: alternative 2

Type: `null`. 

##### application/json body.email_changed_at

At least one alternative must match.

###### application/json body.email_changed_at: alternative 1

Type: `string`. 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))$`

###### application/json body.email_changed_at: alternative 2

Type: `null`. 

##### application/json body.federation

At least one alternative must match.

###### application/json body.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.federation: alternative 2

Type: `null`. 

##### application/json body.federation_conflict

At least one alternative must match.

###### application/json body.federation_conflict: alternative 1

Type: `string`. 

###### application/json body.federation_conflict: alternative 2

Type: `null`. 

##### application/json body.last_suspended_at

At least one alternative must match.

###### application/json body.last_suspended_at: alternative 1

Type: `string`. 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))$`

###### application/json body.last_suspended_at: alternative 2

Type: `null`. 

##### application/json body.previous_email

At least one alternative must match.

###### application/json body.previous_email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.previous_email: alternative 2

Type: `null`. 

##### application/json body.recovered_at

At least one alternative must match.

###### application/json body.recovered_at: alternative 1

Type: `string`. 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))$`

###### application/json body.recovered_at: alternative 2

Type: `null`. 

##### application/json body.recovery_id

At least one alternative must match.

###### application/json body.recovery_id: alternative 1

Type: `string`. 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)$`

###### application/json body.recovery_id: alternative 2

Type: `null`. 

##### application/json body.recovery_request

At least one alternative must match.

###### application/json body.recovery_request: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_id` | string or null | Yes |  |
| `created_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))$` |
| `new_email` | string or null | Yes |  |
| `reason` | string or null | Yes |  |
| `request_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)$` |
| `state` | "awaiting" / "executed" / "completed" / "failed" / "rejected" / "expired" / "cancelled" / "aborted" / "superseded" | Yes |  |

Additional fields are not accepted.

###### application/json body.recovery_request: alternative 1.approval_id

At least one alternative must match.

###### application/json body.recovery_request: alternative 1.approval_id: alternative 1

Type: `string`. 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)$`

###### application/json body.recovery_request: alternative 1.approval_id: alternative 2

Type: `null`. 

###### application/json body.recovery_request: alternative 1.new_email

At least one alternative must match.

###### application/json body.recovery_request: alternative 1.new_email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.recovery_request: alternative 1.new_email: alternative 2

Type: `null`. 

###### application/json body.recovery_request: alternative 1.reason

At least one alternative must match.

###### application/json body.recovery_request: alternative 1.reason: alternative 1

Type: `string`. 

###### application/json body.recovery_request: alternative 1.reason: alternative 2

Type: `null`. 

###### application/json body.recovery_request: alternative 2

Type: `null`. 

##### application/json body.recovery_requested_at

At least one alternative must match.

###### application/json body.recovery_requested_at: alternative 1

Type: `string`. 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))$`

###### application/json body.recovery_requested_at: alternative 2

Type: `null`.


### users-federation-conflict 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.


### users-federation-conflict Response 401 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.


### users-federation-conflict Response 403 schema

Content type: `application/json`.

See [response 401 schema](#users-federation-conflict-response-401-schema).


### users-federation-conflict Response 404 schema

Content type: `application/json`.

See [response 401 schema](#users-federation-conflict-response-401-schema).


### users-federation-conflict Response 409 schema

Content type: `application/json`.

See [response 401 schema](#users-federation-conflict-response-401-schema).


### users-federation-conflict Response 500 schema

Content type: `application/json`.

See [response 401 schema](#users-federation-conflict-response-401-schema).


### users-federation-conflict Response 502 schema

Content type: `application/json`.

See [response 400 schema](#users-federation-conflict-response-400-schema).


### users-federation-conflict Response 503 schema

Content type: `application/json`.

See [response 400 schema](#users-federation-conflict-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "created_at": "2026-05-01T10:00:00Z",
    "display_name": "Jane Doe",
    "email": "jane.doe@acme.example",
    "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
    "federation": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "identity_source": "platform-managed",
    "resource": "human_actor",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00.000Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### DELETE /users/{user_id}/federation-conflict

**Clear a federation conflict**

Clears a resolved conflict. Requires a platform-operator binding and `users.manage` on an `enterprise_wildcard` grant anchored at `platform-operators/<id>`.

**Required capability:** `users.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `user_id` `string` (path) *(required)*

### users-federation-conflict-delete Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `access_resend_event_id` | string or null | No |  |
| `created_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))$` |
| `display_name` | string or null | No |  |
| `email` | string or null | No |  |
| `email_changed_at` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `federation` | object or null | No |  |
| `federation_conflict` | string or null | No |  |
| `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)$` |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `last_suspended_at` | string or null | No |  |
| `previous_email` | string or null | No |  |
| `recovered_at` | string or null | No |  |
| `recovery_id` | string or null | No |  |
| `recovery_request` | object or null | No |  |
| `recovery_requested_at` | string or null | No |  |
| `resource` | "human_actor" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|clients\|platform-operators)\/([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})$` |
| `status` | "active" / "suspended" / "deactivated" / "pending_activation" / "invited" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.access_resend_event_id

At least one alternative must match.

###### application/json body.access_resend_event_id: alternative 1

Type: `string`. 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)$`

###### application/json body.access_resend_event_id: alternative 2

Type: `null`. 

##### application/json body.display_name

At least one alternative must match.

###### application/json body.display_name: alternative 1

Type: `string`. 

###### application/json body.display_name: alternative 2

Type: `null`. 

##### application/json body.email

At least one alternative must match.

###### application/json body.email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.email: alternative 2

Type: `null`. 

##### application/json body.email_changed_at

At least one alternative must match.

###### application/json body.email_changed_at: alternative 1

Type: `string`. 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))$`

###### application/json body.email_changed_at: alternative 2

Type: `null`. 

##### application/json body.federation

At least one alternative must match.

###### application/json body.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.federation: alternative 2

Type: `null`. 

##### application/json body.federation_conflict

At least one alternative must match.

###### application/json body.federation_conflict: alternative 1

Type: `string`. 

###### application/json body.federation_conflict: alternative 2

Type: `null`. 

##### application/json body.last_suspended_at

At least one alternative must match.

###### application/json body.last_suspended_at: alternative 1

Type: `string`. 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))$`

###### application/json body.last_suspended_at: alternative 2

Type: `null`. 

##### application/json body.previous_email

At least one alternative must match.

###### application/json body.previous_email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.previous_email: alternative 2

Type: `null`. 

##### application/json body.recovered_at

At least one alternative must match.

###### application/json body.recovered_at: alternative 1

Type: `string`. 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))$`

###### application/json body.recovered_at: alternative 2

Type: `null`. 

##### application/json body.recovery_id

At least one alternative must match.

###### application/json body.recovery_id: alternative 1

Type: `string`. 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)$`

###### application/json body.recovery_id: alternative 2

Type: `null`. 

##### application/json body.recovery_request

At least one alternative must match.

###### application/json body.recovery_request: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_id` | string or null | Yes |  |
| `created_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))$` |
| `new_email` | string or null | Yes |  |
| `reason` | string or null | Yes |  |
| `request_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)$` |
| `state` | "awaiting" / "executed" / "completed" / "failed" / "rejected" / "expired" / "cancelled" / "aborted" / "superseded" | Yes |  |

Additional fields are not accepted.

###### application/json body.recovery_request: alternative 1.approval_id

At least one alternative must match.

###### application/json body.recovery_request: alternative 1.approval_id: alternative 1

Type: `string`. 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)$`

###### application/json body.recovery_request: alternative 1.approval_id: alternative 2

Type: `null`. 

###### application/json body.recovery_request: alternative 1.new_email

At least one alternative must match.

###### application/json body.recovery_request: alternative 1.new_email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.recovery_request: alternative 1.new_email: alternative 2

Type: `null`. 

###### application/json body.recovery_request: alternative 1.reason

At least one alternative must match.

###### application/json body.recovery_request: alternative 1.reason: alternative 1

Type: `string`. 

###### application/json body.recovery_request: alternative 1.reason: alternative 2

Type: `null`. 

###### application/json body.recovery_request: alternative 2

Type: `null`. 

##### application/json body.recovery_requested_at

At least one alternative must match.

###### application/json body.recovery_requested_at: alternative 1

Type: `string`. 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))$`

###### application/json body.recovery_requested_at: alternative 2

Type: `null`.


### users-federation-conflict-delete 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.


### users-federation-conflict-delete Response 401 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.


### users-federation-conflict-delete Response 403 schema

Content type: `application/json`.

See [response 401 schema](#users-federation-conflict-delete-response-401-schema).


### users-federation-conflict-delete Response 404 schema

Content type: `application/json`.

See [response 401 schema](#users-federation-conflict-delete-response-401-schema).


### users-federation-conflict-delete Response 500 schema

Content type: `application/json`.

See [response 401 schema](#users-federation-conflict-delete-response-401-schema).


### users-federation-conflict-delete Response 502 schema

Content type: `application/json`.

See [response 400 schema](#users-federation-conflict-delete-response-400-schema).


### users-federation-conflict-delete Response 503 schema

Content type: `application/json`.

See [response 400 schema](#users-federation-conflict-delete-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "created_at": "2026-05-01T10:00:00Z",
    "display_name": "Jane Doe",
    "email": "jane.doe@acme.example",
    "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
    "federation": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "identity_source": "platform-managed",
    "resource": "human_actor",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00.000Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /users/{user_id}/hosted-access

**Grant hosted sign-in access to platform staff**

Provisions hosted sign-in access for an existing user parented to a platform operator. The user must have an email address; the workspace is derived from the stored user and is not a request field. Send no request body. Available on development and sandbox deployments; production returns `409 state_conflict` with `data.reason = not_supported` because staff use corporate SSO there.

**Required capability:** `users.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `user_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

### users-hosted-access Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `subject_id` | string | Yes | minLength: 1 |

Additional fields are not accepted.


### users-hosted-access 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.


### users-hosted-access Response 401 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.


### users-hosted-access Response 403 schema

Content type: `application/json`.

See [response 401 schema](#users-hosted-access-response-401-schema).


### users-hosted-access Response 404 schema

Content type: `application/json`.

See [response 401 schema](#users-hosted-access-response-401-schema).


### users-hosted-access Response 409 schema

Content type: `application/json`.

See [response 401 schema](#users-hosted-access-response-401-schema).


### users-hosted-access Response 500 schema

Content type: `application/json`.

See [response 401 schema](#users-hosted-access-response-401-schema).


### users-hosted-access Response 502 schema

Content type: `application/json`.

See [response 400 schema](#users-hosted-access-response-400-schema).


### users-hosted-access Response 503 schema

Content type: `application/json`.

See [response 400 schema](#users-hosted-access-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "subject_id": "hosted-staff-123"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /users/{user_id}/reactivate

**Reactivate user**

**Required capability:** `users.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `user_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `reason` | string or null | No |  |

Additional fields are not accepted.

#### Request body schema.reason

At least one alternative must match.

##### Request body schema.reason: alternative 1

Type: `string`. 

##### Request body schema.reason: alternative 2

Type: `null`.

### users-reactivate Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `access_resend_event_id` | string or null | No |  |
| `created_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))$` |
| `display_name` | string or null | No |  |
| `email` | string or null | No |  |
| `email_changed_at` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `federation` | object or null | No |  |
| `federation_conflict` | string or null | No |  |
| `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)$` |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `last_suspended_at` | string or null | No |  |
| `previous_email` | string or null | No |  |
| `recovered_at` | string or null | No |  |
| `recovery_id` | string or null | No |  |
| `recovery_request` | object or null | No |  |
| `recovery_requested_at` | string or null | No |  |
| `resource` | "human_actor" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|clients\|platform-operators)\/([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})$` |
| `status` | "active" / "suspended" / "deactivated" / "pending_activation" / "invited" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.access_resend_event_id

At least one alternative must match.

###### application/json body.access_resend_event_id: alternative 1

Type: `string`. 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)$`

###### application/json body.access_resend_event_id: alternative 2

Type: `null`. 

##### application/json body.display_name

At least one alternative must match.

###### application/json body.display_name: alternative 1

Type: `string`. 

###### application/json body.display_name: alternative 2

Type: `null`. 

##### application/json body.email

At least one alternative must match.

###### application/json body.email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.email: alternative 2

Type: `null`. 

##### application/json body.email_changed_at

At least one alternative must match.

###### application/json body.email_changed_at: alternative 1

Type: `string`. 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))$`

###### application/json body.email_changed_at: alternative 2

Type: `null`. 

##### application/json body.federation

At least one alternative must match.

###### application/json body.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.federation: alternative 2

Type: `null`. 

##### application/json body.federation_conflict

At least one alternative must match.

###### application/json body.federation_conflict: alternative 1

Type: `string`. 

###### application/json body.federation_conflict: alternative 2

Type: `null`. 

##### application/json body.last_suspended_at

At least one alternative must match.

###### application/json body.last_suspended_at: alternative 1

Type: `string`. 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))$`

###### application/json body.last_suspended_at: alternative 2

Type: `null`. 

##### application/json body.previous_email

At least one alternative must match.

###### application/json body.previous_email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.previous_email: alternative 2

Type: `null`. 

##### application/json body.recovered_at

At least one alternative must match.

###### application/json body.recovered_at: alternative 1

Type: `string`. 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))$`

###### application/json body.recovered_at: alternative 2

Type: `null`. 

##### application/json body.recovery_id

At least one alternative must match.

###### application/json body.recovery_id: alternative 1

Type: `string`. 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)$`

###### application/json body.recovery_id: alternative 2

Type: `null`. 

##### application/json body.recovery_request

At least one alternative must match.

###### application/json body.recovery_request: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_id` | string or null | Yes |  |
| `created_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))$` |
| `new_email` | string or null | Yes |  |
| `reason` | string or null | Yes |  |
| `request_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)$` |
| `state` | "awaiting" / "executed" / "completed" / "failed" / "rejected" / "expired" / "cancelled" / "aborted" / "superseded" | Yes |  |

Additional fields are not accepted.

###### application/json body.recovery_request: alternative 1.approval_id

At least one alternative must match.

###### application/json body.recovery_request: alternative 1.approval_id: alternative 1

Type: `string`. 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)$`

###### application/json body.recovery_request: alternative 1.approval_id: alternative 2

Type: `null`. 

###### application/json body.recovery_request: alternative 1.new_email

At least one alternative must match.

###### application/json body.recovery_request: alternative 1.new_email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.recovery_request: alternative 1.new_email: alternative 2

Type: `null`. 

###### application/json body.recovery_request: alternative 1.reason

At least one alternative must match.

###### application/json body.recovery_request: alternative 1.reason: alternative 1

Type: `string`. 

###### application/json body.recovery_request: alternative 1.reason: alternative 2

Type: `null`. 

###### application/json body.recovery_request: alternative 2

Type: `null`. 

##### application/json body.recovery_requested_at

At least one alternative must match.

###### application/json body.recovery_requested_at: alternative 1

Type: `string`. 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))$`

###### application/json body.recovery_requested_at: alternative 2

Type: `null`.


### users-reactivate 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.


### users-reactivate Response 401 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.


### users-reactivate Response 403 schema

Content type: `application/json`.

See [response 401 schema](#users-reactivate-response-401-schema).


### users-reactivate Response 404 schema

Content type: `application/json`.

See [response 401 schema](#users-reactivate-response-401-schema).


### users-reactivate Response 409 schema

Content type: `application/json`.

See [response 401 schema](#users-reactivate-response-401-schema).


### users-reactivate Response 500 schema

Content type: `application/json`.

See [response 401 schema](#users-reactivate-response-401-schema).


### users-reactivate Response 502 schema

Content type: `application/json`.

See [response 400 schema](#users-reactivate-response-400-schema).


### users-reactivate Response 503 schema

Content type: `application/json`.

See [response 400 schema](#users-reactivate-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "created_at": "2026-05-01T10:00:00Z",
    "display_name": "Jane Doe",
    "email": "jane.doe@acme.example",
    "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
    "federation": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "identity_source": "platform-managed",
    "resource": "human_actor",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00.000Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /users/{user_id}/recovery

**Open an access recovery**

Platform support, after verifying the person out of band, opens an `identity.recovery` request; a compliance member approves it. Requires `users.recovery_initiate`. `expected_email` is the address support verified; `409 recovery_email_changed` when the user’s email is no longer that one. `400 recovery_verification_required` without `verification_ref`; `409 recovery_not_applicable`, `recovery_already_pending`, `recovery_new_email_taken`.

**Required capability:** `users.recovery_initiate`

**Authentication:** Bearer token required.

**Parameters:**

- `user_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `expected_email` | string | Yes | format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$` |
| `new_email` | string or null | No |  |
| `verification_method` | "video_call" / "kyb_representative" / "document_check" / "other" | Yes |  |
| `verification_ref` | string | No | minLength: 1; maxLength: 512 |

Additional fields are not accepted.

#### Request body schema.new_email

At least one alternative must match.

##### Request body schema.new_email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

##### Request body schema.new_email: alternative 2

Type: `null`.

### users-recovery Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_ref` | string or null | Yes |  |
| `recovery_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)$` |
| `request_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.

##### application/json body.approval_ref

At least one alternative must match.

###### application/json body.approval_ref: alternative 1

Type: `string`. 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)$`

###### application/json body.approval_ref: alternative 2

Type: `null`.


### users-recovery 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.


### users-recovery Response 401 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.


### users-recovery Response 403 schema

Content type: `application/json`.

See [response 401 schema](#users-recovery-response-401-schema).


### users-recovery Response 404 schema

Content type: `application/json`.

See [response 401 schema](#users-recovery-response-401-schema).


### users-recovery Response 409 schema

Content type: `application/json`.

See [response 401 schema](#users-recovery-response-401-schema).


### users-recovery Response 500 schema

Content type: `application/json`.

See [response 401 schema](#users-recovery-response-401-schema).


### users-recovery Response 502 schema

Content type: `application/json`.

See [response 400 schema](#users-recovery-response-400-schema).


### users-recovery Response 503 schema

Content type: `application/json`.

See [response 400 schema](#users-recovery-response-400-schema).


**Responses:**

- `201` — Resource created successfully.
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /users/{user_id}/recovery-request

**Flag a user for access recovery**

The enterprise asks the platform to recover a user’s access. Changes nothing else and creates no approval. On an enterprise that runs its own identity stack only an enterprise-bound caller may: platform staff get `403 platform_cannot_manage_federated_actor`.

**Required capability:** `users.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `user_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

### users-recovery-request Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `recovery_requested_at` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.recovery_requested_at

At least one alternative must match.

###### application/json body.recovery_requested_at: alternative 1

Type: `string`. 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))$`

###### application/json body.recovery_requested_at: alternative 2

Type: `null`.


### users-recovery-request 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.


### users-recovery-request Response 401 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.


### users-recovery-request Response 403 schema

Content type: `application/json`.

See [response 401 schema](#users-recovery-request-response-401-schema).


### users-recovery-request Response 404 schema

Content type: `application/json`.

See [response 401 schema](#users-recovery-request-response-401-schema).


### users-recovery-request Response 409 schema

Content type: `application/json`.

See [response 401 schema](#users-recovery-request-response-401-schema).


### users-recovery-request Response 500 schema

Content type: `application/json`.

See [response 401 schema](#users-recovery-request-response-401-schema).


### users-recovery-request Response 502 schema

Content type: `application/json`.

See [response 400 schema](#users-recovery-request-response-400-schema).


### users-recovery-request Response 503 schema

Content type: `application/json`.

See [response 400 schema](#users-recovery-request-response-400-schema).


**Responses:**

- `200` — Operation succeeded.
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /users/{user_id}/suspend

**Suspend user**

**Required capability:** `users.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `user_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `reason` | string or null | No |  |

Additional fields are not accepted.

#### Request body schema.reason

At least one alternative must match.

##### Request body schema.reason: alternative 1

Type: `string`. 

##### Request body schema.reason: alternative 2

Type: `null`.

### users-suspend Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `access_resend_event_id` | string or null | No |  |
| `created_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))$` |
| `display_name` | string or null | No |  |
| `email` | string or null | No |  |
| `email_changed_at` | string or null | No |  |
| `etag` | string | Yes | minLength: 1 |
| `federation` | object or null | No |  |
| `federation_conflict` | string or null | No |  |
| `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)$` |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `last_suspended_at` | string or null | No |  |
| `previous_email` | string or null | No |  |
| `recovered_at` | string or null | No |  |
| `recovery_id` | string or null | No |  |
| `recovery_request` | object or null | No |  |
| `recovery_requested_at` | string or null | No |  |
| `resource` | "human_actor" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|clients\|platform-operators)\/([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})$` |
| `status` | "active" / "suspended" / "deactivated" / "pending_activation" / "invited" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.access_resend_event_id

At least one alternative must match.

###### application/json body.access_resend_event_id: alternative 1

Type: `string`. 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)$`

###### application/json body.access_resend_event_id: alternative 2

Type: `null`. 

##### application/json body.display_name

At least one alternative must match.

###### application/json body.display_name: alternative 1

Type: `string`. 

###### application/json body.display_name: alternative 2

Type: `null`. 

##### application/json body.email

At least one alternative must match.

###### application/json body.email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.email: alternative 2

Type: `null`. 

##### application/json body.email_changed_at

At least one alternative must match.

###### application/json body.email_changed_at: alternative 1

Type: `string`. 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))$`

###### application/json body.email_changed_at: alternative 2

Type: `null`. 

##### application/json body.federation

At least one alternative must match.

###### application/json body.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.federation: alternative 2

Type: `null`. 

##### application/json body.federation_conflict

At least one alternative must match.

###### application/json body.federation_conflict: alternative 1

Type: `string`. 

###### application/json body.federation_conflict: alternative 2

Type: `null`. 

##### application/json body.last_suspended_at

At least one alternative must match.

###### application/json body.last_suspended_at: alternative 1

Type: `string`. 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))$`

###### application/json body.last_suspended_at: alternative 2

Type: `null`. 

##### application/json body.previous_email

At least one alternative must match.

###### application/json body.previous_email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.previous_email: alternative 2

Type: `null`. 

##### application/json body.recovered_at

At least one alternative must match.

###### application/json body.recovered_at: alternative 1

Type: `string`. 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))$`

###### application/json body.recovered_at: alternative 2

Type: `null`. 

##### application/json body.recovery_id

At least one alternative must match.

###### application/json body.recovery_id: alternative 1

Type: `string`. 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)$`

###### application/json body.recovery_id: alternative 2

Type: `null`. 

##### application/json body.recovery_request

At least one alternative must match.

###### application/json body.recovery_request: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_id` | string or null | Yes |  |
| `created_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))$` |
| `new_email` | string or null | Yes |  |
| `reason` | string or null | Yes |  |
| `request_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)$` |
| `state` | "awaiting" / "executed" / "completed" / "failed" / "rejected" / "expired" / "cancelled" / "aborted" / "superseded" | Yes |  |

Additional fields are not accepted.

###### application/json body.recovery_request: alternative 1.approval_id

At least one alternative must match.

###### application/json body.recovery_request: alternative 1.approval_id: alternative 1

Type: `string`. 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)$`

###### application/json body.recovery_request: alternative 1.approval_id: alternative 2

Type: `null`. 

###### application/json body.recovery_request: alternative 1.new_email

At least one alternative must match.

###### application/json body.recovery_request: alternative 1.new_email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.recovery_request: alternative 1.new_email: alternative 2

Type: `null`. 

###### application/json body.recovery_request: alternative 1.reason

At least one alternative must match.

###### application/json body.recovery_request: alternative 1.reason: alternative 1

Type: `string`. 

###### application/json body.recovery_request: alternative 1.reason: alternative 2

Type: `null`. 

###### application/json body.recovery_request: alternative 2

Type: `null`. 

##### application/json body.recovery_requested_at

At least one alternative must match.

###### application/json body.recovery_requested_at: alternative 1

Type: `string`. 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))$`

###### application/json body.recovery_requested_at: alternative 2

Type: `null`.


### users-suspend 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.


### users-suspend Response 401 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.


### users-suspend Response 403 schema

Content type: `application/json`.

See [response 401 schema](#users-suspend-response-401-schema).


### users-suspend Response 404 schema

Content type: `application/json`.

See [response 401 schema](#users-suspend-response-401-schema).


### users-suspend Response 409 schema

Content type: `application/json`.

See [response 401 schema](#users-suspend-response-401-schema).


### users-suspend Response 500 schema

Content type: `application/json`.

See [response 401 schema](#users-suspend-response-401-schema).


### users-suspend Response 502 schema

Content type: `application/json`.

See [response 400 schema](#users-suspend-response-400-schema).


### users-suspend Response 503 schema

Content type: `application/json`.

See [response 400 schema](#users-suspend-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "created_at": "2026-05-01T10:00:00Z",
    "display_name": "Jane Doe",
    "email": "jane.doe@acme.example",
    "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
    "federation": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "identity_source": "platform-managed",
    "last_suspended_at": "2026-05-01T10:00:00Z",
    "resource": "human_actor",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "suspended",
    "updated_at": "2026-05-01T10:00:00.000Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Service Accounts

### GET /service-accounts

**List service accounts**

**Required capability:** `service_accounts.read`

**Authentication:** Bearer token required.

**Parameters:**

- `parent_ref` `string` (query) *(required)*
- `status` `string` (query)
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### service-accounts-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

Public service account resource. The account itself has no expiry; only client secrets and access tokens have independent TTLs.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `description` | string or null | Yes |  |
| `created_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))$` |
| `current_secret_expires_at` | string or null | Yes | Expiry of the currently active client secret, or null for an account with no secret (an enterprise backend authenticating with private_key_jwt). The service account itself never expires on a timer, and JWT access-token TTL is separate. |
| `etag` | string | Yes | minLength: 1 |
| `external_id` | string or null | Yes |  |
| `id` | string | Yes | Stable service account identifier. Matches `client_id` and the trailing id segment of `principal_ref`. 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)$` |
| `managed_by` | string or null | Yes | Identity provider that manages this system account; null for tenant-created accounts. Managed accounts cannot be revoked or have their secret rotated through the service-account API. |
| `parent_ref` | string | Yes | pattern: `^(enterprises\|clients)\/([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})$` |
| `previous_secret_expires_at` | string or null | Yes | Expiry of the previous client secret during a rotation grace window, or null when no previous secret remains valid. |
| `principal_ref` | string | Yes | principal_ref ≡ service-accounts/{client_id} ≡ service-accounts/{id} pattern: `^(service-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})$` |
| `resource` | "service_account" | Yes |  |
| `status` | "active" / "revoked" | Yes | Service accounts do not expire on a timer. Lifecycle is status-only: `active` or `revoked`. |
| `updated_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))$` |

Additional fields are not accepted.

###### application/json body.items item.description

At least one alternative must match.

###### application/json body.items item.description: alternative 1

Type: `string`. 

###### application/json body.items item.description: alternative 2

Type: `null`. 

###### application/json body.items item.current_secret_expires_at

Expiry of the currently active client secret, or null for an account with no secret (an enterprise backend authenticating with private_key_jwt). The service account itself never expires on a timer, and JWT access-token TTL is separate.

At least one alternative must match.

###### application/json body.items item.current_secret_expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.current_secret_expires_at: alternative 2

Type: `null`. 

###### application/json body.items item.external_id

At least one alternative must match.

###### application/json body.items item.external_id: alternative 1

Type: `string`. 

###### application/json body.items item.external_id: alternative 2

Type: `null`. 

###### application/json body.items item.managed_by

Identity provider that manages this system account; null for tenant-created accounts. Managed accounts cannot be revoked or have their secret rotated through the service-account API.

At least one alternative must match.

###### application/json body.items item.managed_by: alternative 1

Type: `string`. 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)$`

###### application/json body.items item.managed_by: alternative 2

Type: `null`. 

###### application/json body.items item.previous_secret_expires_at

Expiry of the previous client secret during a rotation grace window, or null when no previous secret remains valid.

At least one alternative must match.

###### application/json body.items item.previous_secret_expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.previous_secret_expires_at: alternative 2

Type: `null`. 

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. 

###### application/json body.next_page_token: alternative 2

Type: `null`.


### service-accounts-list 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.


### service-accounts-list Response 401 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.


### service-accounts-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#service-accounts-list-response-401-schema).


### service-accounts-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#service-accounts-list-response-401-schema).


### service-accounts-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#service-accounts-list-response-400-schema).


### service-accounts-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#service-accounts-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "description": "Withdrawal automation account",
        "created_at": "2026-05-01T10:00:00Z",
        "current_secret_expires_at": "2026-05-02T10:00:00Z",
        "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
        "external_id": "sa-ext-001",
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "managed_by": null,
        "parent_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "previous_secret_expires_at": null,
        "principal_ref": "service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "resource": "service_account",
        "status": "active",
        "updated_at": "2026-05-01T10:00:00Z"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /service-accounts

**Create service account**

Creates a service account and mints a fresh `client_secret`. The plaintext secret is returned in this issuance response; ordinary reads do not return it. Store it immediately. A retry with the same Idempotency-Key returns the account created by the first request, without its `client_secret`, instead of creating a second one. Use `service_accounts.rotate_secret` to issue a new secret if the original response was lost. The service account itself never expires on a timer; lifecycle is status-only (`active` or `revoked`). `client_secret_expires_at` is the client-secret TTL, while JWT access-token TTL is separate. `client_secret_ttl_seconds` is optional, has a minimum of 60 seconds and no maximum; omission uses the deployment default. The parent must be an enterprise or client. Managed accounts (`managed_by` is non-null) cannot be revoked or rotated here.

**Required capability:** `service_accounts.create`

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `description` | string or null | No |  |
| `client_secret_ttl_seconds` | integer | No | minimum: 60; maximum: 9007199254740991 |
| `external_id` | string or null | No |  |
| `parent_ref` | string | Yes | pattern: `^(enterprises\|clients)\/([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})$` |

Additional fields are not accepted.

#### Request body schema.description

At least one alternative must match.

##### Request body schema.description: alternative 1

Type: `string`. 

##### Request body schema.description: alternative 2

Type: `null`. 

#### Request body schema.external_id

At least one alternative must match.

##### Request body schema.external_id: alternative 1

Type: `string`. 

##### Request body schema.external_id: alternative 2

Type: `null`.

**Request example:**

```json
{
  "description": "Withdrawal automation account",
  "external_id": "sa-ext-001",
  "parent_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}
```

### service-accounts-create Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `client_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)$` |
| `client_secret` | string | No | Present only in the first response. A retry with the same Idempotency-Key replays the response without it. minLength: 1 |
| `client_secret_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))$` |
| `principal_ref` | string | Yes | pattern: `^(service-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})$` |
| `service_account` | object | Yes | Public service account resource. The account itself has no expiry; only client secrets and access tokens have independent TTLs. No additional fields |

Additional fields are not accepted.

##### application/json body.service_account

Public service account resource. The account itself has no expiry; only client secrets and access tokens have independent TTLs.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `description` | string or null | Yes |  |
| `created_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))$` |
| `current_secret_expires_at` | string or null | Yes | Expiry of the currently active client secret, or null for an account with no secret (an enterprise backend authenticating with private_key_jwt). The service account itself never expires on a timer, and JWT access-token TTL is separate. |
| `etag` | string | Yes | minLength: 1 |
| `external_id` | string or null | Yes |  |
| `id` | string | Yes | Stable service account identifier. Matches `client_id` and the trailing id segment of `principal_ref`. 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)$` |
| `managed_by` | string or null | Yes | Identity provider that manages this system account; null for tenant-created accounts. Managed accounts cannot be revoked or have their secret rotated through the service-account API. |
| `parent_ref` | string | Yes | pattern: `^(enterprises\|clients)\/([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})$` |
| `previous_secret_expires_at` | string or null | Yes | Expiry of the previous client secret during a rotation grace window, or null when no previous secret remains valid. |
| `principal_ref` | string | Yes | principal_ref ≡ service-accounts/{client_id} ≡ service-accounts/{id} pattern: `^(service-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})$` |
| `resource` | "service_account" | Yes |  |
| `status` | "active" / "revoked" | Yes | Service accounts do not expire on a timer. Lifecycle is status-only: `active` or `revoked`. |
| `updated_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))$` |

Additional fields are not accepted.

###### application/json body.service_account.description

At least one alternative must match.

###### application/json body.service_account.description: alternative 1

Type: `string`. 

###### application/json body.service_account.description: alternative 2

Type: `null`. 

###### application/json body.service_account.current_secret_expires_at

Expiry of the currently active client secret, or null for an account with no secret (an enterprise backend authenticating with private_key_jwt). The service account itself never expires on a timer, and JWT access-token TTL is separate.

At least one alternative must match.

###### application/json body.service_account.current_secret_expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.service_account.current_secret_expires_at: alternative 2

Type: `null`. 

###### application/json body.service_account.external_id

At least one alternative must match.

###### application/json body.service_account.external_id: alternative 1

Type: `string`. 

###### application/json body.service_account.external_id: alternative 2

Type: `null`. 

###### application/json body.service_account.managed_by

Identity provider that manages this system account; null for tenant-created accounts. Managed accounts cannot be revoked or have their secret rotated through the service-account API.

At least one alternative must match.

###### application/json body.service_account.managed_by: alternative 1

Type: `string`. 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)$`

###### application/json body.service_account.managed_by: alternative 2

Type: `null`. 

###### application/json body.service_account.previous_secret_expires_at

Expiry of the previous client secret during a rotation grace window, or null when no previous secret remains valid.

At least one alternative must match.

###### application/json body.service_account.previous_secret_expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.service_account.previous_secret_expires_at: alternative 2

Type: `null`.


| Response header | Type | Description |
| --- | --- | --- |
| `Cache-Control` | "no-store" |  |

### service-accounts-create 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.


### service-accounts-create Response 401 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.


### service-accounts-create Response 403 schema

Content type: `application/json`.

See [response 401 schema](#service-accounts-create-response-401-schema).


### service-accounts-create Response 409 schema

Content type: `application/json`.

See [response 401 schema](#service-accounts-create-response-401-schema).


### service-accounts-create Response 500 schema

Content type: `application/json`.

See [response 401 schema](#service-accounts-create-response-401-schema).


### service-accounts-create Response 502 schema

Content type: `application/json`.

See [response 400 schema](#service-accounts-create-response-400-schema).


### service-accounts-create Response 503 schema

Content type: `application/json`.

See [response 400 schema](#service-accounts-create-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "client_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "client_secret": "cs_live_abc123placeholder",
    "client_secret_expires_at": "2026-05-02T10:00:00Z",
    "principal_ref": "service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "service_account": {
      "description": "Withdrawal automation account",
      "created_at": "2026-05-01T10:00:00Z",
      "current_secret_expires_at": "2026-05-02T10:00:00Z",
      "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
      "external_id": "sa-ext-001",
      "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "managed_by": null,
      "parent_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "previous_secret_expires_at": null,
      "principal_ref": "service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "resource": "service_account",
      "status": "active",
      "updated_at": "2026-05-01T10:00:00Z"
    }
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /service-accounts/{service_account_id}

**Get service account**

**Required capability:** `service_accounts.read`

**Authentication:** Bearer token required.

**Parameters:**

- `service_account_id` `string` (path) *(required)*

### service-accounts-get Response 200 schema

Content type: `application/json`.

#### application/json body

Public service account resource. The account itself has no expiry; only client secrets and access tokens have independent TTLs.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `description` | string or null | Yes |  |
| `created_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))$` |
| `current_secret_expires_at` | string or null | Yes | Expiry of the currently active client secret, or null for an account with no secret (an enterprise backend authenticating with private_key_jwt). The service account itself never expires on a timer, and JWT access-token TTL is separate. |
| `etag` | string | Yes | minLength: 1 |
| `external_id` | string or null | Yes |  |
| `id` | string | Yes | Stable service account identifier. Matches `client_id` and the trailing id segment of `principal_ref`. 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)$` |
| `managed_by` | string or null | Yes | Identity provider that manages this system account; null for tenant-created accounts. Managed accounts cannot be revoked or have their secret rotated through the service-account API. |
| `parent_ref` | string | Yes | pattern: `^(enterprises\|clients)\/([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})$` |
| `previous_secret_expires_at` | string or null | Yes | Expiry of the previous client secret during a rotation grace window, or null when no previous secret remains valid. |
| `principal_ref` | string | Yes | principal_ref ≡ service-accounts/{client_id} ≡ service-accounts/{id} pattern: `^(service-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})$` |
| `resource` | "service_account" | Yes |  |
| `status` | "active" / "revoked" | Yes | Service accounts do not expire on a timer. Lifecycle is status-only: `active` or `revoked`. |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.description

At least one alternative must match.

###### application/json body.description: alternative 1

Type: `string`. 

###### application/json body.description: alternative 2

Type: `null`. 

##### application/json body.current_secret_expires_at

Expiry of the currently active client secret, or null for an account with no secret (an enterprise backend authenticating with private_key_jwt). The service account itself never expires on a timer, and JWT access-token TTL is separate.

At least one alternative must match.

###### application/json body.current_secret_expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.current_secret_expires_at: alternative 2

Type: `null`. 

##### application/json body.external_id

At least one alternative must match.

###### application/json body.external_id: alternative 1

Type: `string`. 

###### application/json body.external_id: alternative 2

Type: `null`. 

##### application/json body.managed_by

Identity provider that manages this system account; null for tenant-created accounts. Managed accounts cannot be revoked or have their secret rotated through the service-account API.

At least one alternative must match.

###### application/json body.managed_by: alternative 1

Type: `string`. 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)$`

###### application/json body.managed_by: alternative 2

Type: `null`. 

##### application/json body.previous_secret_expires_at

Expiry of the previous client secret during a rotation grace window, or null when no previous secret remains valid.

At least one alternative must match.

###### application/json body.previous_secret_expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.previous_secret_expires_at: alternative 2

Type: `null`.


### service-accounts-get 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.


### service-accounts-get Response 401 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.


### service-accounts-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#service-accounts-get-response-401-schema).


### service-accounts-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#service-accounts-get-response-401-schema).


### service-accounts-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#service-accounts-get-response-401-schema).


### service-accounts-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#service-accounts-get-response-400-schema).


### service-accounts-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#service-accounts-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "description": "Withdrawal automation account",
    "created_at": "2026-05-01T10:00:00Z",
    "current_secret_expires_at": "2026-05-02T10:00:00Z",
    "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
    "external_id": "sa-ext-001",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "managed_by": null,
    "parent_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "previous_secret_expires_at": null,
    "principal_ref": "service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "resource": "service_account",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### PATCH /service-accounts/{service_account_id}

**Update service account**

Patch a service account. Requires `If-Match` from the resource GET response header. The body `etag` is the raw storage version; the HTTP `ETag` wraps that value as a weak entity tag.

**Required capability:** `service_accounts.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `service_account_id` `string` (path) *(required)*
- `If-Match` `string` (header) *(required)* — Weak entity tag from a prior GET. Mismatch causes the request to fail with 412 Precondition Failed.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `description` | string or null | No |  |
| `external_id` | string or null | No |  |

Additional fields are not accepted.

#### Request body schema.description

At least one alternative must match.

##### Request body schema.description: alternative 1

Type: `string`. 

##### Request body schema.description: alternative 2

Type: `null`. 

#### Request body schema.external_id

At least one alternative must match.

##### Request body schema.external_id: alternative 1

Type: `string`. 

##### Request body schema.external_id: alternative 2

Type: `null`.

**Request example:**

```json
{
  "description": "Updated description"
}
```

### service-accounts-update Response 200 schema

Content type: `application/json`.

#### application/json body

Public service account resource. The account itself has no expiry; only client secrets and access tokens have independent TTLs.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `description` | string or null | Yes |  |
| `created_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))$` |
| `current_secret_expires_at` | string or null | Yes | Expiry of the currently active client secret, or null for an account with no secret (an enterprise backend authenticating with private_key_jwt). The service account itself never expires on a timer, and JWT access-token TTL is separate. |
| `etag` | string | Yes | minLength: 1 |
| `external_id` | string or null | Yes |  |
| `id` | string | Yes | Stable service account identifier. Matches `client_id` and the trailing id segment of `principal_ref`. 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)$` |
| `managed_by` | string or null | Yes | Identity provider that manages this system account; null for tenant-created accounts. Managed accounts cannot be revoked or have their secret rotated through the service-account API. |
| `parent_ref` | string | Yes | pattern: `^(enterprises\|clients)\/([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})$` |
| `previous_secret_expires_at` | string or null | Yes | Expiry of the previous client secret during a rotation grace window, or null when no previous secret remains valid. |
| `principal_ref` | string | Yes | principal_ref ≡ service-accounts/{client_id} ≡ service-accounts/{id} pattern: `^(service-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})$` |
| `resource` | "service_account" | Yes |  |
| `status` | "active" / "revoked" | Yes | Service accounts do not expire on a timer. Lifecycle is status-only: `active` or `revoked`. |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.description

At least one alternative must match.

###### application/json body.description: alternative 1

Type: `string`. 

###### application/json body.description: alternative 2

Type: `null`. 

##### application/json body.current_secret_expires_at

Expiry of the currently active client secret, or null for an account with no secret (an enterprise backend authenticating with private_key_jwt). The service account itself never expires on a timer, and JWT access-token TTL is separate.

At least one alternative must match.

###### application/json body.current_secret_expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.current_secret_expires_at: alternative 2

Type: `null`. 

##### application/json body.external_id

At least one alternative must match.

###### application/json body.external_id: alternative 1

Type: `string`. 

###### application/json body.external_id: alternative 2

Type: `null`. 

##### application/json body.managed_by

Identity provider that manages this system account; null for tenant-created accounts. Managed accounts cannot be revoked or have their secret rotated through the service-account API.

At least one alternative must match.

###### application/json body.managed_by: alternative 1

Type: `string`. 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)$`

###### application/json body.managed_by: alternative 2

Type: `null`. 

##### application/json body.previous_secret_expires_at

Expiry of the previous client secret during a rotation grace window, or null when no previous secret remains valid.

At least one alternative must match.

###### application/json body.previous_secret_expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.previous_secret_expires_at: alternative 2

Type: `null`.


### service-accounts-update 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.


### service-accounts-update Response 401 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.


### service-accounts-update Response 403 schema

Content type: `application/json`.

See [response 401 schema](#service-accounts-update-response-401-schema).


### service-accounts-update Response 404 schema

Content type: `application/json`.

See [response 401 schema](#service-accounts-update-response-401-schema).


### service-accounts-update Response 409 schema

Content type: `application/json`.

See [response 401 schema](#service-accounts-update-response-401-schema).


### service-accounts-update Response 412 schema

Content type: `application/json`.

See [response 401 schema](#service-accounts-update-response-401-schema).


### service-accounts-update Response 500 schema

Content type: `application/json`.

See [response 401 schema](#service-accounts-update-response-401-schema).


### service-accounts-update Response 502 schema

Content type: `application/json`.

See [response 400 schema](#service-accounts-update-response-400-schema).


### service-accounts-update Response 503 schema

Content type: `application/json`.

See [response 400 schema](#service-accounts-update-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "description": "Withdrawal automation account",
    "created_at": "2026-05-01T10:00:00Z",
    "current_secret_expires_at": "2026-05-02T10:00:00Z",
    "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
    "external_id": "sa-ext-001",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "managed_by": null,
    "parent_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "previous_secret_expires_at": null,
    "principal_ref": "service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "resource": "service_account",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `412` — If-Match check failed; the resource has changed since the cached etag.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /service-accounts/{service_account_id}/revoke

**Revoke service account**

**Required capability:** `service_accounts.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `service_account_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `reason` | string or null | No |  |

Additional fields are not accepted.

#### Request body schema.reason

At least one alternative must match.

##### Request body schema.reason: alternative 1

Type: `string`. 

##### Request body schema.reason: alternative 2

Type: `null`.

### service-accounts-revoke Response 200 schema

Content type: `application/json`.

#### application/json body

Public service account resource. The account itself has no expiry; only client secrets and access tokens have independent TTLs.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `description` | string or null | Yes |  |
| `created_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))$` |
| `current_secret_expires_at` | string or null | Yes | Expiry of the currently active client secret, or null for an account with no secret (an enterprise backend authenticating with private_key_jwt). The service account itself never expires on a timer, and JWT access-token TTL is separate. |
| `etag` | string | Yes | minLength: 1 |
| `external_id` | string or null | Yes |  |
| `id` | string | Yes | Stable service account identifier. Matches `client_id` and the trailing id segment of `principal_ref`. 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)$` |
| `managed_by` | string or null | Yes | Identity provider that manages this system account; null for tenant-created accounts. Managed accounts cannot be revoked or have their secret rotated through the service-account API. |
| `parent_ref` | string | Yes | pattern: `^(enterprises\|clients)\/([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})$` |
| `previous_secret_expires_at` | string or null | Yes | Expiry of the previous client secret during a rotation grace window, or null when no previous secret remains valid. |
| `principal_ref` | string | Yes | principal_ref ≡ service-accounts/{client_id} ≡ service-accounts/{id} pattern: `^(service-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})$` |
| `resource` | "service_account" | Yes |  |
| `status` | "active" / "revoked" | Yes | Service accounts do not expire on a timer. Lifecycle is status-only: `active` or `revoked`. |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.description

At least one alternative must match.

###### application/json body.description: alternative 1

Type: `string`. 

###### application/json body.description: alternative 2

Type: `null`. 

##### application/json body.current_secret_expires_at

Expiry of the currently active client secret, or null for an account with no secret (an enterprise backend authenticating with private_key_jwt). The service account itself never expires on a timer, and JWT access-token TTL is separate.

At least one alternative must match.

###### application/json body.current_secret_expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.current_secret_expires_at: alternative 2

Type: `null`. 

##### application/json body.external_id

At least one alternative must match.

###### application/json body.external_id: alternative 1

Type: `string`. 

###### application/json body.external_id: alternative 2

Type: `null`. 

##### application/json body.managed_by

Identity provider that manages this system account; null for tenant-created accounts. Managed accounts cannot be revoked or have their secret rotated through the service-account API.

At least one alternative must match.

###### application/json body.managed_by: alternative 1

Type: `string`. 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)$`

###### application/json body.managed_by: alternative 2

Type: `null`. 

##### application/json body.previous_secret_expires_at

Expiry of the previous client secret during a rotation grace window, or null when no previous secret remains valid.

At least one alternative must match.

###### application/json body.previous_secret_expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.previous_secret_expires_at: alternative 2

Type: `null`.


### service-accounts-revoke 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.


### service-accounts-revoke Response 401 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.


### service-accounts-revoke Response 403 schema

Content type: `application/json`.

See [response 401 schema](#service-accounts-revoke-response-401-schema).


### service-accounts-revoke Response 404 schema

Content type: `application/json`.

See [response 401 schema](#service-accounts-revoke-response-401-schema).


### service-accounts-revoke Response 409 schema

Content type: `application/json`.

See [response 401 schema](#service-accounts-revoke-response-401-schema).


### service-accounts-revoke Response 500 schema

Content type: `application/json`.

See [response 401 schema](#service-accounts-revoke-response-401-schema).


### service-accounts-revoke Response 502 schema

Content type: `application/json`.

See [response 400 schema](#service-accounts-revoke-response-400-schema).


### service-accounts-revoke Response 503 schema

Content type: `application/json`.

See [response 400 schema](#service-accounts-revoke-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "description": "Withdrawal automation account",
    "created_at": "2026-05-01T10:00:00Z",
    "current_secret_expires_at": "2026-05-02T10:00:00Z",
    "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
    "external_id": "sa-ext-001",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "managed_by": null,
    "parent_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "previous_secret_expires_at": null,
    "principal_ref": "service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "resource": "service_account",
    "status": "revoked",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /service-accounts/{service_account_id}/rotate-secret

**Rotate service account secret**

Issues a new `client_secret` with HTTP 201. The plaintext is returned only in this issuance response; ordinary reads do not return it. Rotation is not replayed: repeating the request issues a new secret, even with the same Idempotency-Key. By default the previous secret is invalidated immediately; pass `invalidate_previous_secret: false` to keep the immediately previous secret valid until its original expiry; rotation does not extend that expiry. Only one previous secret is retained. The service account itself never expires on a timer; lifecycle is status-only (`active` or `revoked`). `client_secret_expires_at` is the new client-secret TTL, while JWT access-token TTL is separate. The body may be omitted; omitted or null invalidate_previous_secret means true. `client_secret_ttl_seconds` is optional, at least 60 seconds, and has no upper bound; omission uses the deployment default. Revoked and managed accounts cannot be rotated.

**Required capability:** `service_accounts.rotate_secret`

**Authentication:** Bearer token required.

**Parameters:**

- `service_account_id` `string` (path) *(required)*

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `client_secret_ttl_seconds` | integer | No | minimum: 60; maximum: 9007199254740991 |
| `invalidate_previous_secret` | boolean or null | No |  |
| `reason` | string or null | No |  |

Additional fields are not accepted.

#### Request body schema.invalidate_previous_secret

At least one alternative must match.

##### Request body schema.invalidate_previous_secret: alternative 1

Type: `boolean`. 

##### Request body schema.invalidate_previous_secret: alternative 2

Type: `null`. 

#### Request body schema.reason

At least one alternative must match.

##### Request body schema.reason: alternative 1

Type: `string`. 

##### Request body schema.reason: alternative 2

Type: `null`.

**Request example:**

```json
{
  "invalidate_previous_secret": true,
  "reason": "Routine rotation"
}
```

### service-accounts-rotate-secret Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `client_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)$` |
| `client_secret` | string | Yes | minLength: 1 |
| `client_secret_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))$` |
| `principal_ref` | string | Yes | pattern: `^(service-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})$` |
| `service_account` | object | Yes | Public service account resource. The account itself has no expiry; only client secrets and access tokens have independent TTLs. No additional fields |

Additional fields are not accepted.

##### application/json body.service_account

Public service account resource. The account itself has no expiry; only client secrets and access tokens have independent TTLs.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `description` | string or null | Yes |  |
| `created_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))$` |
| `current_secret_expires_at` | string or null | Yes | Expiry of the currently active client secret, or null for an account with no secret (an enterprise backend authenticating with private_key_jwt). The service account itself never expires on a timer, and JWT access-token TTL is separate. |
| `etag` | string | Yes | minLength: 1 |
| `external_id` | string or null | Yes |  |
| `id` | string | Yes | Stable service account identifier. Matches `client_id` and the trailing id segment of `principal_ref`. 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)$` |
| `managed_by` | string or null | Yes | Identity provider that manages this system account; null for tenant-created accounts. Managed accounts cannot be revoked or have their secret rotated through the service-account API. |
| `parent_ref` | string | Yes | pattern: `^(enterprises\|clients)\/([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})$` |
| `previous_secret_expires_at` | string or null | Yes | Expiry of the previous client secret during a rotation grace window, or null when no previous secret remains valid. |
| `principal_ref` | string | Yes | principal_ref ≡ service-accounts/{client_id} ≡ service-accounts/{id} pattern: `^(service-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})$` |
| `resource` | "service_account" | Yes |  |
| `status` | "active" / "revoked" | Yes | Service accounts do not expire on a timer. Lifecycle is status-only: `active` or `revoked`. |
| `updated_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))$` |

Additional fields are not accepted.

###### application/json body.service_account.description

At least one alternative must match.

###### application/json body.service_account.description: alternative 1

Type: `string`. 

###### application/json body.service_account.description: alternative 2

Type: `null`. 

###### application/json body.service_account.current_secret_expires_at

Expiry of the currently active client secret, or null for an account with no secret (an enterprise backend authenticating with private_key_jwt). The service account itself never expires on a timer, and JWT access-token TTL is separate.

At least one alternative must match.

###### application/json body.service_account.current_secret_expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.service_account.current_secret_expires_at: alternative 2

Type: `null`. 

###### application/json body.service_account.external_id

At least one alternative must match.

###### application/json body.service_account.external_id: alternative 1

Type: `string`. 

###### application/json body.service_account.external_id: alternative 2

Type: `null`. 

###### application/json body.service_account.managed_by

Identity provider that manages this system account; null for tenant-created accounts. Managed accounts cannot be revoked or have their secret rotated through the service-account API.

At least one alternative must match.

###### application/json body.service_account.managed_by: alternative 1

Type: `string`. 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)$`

###### application/json body.service_account.managed_by: alternative 2

Type: `null`. 

###### application/json body.service_account.previous_secret_expires_at

Expiry of the previous client secret during a rotation grace window, or null when no previous secret remains valid.

At least one alternative must match.

###### application/json body.service_account.previous_secret_expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.service_account.previous_secret_expires_at: alternative 2

Type: `null`.


| Response header | Type | Description |
| --- | --- | --- |
| `Cache-Control` | "no-store" |  |

### service-accounts-rotate-secret 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.


### service-accounts-rotate-secret Response 401 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.


### service-accounts-rotate-secret Response 403 schema

Content type: `application/json`.

See [response 401 schema](#service-accounts-rotate-secret-response-401-schema).


### service-accounts-rotate-secret Response 404 schema

Content type: `application/json`.

See [response 401 schema](#service-accounts-rotate-secret-response-401-schema).


### service-accounts-rotate-secret Response 409 schema

Content type: `application/json`.

See [response 401 schema](#service-accounts-rotate-secret-response-401-schema).


### service-accounts-rotate-secret Response 500 schema

Content type: `application/json`.

See [response 401 schema](#service-accounts-rotate-secret-response-401-schema).


### service-accounts-rotate-secret Response 502 schema

Content type: `application/json`.

See [response 400 schema](#service-accounts-rotate-secret-response-400-schema).


### service-accounts-rotate-secret Response 503 schema

Content type: `application/json`.

See [response 400 schema](#service-accounts-rotate-secret-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "client_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "client_secret": "cs_live_abc123placeholder",
    "client_secret_expires_at": "2026-05-02T10:00:00Z",
    "principal_ref": "service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "service_account": {
      "description": "Withdrawal automation account",
      "created_at": "2026-05-01T10:00:00Z",
      "current_secret_expires_at": "2026-05-02T10:00:00Z",
      "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
      "external_id": "sa-ext-001",
      "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "managed_by": null,
      "parent_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "previous_secret_expires_at": null,
      "principal_ref": "service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "resource": "service_account",
      "status": "active",
      "updated_at": "2026-05-01T10:00:00Z"
    }
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /service-accounts/provision

**Provision service account with roles**

Creates a service account and grants it the supplied roles in a single call. Equivalent to `POST /service-accounts` followed by N × `POST /role-assignments`, but saves the client the round-trips. Best-effort grant phase: the service account is always created if `identity-service` accepts it; per-role grant failures are reported in `role_assignment_errors` (preserving the input order) and the response is still `201`. The plaintext secret is included only in the issuance response; ordinary reads do not return it. Store it before retrying failed grants. A retry with the same Idempotency-Key returns the first response without its `client_secret` and creates or grants nothing again; use `service_accounts.rotate_secret` if the original response was lost. `client_secret_ttl_seconds` has a minimum of 60 seconds, no upper bound, and uses the deployment default when omitted.

**Required capability:** `service_accounts.create`, `role_assignments.create`

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `description` | string or null | No |  |
| `client_secret_ttl_seconds` | integer | No | minimum: 60; maximum: 9007199254740991 |
| `external_id` | string or null | No |  |
| `parent_ref` | string | Yes | pattern: `^(enterprises\|clients)\/([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})$` |
| `roles` | object[] | Yes | minItems: 1 |

Additional fields are not accepted.

#### Request body schema.description

At least one alternative must match.

##### Request body schema.description: alternative 1

Type: `string`. 

##### Request body schema.description: alternative 2

Type: `null`. 

#### Request body schema.external_id

At least one alternative must match.

##### Request body schema.external_id: alternative 1

Type: `string`. 

##### Request body schema.external_id: alternative 2

Type: `null`. 

#### Request body schema.roles

Type: `object[]`. minItems: 1

##### Request body schema.roles item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `role_ref` | string | Yes | pattern: `^(roles)\/([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})$` |
| `scope_anchor_kind` | "explicit" / "enterprise_wildcard" | No |  |
| `scope_propagation` | "self" / "subtree" | No |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|platform-operators\|clients)\/([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})$` |

Additional fields are not accepted.

**Request example:**

```json
{
  "description": "Withdrawal automation account",
  "parent_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "roles": [
    {
      "role_ref": "roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
    }
  ]
}
```

### service-accounts-provision Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `client_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)$` |
| `client_secret` | string | No | Present only in the first response. A retry with the same Idempotency-Key replays the response without it. minLength: 1 |
| `client_secret_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))$` |
| `principal_ref` | string | Yes | pattern: `^(service-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})$` |
| `role_assignment_errors` | object[] | Yes |  |
| `role_assignments` | object[] | Yes |  |
| `service_account` | object | Yes | Public service account resource. The account itself has no expiry; only client secrets and access tokens have independent TTLs. No additional fields |

Additional fields are not accepted.

##### application/json body.role_assignment_errors

Type: `object[]`. 

###### application/json body.role_assignment_errors item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `code` | string | Yes |  |
| `message` | string | Yes |  |
| `role_ref` | string | Yes |  |
| `scope_ref` | string | Yes |  |

Additional fields are not accepted.

##### application/json body.role_assignments

Type: `object[]`. 

###### application/json body.role_assignments item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `created_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))$` |
| `etag` | string | Yes | minLength: 1 |
| `granted_by` | string or null | No |  |
| `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)$` |
| `principal_ref` | string | Yes | pattern: `^(users\|service-accounts\|system-principals)\/([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})$` |
| `resource` | "role_assignment" | Yes |  |
| `role_ref` | string | Yes | pattern: `^(roles)\/([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})$` |
| `scope_anchor_kind` | "explicit" / "enterprise_wildcard" | Yes |  |
| `scope_propagation` | "self" / "subtree" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|platform-operators\|clients)\/([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})$` |
| `status` | "active" / "revoked" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

###### application/json body.role_assignments item.granted_by

At least one alternative must match.

###### application/json body.role_assignments item.granted_by: alternative 1

Type: `string`. pattern: `^(users|service-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})$`

###### application/json body.role_assignments item.granted_by: alternative 2

Type: `null`. 

##### application/json body.service_account

Public service account resource. The account itself has no expiry; only client secrets and access tokens have independent TTLs.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `description` | string or null | Yes |  |
| `created_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))$` |
| `current_secret_expires_at` | string or null | Yes | Expiry of the currently active client secret, or null for an account with no secret (an enterprise backend authenticating with private_key_jwt). The service account itself never expires on a timer, and JWT access-token TTL is separate. |
| `etag` | string | Yes | minLength: 1 |
| `external_id` | string or null | Yes |  |
| `id` | string | Yes | Stable service account identifier. Matches `client_id` and the trailing id segment of `principal_ref`. 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)$` |
| `managed_by` | string or null | Yes | Identity provider that manages this system account; null for tenant-created accounts. Managed accounts cannot be revoked or have their secret rotated through the service-account API. |
| `parent_ref` | string | Yes | pattern: `^(enterprises\|clients)\/([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})$` |
| `previous_secret_expires_at` | string or null | Yes | Expiry of the previous client secret during a rotation grace window, or null when no previous secret remains valid. |
| `principal_ref` | string | Yes | principal_ref ≡ service-accounts/{client_id} ≡ service-accounts/{id} pattern: `^(service-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})$` |
| `resource` | "service_account" | Yes |  |
| `status` | "active" / "revoked" | Yes | Service accounts do not expire on a timer. Lifecycle is status-only: `active` or `revoked`. |
| `updated_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))$` |

Additional fields are not accepted.

###### application/json body.service_account.description

At least one alternative must match.

###### application/json body.service_account.description: alternative 1

Type: `string`. 

###### application/json body.service_account.description: alternative 2

Type: `null`. 

###### application/json body.service_account.current_secret_expires_at

Expiry of the currently active client secret, or null for an account with no secret (an enterprise backend authenticating with private_key_jwt). The service account itself never expires on a timer, and JWT access-token TTL is separate.

At least one alternative must match.

###### application/json body.service_account.current_secret_expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.service_account.current_secret_expires_at: alternative 2

Type: `null`. 

###### application/json body.service_account.external_id

At least one alternative must match.

###### application/json body.service_account.external_id: alternative 1

Type: `string`. 

###### application/json body.service_account.external_id: alternative 2

Type: `null`. 

###### application/json body.service_account.managed_by

Identity provider that manages this system account; null for tenant-created accounts. Managed accounts cannot be revoked or have their secret rotated through the service-account API.

At least one alternative must match.

###### application/json body.service_account.managed_by: alternative 1

Type: `string`. 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)$`

###### application/json body.service_account.managed_by: alternative 2

Type: `null`. 

###### application/json body.service_account.previous_secret_expires_at

Expiry of the previous client secret during a rotation grace window, or null when no previous secret remains valid.

At least one alternative must match.

###### application/json body.service_account.previous_secret_expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.service_account.previous_secret_expires_at: alternative 2

Type: `null`.


| Response header | Type | Description |
| --- | --- | --- |
| `Cache-Control` | "no-store" |  |

### service-accounts-provision 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.


### service-accounts-provision Response 401 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.


### service-accounts-provision Response 403 schema

Content type: `application/json`.

See [response 401 schema](#service-accounts-provision-response-401-schema).


### service-accounts-provision Response 409 schema

Content type: `application/json`.

See [response 401 schema](#service-accounts-provision-response-401-schema).


### service-accounts-provision Response 500 schema

Content type: `application/json`.

See [response 401 schema](#service-accounts-provision-response-401-schema).


### service-accounts-provision Response 502 schema

Content type: `application/json`.

See [response 400 schema](#service-accounts-provision-response-400-schema).


### service-accounts-provision Response 503 schema

Content type: `application/json`.

See [response 400 schema](#service-accounts-provision-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "client_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "client_secret": "cs_live_abc123placeholder",
    "client_secret_expires_at": "2026-05-02T10:00:00Z",
    "principal_ref": "service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "role_assignment_errors": [],
    "role_assignments": [
      {
        "created_at": "2026-05-01T10:00:00Z",
        "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "principal_ref": "service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "resource": "role_assignment",
        "role_ref": "roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "scope_anchor_kind": "explicit",
        "scope_propagation": "subtree",
        "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "status": "active",
        "updated_at": "2026-05-01T10:00:00Z"
      }
    ],
    "service_account": {
      "description": "Withdrawal automation account",
      "created_at": "2026-05-01T10:00:00Z",
      "current_secret_expires_at": "2026-05-02T10:00:00Z",
      "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
      "external_id": "sa-ext-001",
      "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "managed_by": null,
      "parent_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "previous_secret_expires_at": null,
      "principal_ref": "service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "resource": "service_account",
      "status": "active",
      "updated_at": "2026-05-01T10:00:00Z"
    }
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Roles

### GET /roles

**List roles**

**Required capability:** `roles.read`

**Authentication:** Bearer token required.

**Parameters:**

- `scope_ref` `string` (query) *(required)*
- `status` `string` (query)
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### roles-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1 |
| `description` | string or null | Yes |  |
| `created_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))$` |
| `etag` | string | Yes | minLength: 1 |
| `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)$` |
| `permissions` | string[] | Yes |  |
| `platform_managed` | boolean | Yes |  |
| `resource` | "role" | Yes |  |
| `scope_ref` | string or null | Yes |  |
| `status` | "active" / "retired" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

###### application/json body.items item.description

At least one alternative must match.

###### application/json body.items item.description: alternative 1

Type: `string`. 

###### application/json body.items item.description: alternative 2

Type: `null`. 

###### application/json body.items item.permissions

Type: `string[]`. 

###### application/json body.items item.permissions item

Type: `string`. pattern: `^[a-z0-9]+(?:[._][a-z0-9]+)*$`; minLength: 1

###### application/json body.items item.scope_ref

At least one alternative must match.

###### application/json body.items item.scope_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.scope_ref: alternative 2

Type: `null`. 

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. 

###### application/json body.next_page_token: alternative 2

Type: `null`.


### roles-list 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.


### roles-list Response 401 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.


### roles-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#roles-list-response-401-schema).


### roles-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#roles-list-response-401-schema).


### roles-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#roles-list-response-400-schema).


### roles-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#roles-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "name": "Enterprise Admin",
        "description": "Full administrative access within an enterprise",
        "created_at": "2026-05-01T10:00:00Z",
        "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "permissions": [
          "withdrawals.create",
          "deposits.read",
          "clients.read"
        ],
        "platform_managed": false,
        "resource": "role",
        "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "status": "active",
        "updated_at": "2026-05-01T10:00:00Z"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /roles

**Create role**

Creates a tenant-managed active role at the explicit topology scope. Requires Idempotency-Key. Permissions must use canonical capability names and suit the scope: platform-owned and platform-actor-only capabilities cannot be placed in an enterprise or client role. Seed-only capabilities cannot be granted through the API.

**Required capability:** `roles.create`

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) *(required)* — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1 |
| `description` | string or null | No |  |
| `permissions` | "users.read" / "users.invite" / "users.create" / "users.manage" / "users.activate_federated" / "users.recovery_initiate" / "service_accounts.read" / "service_accounts.create" / "service_accounts.manage" / "service_accounts.rotate_secret" / "clients.read" / "clients.create" / "clients.manage" / "accounts.read" / "accounts.create" / "accounts.manage" / "roles.read" / "roles.create" / "roles.manage" / "role_assignments.read" / "role_assignments.create" / "role_assignments.manage" / "withdrawals.read" / "withdrawals.create" / "withdrawals.manage" / "conversions.read" / "conversions.create" / "conversions.manage" / "external_settlement_conversions.read" / "external_settlement_conversions.create" / "external_settlement_conversions.manage" / "internal_transfers.read" / "internal_transfers.create" / "internal_transfers.manage" / "ramps.read" / "ramps.create" / "ramps.manage" / "policies.read" / "policies.create" / "policies.manage" / "commercial_agreements.read" / "commercial_agreements.create" / "commercial_agreements.manage" / "loans.read" / "loans.create" / "loans.manage" / "loan_products.read" / "loan_products.manage" / "loan_shortfalls.read" / "sandbox_simulator.run" / "sandbox_reset.run" / "webhooks.read" / "webhooks.create" / "webhooks.manage" / "funding_endpoints.read" / "funding_endpoints.provision" / "deposit_instructions.read" / "deposit_instructions.create" / "withdrawal_destinations.read" / "withdrawal_destinations.create" / "withdrawal_destinations.manage" / "deposits.read" / "deposits.credit" / "approvals.read" / "approvals.decide" / "compliance_assessments.read" / "compliance_assessments.decide" / "compliance_assessments.read_decision_volume" / "compliance_assessments.reveal_subject_identity" / "compliance_alerts.read" / "compliance_alerts.acknowledge" / "compliance_rules.read" / "compliance_rules.manage" / "events.read" / "feature_flags.read" / "feature_flags.manage" / "feature_flags.manage_platform" / "identity_providers.manage" / "enterprises.read" / "enterprises.list" / "enterprises.create" / "enterprises.provision" / "enterprises.manage" / "enterprises.restrict" / "enterprises.reactivate" / "enterprises.terminate" / "kyc.verify" / "payment_methods.manage" / "payout_methods.manage" / "crypto_networks.manage" / "platform_operators.read" / "platform_operators.manage" / "platform_principals.manage" / "platform_principals.rotate_secret" / "ledger.compensate" / "ledger.fee_post" / "ledger.reconciliation_post" / "overdraft_limits.manage" / "operations_reports.read" / "operations_reports.create_export" / "operations_reports.view_fee_breakdown" / "operations_reports.view_actor_attribution" / "audit.read" / "audit.create_export" / "audit.view_technical_traces" / "audit.view_actor_pii" / "audit.view_free_text" / "catalog.manage" / "custody_mappings.manage" / "onchain_analytics_mappings.manage" / "fiat_routes.manage" / "conversion_routes.manage" / "settlement_bindings.manage" / "legal.publish" / "operations.review" / "operations.recovery" / "admissibility.read" / "custody.read"[] | Yes | minItems: 1 |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|platform-operators\|clients)\/([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})$` |

Additional fields are not accepted.

#### Request body schema.description

At least one alternative must match.

##### Request body schema.description: alternative 1

Type: `string`. 

##### Request body schema.description: alternative 2

Type: `null`. 

#### Request body schema.permissions

Type: `"users.read" / "users.invite" / "users.create" / "users.manage" / "users.activate_federated" / "users.recovery_initiate" / "service_accounts.read" / "service_accounts.create" / "service_accounts.manage" / "service_accounts.rotate_secret" / "clients.read" / "clients.create" / "clients.manage" / "accounts.read" / "accounts.create" / "accounts.manage" / "roles.read" / "roles.create" / "roles.manage" / "role_assignments.read" / "role_assignments.create" / "role_assignments.manage" / "withdrawals.read" / "withdrawals.create" / "withdrawals.manage" / "conversions.read" / "conversions.create" / "conversions.manage" / "external_settlement_conversions.read" / "external_settlement_conversions.create" / "external_settlement_conversions.manage" / "internal_transfers.read" / "internal_transfers.create" / "internal_transfers.manage" / "ramps.read" / "ramps.create" / "ramps.manage" / "policies.read" / "policies.create" / "policies.manage" / "commercial_agreements.read" / "commercial_agreements.create" / "commercial_agreements.manage" / "loans.read" / "loans.create" / "loans.manage" / "loan_products.read" / "loan_products.manage" / "loan_shortfalls.read" / "sandbox_simulator.run" / "sandbox_reset.run" / "webhooks.read" / "webhooks.create" / "webhooks.manage" / "funding_endpoints.read" / "funding_endpoints.provision" / "deposit_instructions.read" / "deposit_instructions.create" / "withdrawal_destinations.read" / "withdrawal_destinations.create" / "withdrawal_destinations.manage" / "deposits.read" / "deposits.credit" / "approvals.read" / "approvals.decide" / "compliance_assessments.read" / "compliance_assessments.decide" / "compliance_assessments.read_decision_volume" / "compliance_assessments.reveal_subject_identity" / "compliance_alerts.read" / "compliance_alerts.acknowledge" / "compliance_rules.read" / "compliance_rules.manage" / "events.read" / "feature_flags.read" / "feature_flags.manage" / "feature_flags.manage_platform" / "identity_providers.manage" / "enterprises.read" / "enterprises.list" / "enterprises.create" / "enterprises.provision" / "enterprises.manage" / "enterprises.restrict" / "enterprises.reactivate" / "enterprises.terminate" / "kyc.verify" / "payment_methods.manage" / "payout_methods.manage" / "crypto_networks.manage" / "platform_operators.read" / "platform_operators.manage" / "platform_principals.manage" / "platform_principals.rotate_secret" / "ledger.compensate" / "ledger.fee_post" / "ledger.reconciliation_post" / "overdraft_limits.manage" / "operations_reports.read" / "operations_reports.create_export" / "operations_reports.view_fee_breakdown" / "operations_reports.view_actor_attribution" / "audit.read" / "audit.create_export" / "audit.view_technical_traces" / "audit.view_actor_pii" / "audit.view_free_text" / "catalog.manage" / "custody_mappings.manage" / "onchain_analytics_mappings.manage" / "fiat_routes.manage" / "conversion_routes.manage" / "settlement_bindings.manage" / "legal.publish" / "operations.review" / "operations.recovery" / "admissibility.read" / "custody.read"[]`. minItems: 1

##### Request body schema.permissions item

Type: `"users.read" / "users.invite" / "users.create" / "users.manage" / "users.activate_federated" / "users.recovery_initiate" / "service_accounts.read" / "service_accounts.create" / "service_accounts.manage" / "service_accounts.rotate_secret" / "clients.read" / "clients.create" / "clients.manage" / "accounts.read" / "accounts.create" / "accounts.manage" / "roles.read" / "roles.create" / "roles.manage" / "role_assignments.read" / "role_assignments.create" / "role_assignments.manage" / "withdrawals.read" / "withdrawals.create" / "withdrawals.manage" / "conversions.read" / "conversions.create" / "conversions.manage" / "external_settlement_conversions.read" / "external_settlement_conversions.create" / "external_settlement_conversions.manage" / "internal_transfers.read" / "internal_transfers.create" / "internal_transfers.manage" / "ramps.read" / "ramps.create" / "ramps.manage" / "policies.read" / "policies.create" / "policies.manage" / "commercial_agreements.read" / "commercial_agreements.create" / "commercial_agreements.manage" / "loans.read" / "loans.create" / "loans.manage" / "loan_products.read" / "loan_products.manage" / "loan_shortfalls.read" / "sandbox_simulator.run" / "sandbox_reset.run" / "webhooks.read" / "webhooks.create" / "webhooks.manage" / "funding_endpoints.read" / "funding_endpoints.provision" / "deposit_instructions.read" / "deposit_instructions.create" / "withdrawal_destinations.read" / "withdrawal_destinations.create" / "withdrawal_destinations.manage" / "deposits.read" / "deposits.credit" / "approvals.read" / "approvals.decide" / "compliance_assessments.read" / "compliance_assessments.decide" / "compliance_assessments.read_decision_volume" / "compliance_assessments.reveal_subject_identity" / "compliance_alerts.read" / "compliance_alerts.acknowledge" / "compliance_rules.read" / "compliance_rules.manage" / "events.read" / "feature_flags.read" / "feature_flags.manage" / "feature_flags.manage_platform" / "identity_providers.manage" / "enterprises.read" / "enterprises.list" / "enterprises.create" / "enterprises.provision" / "enterprises.manage" / "enterprises.restrict" / "enterprises.reactivate" / "enterprises.terminate" / "kyc.verify" / "payment_methods.manage" / "payout_methods.manage" / "crypto_networks.manage" / "platform_operators.read" / "platform_operators.manage" / "platform_principals.manage" / "platform_principals.rotate_secret" / "ledger.compensate" / "ledger.fee_post" / "ledger.reconciliation_post" / "overdraft_limits.manage" / "operations_reports.read" / "operations_reports.create_export" / "operations_reports.view_fee_breakdown" / "operations_reports.view_actor_attribution" / "audit.read" / "audit.create_export" / "audit.view_technical_traces" / "audit.view_actor_pii" / "audit.view_free_text" / "catalog.manage" / "custody_mappings.manage" / "onchain_analytics_mappings.manage" / "fiat_routes.manage" / "conversion_routes.manage" / "settlement_bindings.manage" / "legal.publish" / "operations.review" / "operations.recovery" / "admissibility.read" / "custody.read"`.

**Request example:**

```json
{
  "name": "Enterprise Admin",
  "description": "Full administrative access within an enterprise",
  "permissions": [
    "withdrawals.create",
    "deposits.read",
    "clients.read"
  ],
  "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}
```

### roles-create Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1 |
| `description` | string or null | Yes |  |
| `created_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))$` |
| `etag` | string | Yes | minLength: 1 |
| `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)$` |
| `permissions` | string[] | Yes |  |
| `platform_managed` | boolean | Yes |  |
| `resource` | "role" | Yes |  |
| `scope_ref` | string or null | Yes |  |
| `status` | "active" / "retired" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.description

At least one alternative must match.

###### application/json body.description: alternative 1

Type: `string`. 

###### application/json body.description: alternative 2

Type: `null`. 

##### application/json body.permissions

Type: `string[]`. 

###### application/json body.permissions item

Type: `string`. pattern: `^[a-z0-9]+(?:[._][a-z0-9]+)*$`; minLength: 1

##### application/json body.scope_ref

At least one alternative must match.

###### application/json body.scope_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.scope_ref: alternative 2

Type: `null`.


### roles-create 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.


### roles-create Response 401 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.


### roles-create Response 403 schema

Content type: `application/json`.

See [response 401 schema](#roles-create-response-401-schema).


### roles-create Response 409 schema

Content type: `application/json`.

See [response 401 schema](#roles-create-response-401-schema).


### roles-create Response 500 schema

Content type: `application/json`.

See [response 401 schema](#roles-create-response-401-schema).


### roles-create Response 502 schema

Content type: `application/json`.

See [response 400 schema](#roles-create-response-400-schema).


### roles-create Response 503 schema

Content type: `application/json`.

See [response 400 schema](#roles-create-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "name": "Enterprise Admin",
    "description": "Full administrative access within an enterprise",
    "created_at": "2026-05-01T10:00:00Z",
    "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "permissions": [
      "withdrawals.create",
      "deposits.read",
      "clients.read"
    ],
    "platform_managed": false,
    "resource": "role",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /roles/{role_id}

**Get role**

**Required capability:** `roles.read`

**Authentication:** Bearer token required.

**Parameters:**

- `role_id` `string` (path) *(required)*

### roles-get Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1 |
| `description` | string or null | Yes |  |
| `created_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))$` |
| `etag` | string | Yes | minLength: 1 |
| `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)$` |
| `permissions` | string[] | Yes |  |
| `platform_managed` | boolean | Yes |  |
| `resource` | "role" | Yes |  |
| `scope_ref` | string or null | Yes |  |
| `status` | "active" / "retired" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.description

At least one alternative must match.

###### application/json body.description: alternative 1

Type: `string`. 

###### application/json body.description: alternative 2

Type: `null`. 

##### application/json body.permissions

Type: `string[]`. 

###### application/json body.permissions item

Type: `string`. pattern: `^[a-z0-9]+(?:[._][a-z0-9]+)*$`; minLength: 1

##### application/json body.scope_ref

At least one alternative must match.

###### application/json body.scope_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.scope_ref: alternative 2

Type: `null`.


### roles-get 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.


### roles-get Response 401 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.


### roles-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#roles-get-response-401-schema).


### roles-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#roles-get-response-401-schema).


### roles-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#roles-get-response-401-schema).


### roles-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#roles-get-response-400-schema).


### roles-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#roles-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "name": "Enterprise Admin",
    "description": "Full administrative access within an enterprise",
    "created_at": "2026-05-01T10:00:00Z",
    "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "permissions": [
      "withdrawals.create",
      "deposits.read",
      "clients.read"
    ],
    "platform_managed": false,
    "resource": "role",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### PATCH /roles/{role_id}

**Update role**

Patches an active tenant-managed role. Requires the current `If-Match` entity tag. Platform-managed roles are immutable through this API; retired roles cannot be updated. Omitting a field preserves it; `description: null` clears the description, but `name: null` is refused. Permission changes invalidate affected principals’ authority context.

**Required capability:** `roles.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `role_id` `string` (path) *(required)*
- `If-Match` `string` (header) *(required)* — Weak entity tag from a prior GET. Mismatch causes the request to fail with 412 Precondition Failed.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string or null | No |  |
| `description` | string or null | No |  |
| `permissions` | "users.read" / "users.invite" / "users.create" / "users.manage" / "users.activate_federated" / "users.recovery_initiate" / "service_accounts.read" / "service_accounts.create" / "service_accounts.manage" / "service_accounts.rotate_secret" / "clients.read" / "clients.create" / "clients.manage" / "accounts.read" / "accounts.create" / "accounts.manage" / "roles.read" / "roles.create" / "roles.manage" / "role_assignments.read" / "role_assignments.create" / "role_assignments.manage" / "withdrawals.read" / "withdrawals.create" / "withdrawals.manage" / "conversions.read" / "conversions.create" / "conversions.manage" / "external_settlement_conversions.read" / "external_settlement_conversions.create" / "external_settlement_conversions.manage" / "internal_transfers.read" / "internal_transfers.create" / "internal_transfers.manage" / "ramps.read" / "ramps.create" / "ramps.manage" / "policies.read" / "policies.create" / "policies.manage" / "commercial_agreements.read" / "commercial_agreements.create" / "commercial_agreements.manage" / "loans.read" / "loans.create" / "loans.manage" / "loan_products.read" / "loan_products.manage" / "loan_shortfalls.read" / "sandbox_simulator.run" / "sandbox_reset.run" / "webhooks.read" / "webhooks.create" / "webhooks.manage" / "funding_endpoints.read" / "funding_endpoints.provision" / "deposit_instructions.read" / "deposit_instructions.create" / "withdrawal_destinations.read" / "withdrawal_destinations.create" / "withdrawal_destinations.manage" / "deposits.read" / "deposits.credit" / "approvals.read" / "approvals.decide" / "compliance_assessments.read" / "compliance_assessments.decide" / "compliance_assessments.read_decision_volume" / "compliance_assessments.reveal_subject_identity" / "compliance_alerts.read" / "compliance_alerts.acknowledge" / "compliance_rules.read" / "compliance_rules.manage" / "events.read" / "feature_flags.read" / "feature_flags.manage" / "feature_flags.manage_platform" / "identity_providers.manage" / "enterprises.read" / "enterprises.list" / "enterprises.create" / "enterprises.provision" / "enterprises.manage" / "enterprises.restrict" / "enterprises.reactivate" / "enterprises.terminate" / "kyc.verify" / "payment_methods.manage" / "payout_methods.manage" / "crypto_networks.manage" / "platform_operators.read" / "platform_operators.manage" / "platform_principals.manage" / "platform_principals.rotate_secret" / "ledger.compensate" / "ledger.fee_post" / "ledger.reconciliation_post" / "overdraft_limits.manage" / "operations_reports.read" / "operations_reports.create_export" / "operations_reports.view_fee_breakdown" / "operations_reports.view_actor_attribution" / "audit.read" / "audit.create_export" / "audit.view_technical_traces" / "audit.view_actor_pii" / "audit.view_free_text" / "catalog.manage" / "custody_mappings.manage" / "onchain_analytics_mappings.manage" / "fiat_routes.manage" / "conversion_routes.manage" / "settlement_bindings.manage" / "legal.publish" / "operations.review" / "operations.recovery" / "admissibility.read" / "custody.read"[] | No | minItems: 1 |

Additional fields are not accepted.

#### Request body schema.name

At least one alternative must match.

##### Request body schema.name: alternative 1

Type: `string`. minLength: 1

##### Request body schema.name: alternative 2

Type: `null`. 

#### Request body schema.description

At least one alternative must match.

##### Request body schema.description: alternative 1

Type: `string`. 

##### Request body schema.description: alternative 2

Type: `null`. 

#### Request body schema.permissions

Type: `"users.read" / "users.invite" / "users.create" / "users.manage" / "users.activate_federated" / "users.recovery_initiate" / "service_accounts.read" / "service_accounts.create" / "service_accounts.manage" / "service_accounts.rotate_secret" / "clients.read" / "clients.create" / "clients.manage" / "accounts.read" / "accounts.create" / "accounts.manage" / "roles.read" / "roles.create" / "roles.manage" / "role_assignments.read" / "role_assignments.create" / "role_assignments.manage" / "withdrawals.read" / "withdrawals.create" / "withdrawals.manage" / "conversions.read" / "conversions.create" / "conversions.manage" / "external_settlement_conversions.read" / "external_settlement_conversions.create" / "external_settlement_conversions.manage" / "internal_transfers.read" / "internal_transfers.create" / "internal_transfers.manage" / "ramps.read" / "ramps.create" / "ramps.manage" / "policies.read" / "policies.create" / "policies.manage" / "commercial_agreements.read" / "commercial_agreements.create" / "commercial_agreements.manage" / "loans.read" / "loans.create" / "loans.manage" / "loan_products.read" / "loan_products.manage" / "loan_shortfalls.read" / "sandbox_simulator.run" / "sandbox_reset.run" / "webhooks.read" / "webhooks.create" / "webhooks.manage" / "funding_endpoints.read" / "funding_endpoints.provision" / "deposit_instructions.read" / "deposit_instructions.create" / "withdrawal_destinations.read" / "withdrawal_destinations.create" / "withdrawal_destinations.manage" / "deposits.read" / "deposits.credit" / "approvals.read" / "approvals.decide" / "compliance_assessments.read" / "compliance_assessments.decide" / "compliance_assessments.read_decision_volume" / "compliance_assessments.reveal_subject_identity" / "compliance_alerts.read" / "compliance_alerts.acknowledge" / "compliance_rules.read" / "compliance_rules.manage" / "events.read" / "feature_flags.read" / "feature_flags.manage" / "feature_flags.manage_platform" / "identity_providers.manage" / "enterprises.read" / "enterprises.list" / "enterprises.create" / "enterprises.provision" / "enterprises.manage" / "enterprises.restrict" / "enterprises.reactivate" / "enterprises.terminate" / "kyc.verify" / "payment_methods.manage" / "payout_methods.manage" / "crypto_networks.manage" / "platform_operators.read" / "platform_operators.manage" / "platform_principals.manage" / "platform_principals.rotate_secret" / "ledger.compensate" / "ledger.fee_post" / "ledger.reconciliation_post" / "overdraft_limits.manage" / "operations_reports.read" / "operations_reports.create_export" / "operations_reports.view_fee_breakdown" / "operations_reports.view_actor_attribution" / "audit.read" / "audit.create_export" / "audit.view_technical_traces" / "audit.view_actor_pii" / "audit.view_free_text" / "catalog.manage" / "custody_mappings.manage" / "onchain_analytics_mappings.manage" / "fiat_routes.manage" / "conversion_routes.manage" / "settlement_bindings.manage" / "legal.publish" / "operations.review" / "operations.recovery" / "admissibility.read" / "custody.read"[]`. minItems: 1

##### Request body schema.permissions item

Type: `"users.read" / "users.invite" / "users.create" / "users.manage" / "users.activate_federated" / "users.recovery_initiate" / "service_accounts.read" / "service_accounts.create" / "service_accounts.manage" / "service_accounts.rotate_secret" / "clients.read" / "clients.create" / "clients.manage" / "accounts.read" / "accounts.create" / "accounts.manage" / "roles.read" / "roles.create" / "roles.manage" / "role_assignments.read" / "role_assignments.create" / "role_assignments.manage" / "withdrawals.read" / "withdrawals.create" / "withdrawals.manage" / "conversions.read" / "conversions.create" / "conversions.manage" / "external_settlement_conversions.read" / "external_settlement_conversions.create" / "external_settlement_conversions.manage" / "internal_transfers.read" / "internal_transfers.create" / "internal_transfers.manage" / "ramps.read" / "ramps.create" / "ramps.manage" / "policies.read" / "policies.create" / "policies.manage" / "commercial_agreements.read" / "commercial_agreements.create" / "commercial_agreements.manage" / "loans.read" / "loans.create" / "loans.manage" / "loan_products.read" / "loan_products.manage" / "loan_shortfalls.read" / "sandbox_simulator.run" / "sandbox_reset.run" / "webhooks.read" / "webhooks.create" / "webhooks.manage" / "funding_endpoints.read" / "funding_endpoints.provision" / "deposit_instructions.read" / "deposit_instructions.create" / "withdrawal_destinations.read" / "withdrawal_destinations.create" / "withdrawal_destinations.manage" / "deposits.read" / "deposits.credit" / "approvals.read" / "approvals.decide" / "compliance_assessments.read" / "compliance_assessments.decide" / "compliance_assessments.read_decision_volume" / "compliance_assessments.reveal_subject_identity" / "compliance_alerts.read" / "compliance_alerts.acknowledge" / "compliance_rules.read" / "compliance_rules.manage" / "events.read" / "feature_flags.read" / "feature_flags.manage" / "feature_flags.manage_platform" / "identity_providers.manage" / "enterprises.read" / "enterprises.list" / "enterprises.create" / "enterprises.provision" / "enterprises.manage" / "enterprises.restrict" / "enterprises.reactivate" / "enterprises.terminate" / "kyc.verify" / "payment_methods.manage" / "payout_methods.manage" / "crypto_networks.manage" / "platform_operators.read" / "platform_operators.manage" / "platform_principals.manage" / "platform_principals.rotate_secret" / "ledger.compensate" / "ledger.fee_post" / "ledger.reconciliation_post" / "overdraft_limits.manage" / "operations_reports.read" / "operations_reports.create_export" / "operations_reports.view_fee_breakdown" / "operations_reports.view_actor_attribution" / "audit.read" / "audit.create_export" / "audit.view_technical_traces" / "audit.view_actor_pii" / "audit.view_free_text" / "catalog.manage" / "custody_mappings.manage" / "onchain_analytics_mappings.manage" / "fiat_routes.manage" / "conversion_routes.manage" / "settlement_bindings.manage" / "legal.publish" / "operations.review" / "operations.recovery" / "admissibility.read" / "custody.read"`.

**Request example:**

```json
{
  "name": "Updated Role Name",
  "description": "Updated description",
  "permissions": [
    "withdrawals.create"
  ]
}
```

### roles-update Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1 |
| `description` | string or null | Yes |  |
| `created_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))$` |
| `etag` | string | Yes | minLength: 1 |
| `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)$` |
| `permissions` | string[] | Yes |  |
| `platform_managed` | boolean | Yes |  |
| `resource` | "role" | Yes |  |
| `scope_ref` | string or null | Yes |  |
| `status` | "active" / "retired" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.description

At least one alternative must match.

###### application/json body.description: alternative 1

Type: `string`. 

###### application/json body.description: alternative 2

Type: `null`. 

##### application/json body.permissions

Type: `string[]`. 

###### application/json body.permissions item

Type: `string`. pattern: `^[a-z0-9]+(?:[._][a-z0-9]+)*$`; minLength: 1

##### application/json body.scope_ref

At least one alternative must match.

###### application/json body.scope_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.scope_ref: alternative 2

Type: `null`.


### roles-update 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.


### roles-update Response 401 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.


### roles-update Response 403 schema

Content type: `application/json`.

See [response 401 schema](#roles-update-response-401-schema).


### roles-update Response 404 schema

Content type: `application/json`.

See [response 401 schema](#roles-update-response-401-schema).


### roles-update Response 409 schema

Content type: `application/json`.

See [response 401 schema](#roles-update-response-401-schema).


### roles-update Response 412 schema

Content type: `application/json`.

See [response 401 schema](#roles-update-response-401-schema).


### roles-update Response 500 schema

Content type: `application/json`.

See [response 401 schema](#roles-update-response-401-schema).


### roles-update Response 502 schema

Content type: `application/json`.

See [response 400 schema](#roles-update-response-400-schema).


### roles-update Response 503 schema

Content type: `application/json`.

See [response 400 schema](#roles-update-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "name": "Updated Role Name",
    "description": "Updated description",
    "created_at": "2026-05-01T10:00:00Z",
    "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "permissions": [
      "withdrawals.create"
    ],
    "platform_managed": false,
    "resource": "role",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `412` — If-Match check failed; the resource has changed since the cached etag.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /roles/{role_id}/retire

**Retire role**

Retires a tenant-managed role and returns status `retired`. Retiring an already retired role or a platform-managed role returns 409. This action does not require If-Match.

**Required capability:** `roles.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `role_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `reason` | string or null | No |  |

Additional fields are not accepted.

#### Request body schema.reason

At least one alternative must match.

##### Request body schema.reason: alternative 1

Type: `string`. 

##### Request body schema.reason: alternative 2

Type: `null`.

### roles-retire Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1 |
| `description` | string or null | Yes |  |
| `created_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))$` |
| `etag` | string | Yes | minLength: 1 |
| `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)$` |
| `permissions` | string[] | Yes |  |
| `platform_managed` | boolean | Yes |  |
| `resource` | "role" | Yes |  |
| `scope_ref` | string or null | Yes |  |
| `status` | "active" / "retired" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.description

At least one alternative must match.

###### application/json body.description: alternative 1

Type: `string`. 

###### application/json body.description: alternative 2

Type: `null`. 

##### application/json body.permissions

Type: `string[]`. 

###### application/json body.permissions item

Type: `string`. pattern: `^[a-z0-9]+(?:[._][a-z0-9]+)*$`; minLength: 1

##### application/json body.scope_ref

At least one alternative must match.

###### application/json body.scope_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.scope_ref: alternative 2

Type: `null`.


### roles-retire 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.


### roles-retire Response 401 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.


### roles-retire Response 403 schema

Content type: `application/json`.

See [response 401 schema](#roles-retire-response-401-schema).


### roles-retire Response 404 schema

Content type: `application/json`.

See [response 401 schema](#roles-retire-response-401-schema).


### roles-retire Response 409 schema

Content type: `application/json`.

See [response 401 schema](#roles-retire-response-401-schema).


### roles-retire Response 500 schema

Content type: `application/json`.

See [response 401 schema](#roles-retire-response-401-schema).


### roles-retire Response 502 schema

Content type: `application/json`.

See [response 400 schema](#roles-retire-response-400-schema).


### roles-retire Response 503 schema

Content type: `application/json`.

See [response 400 schema](#roles-retire-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "name": "Enterprise Admin",
    "description": "Full administrative access within an enterprise",
    "created_at": "2026-05-01T10:00:00Z",
    "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "permissions": [
      "withdrawals.create",
      "deposits.read",
      "clients.read"
    ],
    "platform_managed": false,
    "resource": "role",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "retired",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Role Assignments

### GET /role-assignments

**List role assignments**

**Required capability:** `role_assignments.read`

**Authentication:** Bearer token required.

**Parameters:**

- `principal_ref` `string` (query)
- `scope_ref` `string` (query) *(required)*
- `role_ref` `string` (query)
- `status` `string` (query)
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### role-assignments-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `created_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))$` |
| `etag` | string | Yes | minLength: 1 |
| `granted_by` | string or null | No |  |
| `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)$` |
| `principal_ref` | string | Yes | pattern: `^(users\|service-accounts\|system-principals)\/([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})$` |
| `resource` | "role_assignment" | Yes |  |
| `role_ref` | string | Yes | pattern: `^(roles)\/([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})$` |
| `scope_anchor_kind` | "explicit" / "enterprise_wildcard" | Yes |  |
| `scope_propagation` | "self" / "subtree" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|platform-operators\|clients)\/([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})$` |
| `status` | "active" / "revoked" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

###### application/json body.items item.granted_by

At least one alternative must match.

###### application/json body.items item.granted_by: alternative 1

Type: `string`. pattern: `^(users|service-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})$`

###### application/json body.items item.granted_by: alternative 2

Type: `null`. 

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. 

###### application/json body.next_page_token: alternative 2

Type: `null`.


### role-assignments-list 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.


### role-assignments-list Response 401 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.


### role-assignments-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#role-assignments-list-response-401-schema).


### role-assignments-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#role-assignments-list-response-401-schema).


### role-assignments-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#role-assignments-list-response-400-schema).


### role-assignments-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#role-assignments-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "created_at": "2026-05-01T10:00:00Z",
        "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "principal_ref": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "resource": "role_assignment",
        "role_ref": "roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "scope_anchor_kind": "explicit",
        "scope_propagation": "subtree",
        "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "status": "active",
        "updated_at": "2026-05-01T10:00:00Z"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /role-assignments

**Grant role assignment**

Requires Idempotency-Key and an active role visible for the requested scope. The grantor must hold role_assignments.create with at least the propagation reach being delegated. `scope_propagation` defaults to `subtree`; `self` reaches only the named scope. A user cannot receive a role carrying service-only capabilities. Seed-only roles cannot be granted through the API. At `platform-operators/<id>` scope a role that carries enterprise-governed capabilities needs an explicit `scope_anchor_kind`: `enterprise_wildcard` covers every enterprise, `explicit` covers the platform operator alone. Omitting it there is refused with `invalid_request` / `scope_anchor_kind_required`; at enterprise and client scope it defaults to `explicit`. `enterprise_wildcard` is allowed only at platform-operator scope, requires enterprise-governed permissions, and must use subtree propagation.

**Required capability:** `role_assignments.create`

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) *(required)* — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `principal_ref` | string | Yes | pattern: `^(users\|service-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})$` |
| `role_ref` | string | Yes | pattern: `^(roles)\/([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})$` |
| `scope_anchor_kind` | "explicit" / "enterprise_wildcard" | No |  |
| `scope_propagation` | "self" / "subtree" | No |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|platform-operators\|clients)\/([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})$` |

Additional fields are not accepted.

**Request example:**

```json
{
  "principal_ref": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "role_ref": "roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "scope_anchor_kind": "explicit",
  "scope_propagation": "subtree",
  "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}
```

### role-assignments-create Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `created_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))$` |
| `etag` | string | Yes | minLength: 1 |
| `granted_by` | string or null | No |  |
| `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)$` |
| `principal_ref` | string | Yes | pattern: `^(users\|service-accounts\|system-principals)\/([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})$` |
| `resource` | "role_assignment" | Yes |  |
| `role_ref` | string | Yes | pattern: `^(roles)\/([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})$` |
| `scope_anchor_kind` | "explicit" / "enterprise_wildcard" | Yes |  |
| `scope_propagation` | "self" / "subtree" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|platform-operators\|clients)\/([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})$` |
| `status` | "active" / "revoked" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.granted_by

At least one alternative must match.

###### application/json body.granted_by: alternative 1

Type: `string`. pattern: `^(users|service-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})$`

###### application/json body.granted_by: alternative 2

Type: `null`.


### role-assignments-create 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.


### role-assignments-create Response 401 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.


### role-assignments-create Response 403 schema

Content type: `application/json`.

See [response 401 schema](#role-assignments-create-response-401-schema).


### role-assignments-create Response 404 schema

Content type: `application/json`.

See [response 401 schema](#role-assignments-create-response-401-schema).


### role-assignments-create Response 409 schema

Content type: `application/json`.

See [response 401 schema](#role-assignments-create-response-401-schema).


### role-assignments-create Response 500 schema

Content type: `application/json`.

See [response 401 schema](#role-assignments-create-response-401-schema).


### role-assignments-create Response 502 schema

Content type: `application/json`.

See [response 400 schema](#role-assignments-create-response-400-schema).


### role-assignments-create Response 503 schema

Content type: `application/json`.

See [response 400 schema](#role-assignments-create-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "created_at": "2026-05-01T10:00:00Z",
    "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "principal_ref": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "resource": "role_assignment",
    "role_ref": "roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "scope_anchor_kind": "explicit",
    "scope_propagation": "subtree",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /role-assignments/{role_assignment_id}

**Get role assignment**

**Required capability:** `role_assignments.read`

**Authentication:** Bearer token required.

**Parameters:**

- `role_assignment_id` `string` (path) *(required)*

### role-assignments-get Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `created_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))$` |
| `etag` | string | Yes | minLength: 1 |
| `granted_by` | string or null | No |  |
| `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)$` |
| `principal_ref` | string | Yes | pattern: `^(users\|service-accounts\|system-principals)\/([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})$` |
| `resource` | "role_assignment" | Yes |  |
| `role_ref` | string | Yes | pattern: `^(roles)\/([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})$` |
| `scope_anchor_kind` | "explicit" / "enterprise_wildcard" | Yes |  |
| `scope_propagation` | "self" / "subtree" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|platform-operators\|clients)\/([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})$` |
| `status` | "active" / "revoked" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.granted_by

At least one alternative must match.

###### application/json body.granted_by: alternative 1

Type: `string`. pattern: `^(users|service-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})$`

###### application/json body.granted_by: alternative 2

Type: `null`.


### role-assignments-get 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.


### role-assignments-get Response 401 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.


### role-assignments-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#role-assignments-get-response-401-schema).


### role-assignments-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#role-assignments-get-response-401-schema).


### role-assignments-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#role-assignments-get-response-401-schema).


### role-assignments-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#role-assignments-get-response-400-schema).


### role-assignments-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#role-assignments-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "created_at": "2026-05-01T10:00:00Z",
    "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "principal_ref": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "resource": "role_assignment",
    "role_ref": "roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "scope_anchor_kind": "explicit",
    "scope_propagation": "subtree",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /role-assignments/{role_assignment_id}/revoke

**Revoke role assignment**

Revokes the assignment and returns status `revoked`; no If-Match header is required. An already revoked assignment returns 409. The final enterprise-scope assignment carrying role_assignments.manage cannot be revoked: grant another enterprise administrator first.

**Required capability:** `role_assignments.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `role_assignment_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `reason` | string or null | No |  |

Additional fields are not accepted.

#### Request body schema.reason

At least one alternative must match.

##### Request body schema.reason: alternative 1

Type: `string`. 

##### Request body schema.reason: alternative 2

Type: `null`.

### role-assignments-revoke Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `created_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))$` |
| `etag` | string | Yes | minLength: 1 |
| `granted_by` | string or null | No |  |
| `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)$` |
| `principal_ref` | string | Yes | pattern: `^(users\|service-accounts\|system-principals)\/([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})$` |
| `resource` | "role_assignment" | Yes |  |
| `role_ref` | string | Yes | pattern: `^(roles)\/([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})$` |
| `scope_anchor_kind` | "explicit" / "enterprise_wildcard" | Yes |  |
| `scope_propagation` | "self" / "subtree" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|platform-operators\|clients)\/([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})$` |
| `status` | "active" / "revoked" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.granted_by

At least one alternative must match.

###### application/json body.granted_by: alternative 1

Type: `string`. pattern: `^(users|service-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})$`

###### application/json body.granted_by: alternative 2

Type: `null`.


### role-assignments-revoke 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.


### role-assignments-revoke Response 401 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.


### role-assignments-revoke Response 403 schema

Content type: `application/json`.

See [response 401 schema](#role-assignments-revoke-response-401-schema).


### role-assignments-revoke Response 404 schema

Content type: `application/json`.

See [response 401 schema](#role-assignments-revoke-response-401-schema).


### role-assignments-revoke Response 409 schema

Content type: `application/json`.

See [response 401 schema](#role-assignments-revoke-response-401-schema).


### role-assignments-revoke Response 500 schema

Content type: `application/json`.

See [response 401 schema](#role-assignments-revoke-response-401-schema).


### role-assignments-revoke Response 502 schema

Content type: `application/json`.

See [response 400 schema](#role-assignments-revoke-response-400-schema).


### role-assignments-revoke Response 503 schema

Content type: `application/json`.

See [response 400 schema](#role-assignments-revoke-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "created_at": "2026-05-01T10:00:00Z",
    "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "principal_ref": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "resource": "role_assignment",
    "role_ref": "roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "scope_anchor_kind": "explicit",
    "scope_propagation": "subtree",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "revoked",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Identity Providers

### GET /identity-providers

**List identity providers**

Lists provider registrations in the required scope_ref workspace: enterprises/<uuid> or platform-operators/<uuid>. Repeat status to filter by multiple lifecycle states. Requires identity_providers.manage and visibility of the requested workspace.

**Required capability:** `identity_providers.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `scope_ref` `string` (query) *(required)*
- `status` `string` (query)
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### identity-providers-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `allowed_clock_skew_seconds` | integer or null | No |  |
| `auto_jit_provision` | boolean | Yes |  |
| `claim_mapping` | object | Yes | No additional fields |
| `client_id` | string | Yes | minLength: 1 |
| `client_secret_ref` | string or null | No |  |
| `created_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))$` |
| `etag` | string | Yes | minLength: 1 |
| `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)$` |
| `issuer_uri` | string | Yes | format: uri |
| `jwks_uri` | string or null | No |  |
| `last_probe_at` | string or null | No |  |
| `last_probe_ok` | boolean or null | No |  |
| `link_by_verified_email` | boolean | Yes |  |
| `protocol` | "oidc" | Yes |  |
| `resource` | "identity_provider" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|platform-operators)\/([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})$` |
| `status` | "active" / "suspended" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

###### application/json body.items item.allowed_clock_skew_seconds

At least one alternative must match.

###### application/json body.items item.allowed_clock_skew_seconds: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### application/json body.items item.allowed_clock_skew_seconds: alternative 2

Type: `null`. 

###### application/json body.items item.claim_mapping

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `auth_context` | object[] | No |  |
| `display_name` | string or null | No |  |
| `email` | string or null | No |  |
| `external_subject` | string | Yes | minLength: 1 |
| `family_name` | string or null | No |  |
| `given_name` | string or null | No |  |
| `required_claims` | object[] | No |  |

Additional fields are not accepted.

###### application/json body.items item.claim_mapping.auth_context

Type: `object[]`. 

###### application/json body.items item.claim_mapping.auth_context item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `normalized_acr` | "single-factor" / "mfa-if-enrolled" / "mfa" | Yes |  |
| `required_acr` | string | No | minLength: 1 |
| `required_amr` | string[] | No | minItems: 1 |

Additional fields are not accepted.

###### application/json body.items item.claim_mapping.auth_context item.required_amr

Type: `string[]`. minItems: 1

###### application/json body.items item.claim_mapping.auth_context item.required_amr item

Type: `string`. minLength: 1

###### application/json body.items item.claim_mapping.display_name

At least one alternative must match.

###### application/json body.items item.claim_mapping.display_name: alternative 1

Type: `string`. 

###### application/json body.items item.claim_mapping.display_name: alternative 2

Type: `null`. 

###### application/json body.items item.claim_mapping.email

At least one alternative must match.

###### application/json body.items item.claim_mapping.email: alternative 1

Type: `string`. 

###### application/json body.items item.claim_mapping.email: alternative 2

Type: `null`. 

###### application/json body.items item.claim_mapping.family_name

At least one alternative must match.

###### application/json body.items item.claim_mapping.family_name: alternative 1

Type: `string`. 

###### application/json body.items item.claim_mapping.family_name: alternative 2

Type: `null`. 

###### application/json body.items item.claim_mapping.given_name

At least one alternative must match.

###### application/json body.items item.claim_mapping.given_name: alternative 1

Type: `string`. 

###### application/json body.items item.claim_mapping.given_name: alternative 2

Type: `null`. 

###### application/json body.items item.claim_mapping.required_claims

Type: `object[]`. 

###### application/json body.items item.claim_mapping.required_claims item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `claim` | string | Yes | minLength: 1 |
| `equals` | string or boolean | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.claim_mapping.required_claims item.equals

At least one alternative must match.

###### application/json body.items item.claim_mapping.required_claims item.equals: alternative 1

Type: `string`. 

###### application/json body.items item.claim_mapping.required_claims item.equals: alternative 2

Type: `boolean`. 

###### application/json body.items item.client_secret_ref

At least one alternative must match.

###### application/json body.items item.client_secret_ref: alternative 1

Type: `string`. 

###### application/json body.items item.client_secret_ref: alternative 2

Type: `null`. 

###### application/json body.items item.jwks_uri

At least one alternative must match.

###### application/json body.items item.jwks_uri: alternative 1

Type: `string`. format: uri

###### application/json body.items item.jwks_uri: alternative 2

Type: `null`. 

###### application/json body.items item.last_probe_at

At least one alternative must match.

###### application/json body.items item.last_probe_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.last_probe_at: alternative 2

Type: `null`. 

###### application/json body.items item.last_probe_ok

At least one alternative must match.

###### application/json body.items item.last_probe_ok: alternative 1

Type: `boolean`. 

###### application/json body.items item.last_probe_ok: alternative 2

Type: `null`. 

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. 

###### application/json body.next_page_token: alternative 2

Type: `null`.


### identity-providers-list 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.


### identity-providers-list Response 401 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.


### identity-providers-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#identity-providers-list-response-401-schema).


### identity-providers-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#identity-providers-list-response-401-schema).


### identity-providers-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#identity-providers-list-response-400-schema).


### identity-providers-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#identity-providers-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "allowed_clock_skew_seconds": 30,
        "auto_jit_provision": false,
        "claim_mapping": {
          "display_name": "name",
          "email": "email",
          "external_subject": "sub",
          "family_name": "family_name",
          "given_name": "given_name"
        },
        "client_id": "my-oidc-client-id",
        "client_secret_ref": null,
        "created_at": "2026-05-01T10:00:00Z",
        "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "issuer_uri": "https://accounts.google.com",
        "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
        "link_by_verified_email": true,
        "protocol": "oidc",
        "resource": "identity_provider",
        "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "status": "active",
        "updated_at": "2026-05-01T10:00:00Z"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /identity-providers

**Register identity provider**

Registers a federated OIDC identity provider for an enterprise or platform-operator workspace. Discovery is resolved from `issuer_uri`; `jwks_uri` is optional and must match the discovery document when supplied. For an enterprise onboarded with its own identity stack (first-access method `enterprise_idp`) the body is `scope_ref`, `issuer_uri`, `client_id` and `webhook_receiver_url` only, and it registers that stack instead: a resumable saga (IdP row, issuer probe, the backend’s service account, identity and command subscriptions) that answers its ledger and replays missing steps on a repeat call. On production registration and deletion return HTTP 409 with code=state_conflict and data.reason=not_supported: identity providers are registered by seed there.

**Required capability:** `identity_providers.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

At least one alternative must match.

#### Request body schema: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `client_id` | string | Yes | minLength: 1 |
| `issuer_uri` | string | Yes | format: uri |
| `scope_ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |
| `webhook_receiver_url` | string | Yes | format: uri |

Additional fields are not accepted.

#### Request body schema: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `allowed_clock_skew_seconds` | integer or null | No |  |
| `auto_jit_provision` | boolean | No | default: `true` |
| `claim_mapping` | object | Yes | No additional fields |
| `client_id` | string | Yes | minLength: 1 |
| `client_secret_ref` | string or null | No |  |
| `issuer_uri` | string | Yes | format: uri |
| `jwks_uri` | string or null | No |  |
| `link_by_verified_email` | boolean | No | default: `false` |
| `protocol` | "oidc" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|platform-operators)\/([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})$` |

Additional fields are not accepted.

##### Request body schema: alternative 2.allowed_clock_skew_seconds

At least one alternative must match.

###### Request body schema: alternative 2.allowed_clock_skew_seconds: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### Request body schema: alternative 2.allowed_clock_skew_seconds: alternative 2

Type: `null`. 

##### Request body schema: alternative 2.claim_mapping

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `auth_context` | object[] | No |  |
| `display_name` | string or null | No |  |
| `email` | string or null | No |  |
| `external_subject` | string | Yes | minLength: 1 |
| `family_name` | string or null | No |  |
| `given_name` | string or null | No |  |
| `required_claims` | object[] | No |  |

Additional fields are not accepted.

###### Request body schema: alternative 2.claim_mapping.auth_context

Type: `object[]`. 

###### Request body schema: alternative 2.claim_mapping.auth_context item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `normalized_acr` | "single-factor" / "mfa-if-enrolled" / "mfa" | Yes |  |
| `required_acr` | string | No | minLength: 1 |
| `required_amr` | string[] | No | minItems: 1 |

Additional fields are not accepted.

###### Request body schema: alternative 2.claim_mapping.auth_context item.required_amr

Type: `string[]`. minItems: 1

###### Request body schema: alternative 2.claim_mapping.auth_context item.required_amr item

Type: `string`. minLength: 1

###### Request body schema: alternative 2.claim_mapping.display_name

At least one alternative must match.

###### Request body schema: alternative 2.claim_mapping.display_name: alternative 1

Type: `string`. 

###### Request body schema: alternative 2.claim_mapping.display_name: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.claim_mapping.email

At least one alternative must match.

###### Request body schema: alternative 2.claim_mapping.email: alternative 1

Type: `string`. 

###### Request body schema: alternative 2.claim_mapping.email: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.claim_mapping.family_name

At least one alternative must match.

###### Request body schema: alternative 2.claim_mapping.family_name: alternative 1

Type: `string`. 

###### Request body schema: alternative 2.claim_mapping.family_name: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.claim_mapping.given_name

At least one alternative must match.

###### Request body schema: alternative 2.claim_mapping.given_name: alternative 1

Type: `string`. 

###### Request body schema: alternative 2.claim_mapping.given_name: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.claim_mapping.required_claims

Type: `object[]`. 

###### Request body schema: alternative 2.claim_mapping.required_claims item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `claim` | string | Yes | minLength: 1 |
| `equals` | string or boolean | Yes |  |

Additional fields are not accepted.

###### Request body schema: alternative 2.claim_mapping.required_claims item.equals

At least one alternative must match.

###### Request body schema: alternative 2.claim_mapping.required_claims item.equals: alternative 1

Type: `string`. 

###### Request body schema: alternative 2.claim_mapping.required_claims item.equals: alternative 2

Type: `boolean`. 

##### Request body schema: alternative 2.client_secret_ref

At least one alternative must match.

###### Request body schema: alternative 2.client_secret_ref: alternative 1

Type: `string`. 

###### Request body schema: alternative 2.client_secret_ref: alternative 2

Type: `null`. 

##### Request body schema: alternative 2.jwks_uri

At least one alternative must match.

###### Request body schema: alternative 2.jwks_uri: alternative 1

Type: `string`. format: uri

###### Request body schema: alternative 2.jwks_uri: alternative 2

Type: `null`.

**Request example:**

```json
{
  "allowed_clock_skew_seconds": 30,
  "auto_jit_provision": false,
  "claim_mapping": {
    "display_name": "name",
    "email": "email",
    "external_subject": "sub",
    "family_name": "family_name",
    "given_name": "given_name"
  },
  "client_id": "my-oidc-client-id",
  "client_secret_ref": null,
  "issuer_uri": "https://accounts.google.com",
  "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
  "link_by_verified_email": true,
  "protocol": "oidc",
  "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}
```

### identity-providers-create Response 201 schema

Content type: `application/json`.

#### application/json body

At least one alternative must match.

##### application/json body: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `allowed_clock_skew_seconds` | integer or null | No |  |
| `auto_jit_provision` | boolean | Yes |  |
| `claim_mapping` | object | Yes | No additional fields |
| `client_id` | string | Yes | minLength: 1 |
| `client_secret_ref` | string or null | No |  |
| `created_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))$` |
| `etag` | string | Yes | minLength: 1 |
| `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)$` |
| `issuer_uri` | string | Yes | format: uri |
| `jwks_uri` | string or null | No |  |
| `last_probe_at` | string or null | No |  |
| `last_probe_ok` | boolean or null | No |  |
| `link_by_verified_email` | boolean | Yes |  |
| `protocol` | "oidc" | Yes |  |
| `resource` | "identity_provider" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|platform-operators)\/([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})$` |
| `status` | "active" / "suspended" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

###### application/json body: alternative 1.allowed_clock_skew_seconds

At least one alternative must match.

###### application/json body: alternative 1.allowed_clock_skew_seconds: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### application/json body: alternative 1.allowed_clock_skew_seconds: alternative 2

Type: `null`. 

###### application/json body: alternative 1.claim_mapping

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `auth_context` | object[] | No |  |
| `display_name` | string or null | No |  |
| `email` | string or null | No |  |
| `external_subject` | string | Yes | minLength: 1 |
| `family_name` | string or null | No |  |
| `given_name` | string or null | No |  |
| `required_claims` | object[] | No |  |

Additional fields are not accepted.

###### application/json body: alternative 1.claim_mapping.auth_context

Type: `object[]`. 

###### application/json body: alternative 1.claim_mapping.auth_context item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `normalized_acr` | "single-factor" / "mfa-if-enrolled" / "mfa" | Yes |  |
| `required_acr` | string | No | minLength: 1 |
| `required_amr` | string[] | No | minItems: 1 |

Additional fields are not accepted.

###### application/json body: alternative 1.claim_mapping.auth_context item.required_amr

Type: `string[]`. minItems: 1

###### application/json body: alternative 1.claim_mapping.auth_context item.required_amr item

Type: `string`. minLength: 1

###### application/json body: alternative 1.claim_mapping.display_name

At least one alternative must match.

###### application/json body: alternative 1.claim_mapping.display_name: alternative 1

Type: `string`. 

###### application/json body: alternative 1.claim_mapping.display_name: alternative 2

Type: `null`. 

###### application/json body: alternative 1.claim_mapping.email

At least one alternative must match.

###### application/json body: alternative 1.claim_mapping.email: alternative 1

Type: `string`. 

###### application/json body: alternative 1.claim_mapping.email: alternative 2

Type: `null`. 

###### application/json body: alternative 1.claim_mapping.family_name

At least one alternative must match.

###### application/json body: alternative 1.claim_mapping.family_name: alternative 1

Type: `string`. 

###### application/json body: alternative 1.claim_mapping.family_name: alternative 2

Type: `null`. 

###### application/json body: alternative 1.claim_mapping.given_name

At least one alternative must match.

###### application/json body: alternative 1.claim_mapping.given_name: alternative 1

Type: `string`. 

###### application/json body: alternative 1.claim_mapping.given_name: alternative 2

Type: `null`. 

###### application/json body: alternative 1.claim_mapping.required_claims

Type: `object[]`. 

###### application/json body: alternative 1.claim_mapping.required_claims item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `claim` | string | Yes | minLength: 1 |
| `equals` | string or boolean | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 1.claim_mapping.required_claims item.equals

At least one alternative must match.

###### application/json body: alternative 1.claim_mapping.required_claims item.equals: alternative 1

Type: `string`. 

###### application/json body: alternative 1.claim_mapping.required_claims item.equals: alternative 2

Type: `boolean`. 

###### application/json body: alternative 1.client_secret_ref

At least one alternative must match.

###### application/json body: alternative 1.client_secret_ref: alternative 1

Type: `string`. 

###### application/json body: alternative 1.client_secret_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 1.jwks_uri

At least one alternative must match.

###### application/json body: alternative 1.jwks_uri: alternative 1

Type: `string`. format: uri

###### application/json body: alternative 1.jwks_uri: alternative 2

Type: `null`. 

###### application/json body: alternative 1.last_probe_at

At least one alternative must match.

###### application/json body: alternative 1.last_probe_at: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 1.last_probe_at: alternative 2

Type: `null`. 

###### application/json body: alternative 1.last_probe_ok

At least one alternative must match.

###### application/json body: alternative 1.last_probe_ok: alternative 1

Type: `boolean`. 

###### application/json body: alternative 1.last_probe_ok: alternative 2

Type: `null`. 

##### application/json body: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `command_subscription_id` | string or null | Yes |  |
| `enterprise_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)$` |
| `failing_step` | "identity_provider" / "probe" / "service_account" / "identity_subscription" / "command_subscription" or null | Yes |  |
| `identity_provider_id` | string or null | Yes |  |
| `identity_subscription_id` | string or null | Yes |  |
| `probe_ok` | boolean | Yes |  |
| `ready` | boolean | Yes |  |
| `service_principal_id` | string or null | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

###### application/json body: alternative 2.command_subscription_id

At least one alternative must match.

###### application/json body: alternative 2.command_subscription_id: alternative 1

Type: `string`. 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)$`

###### application/json body: alternative 2.command_subscription_id: alternative 2

Type: `null`. 

###### application/json body: alternative 2.failing_step

At least one alternative must match.

###### application/json body: alternative 2.failing_step: alternative 1

Type: `"identity_provider" / "probe" / "service_account" / "identity_subscription" / "command_subscription"`. 

###### application/json body: alternative 2.failing_step: alternative 2

Type: `null`. 

###### application/json body: alternative 2.identity_provider_id

At least one alternative must match.

###### application/json body: alternative 2.identity_provider_id: alternative 1

Type: `string`. 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)$`

###### application/json body: alternative 2.identity_provider_id: alternative 2

Type: `null`. 

###### application/json body: alternative 2.identity_subscription_id

At least one alternative must match.

###### application/json body: alternative 2.identity_subscription_id: alternative 1

Type: `string`. 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)$`

###### application/json body: alternative 2.identity_subscription_id: alternative 2

Type: `null`. 

###### application/json body: alternative 2.service_principal_id

At least one alternative must match.

###### application/json body: alternative 2.service_principal_id: alternative 1

Type: `string`. 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)$`

###### application/json body: alternative 2.service_principal_id: alternative 2

Type: `null`.


### identity-providers-create 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.


### identity-providers-create Response 401 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.


### identity-providers-create Response 403 schema

Content type: `application/json`.

See [response 401 schema](#identity-providers-create-response-401-schema).


### identity-providers-create Response 409 schema

Content type: `application/json`.

See [response 401 schema](#identity-providers-create-response-401-schema).


### identity-providers-create Response 500 schema

Content type: `application/json`.

See [response 401 schema](#identity-providers-create-response-401-schema).


### identity-providers-create Response 502 schema

Content type: `application/json`.

See [response 400 schema](#identity-providers-create-response-400-schema).


### identity-providers-create Response 503 schema

Content type: `application/json`.

See [response 400 schema](#identity-providers-create-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "allowed_clock_skew_seconds": 30,
    "auto_jit_provision": false,
    "claim_mapping": {
      "display_name": "name",
      "email": "email",
      "external_subject": "sub",
      "family_name": "family_name",
      "given_name": "given_name"
    },
    "client_id": "my-oidc-client-id",
    "client_secret_ref": null,
    "created_at": "2026-05-01T10:00:00Z",
    "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "issuer_uri": "https://accounts.google.com",
    "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
    "link_by_verified_email": true,
    "protocol": "oidc",
    "resource": "identity_provider",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /identity-providers/{identity_provider_id}

**Get identity provider**

**Required capability:** `identity_providers.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `identity_provider_id` `string` (path) *(required)*

### identity-providers-get Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `allowed_clock_skew_seconds` | integer or null | No |  |
| `auto_jit_provision` | boolean | Yes |  |
| `claim_mapping` | object | Yes | No additional fields |
| `client_id` | string | Yes | minLength: 1 |
| `client_secret_ref` | string or null | No |  |
| `created_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))$` |
| `etag` | string | Yes | minLength: 1 |
| `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)$` |
| `issuer_uri` | string | Yes | format: uri |
| `jwks_uri` | string or null | No |  |
| `last_probe_at` | string or null | No |  |
| `last_probe_ok` | boolean or null | No |  |
| `link_by_verified_email` | boolean | Yes |  |
| `protocol` | "oidc" | Yes |  |
| `resource` | "identity_provider" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|platform-operators)\/([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})$` |
| `status` | "active" / "suspended" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.allowed_clock_skew_seconds

At least one alternative must match.

###### application/json body.allowed_clock_skew_seconds: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### application/json body.allowed_clock_skew_seconds: alternative 2

Type: `null`. 

##### application/json body.claim_mapping

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `auth_context` | object[] | No |  |
| `display_name` | string or null | No |  |
| `email` | string or null | No |  |
| `external_subject` | string | Yes | minLength: 1 |
| `family_name` | string or null | No |  |
| `given_name` | string or null | No |  |
| `required_claims` | object[] | No |  |

Additional fields are not accepted.

###### application/json body.claim_mapping.auth_context

Type: `object[]`. 

###### application/json body.claim_mapping.auth_context item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `normalized_acr` | "single-factor" / "mfa-if-enrolled" / "mfa" | Yes |  |
| `required_acr` | string | No | minLength: 1 |
| `required_amr` | string[] | No | minItems: 1 |

Additional fields are not accepted.

###### application/json body.claim_mapping.auth_context item.required_amr

Type: `string[]`. minItems: 1

###### application/json body.claim_mapping.auth_context item.required_amr item

Type: `string`. minLength: 1

###### application/json body.claim_mapping.display_name

At least one alternative must match.

###### application/json body.claim_mapping.display_name: alternative 1

Type: `string`. 

###### application/json body.claim_mapping.display_name: alternative 2

Type: `null`. 

###### application/json body.claim_mapping.email

At least one alternative must match.

###### application/json body.claim_mapping.email: alternative 1

Type: `string`. 

###### application/json body.claim_mapping.email: alternative 2

Type: `null`. 

###### application/json body.claim_mapping.family_name

At least one alternative must match.

###### application/json body.claim_mapping.family_name: alternative 1

Type: `string`. 

###### application/json body.claim_mapping.family_name: alternative 2

Type: `null`. 

###### application/json body.claim_mapping.given_name

At least one alternative must match.

###### application/json body.claim_mapping.given_name: alternative 1

Type: `string`. 

###### application/json body.claim_mapping.given_name: alternative 2

Type: `null`. 

###### application/json body.claim_mapping.required_claims

Type: `object[]`. 

###### application/json body.claim_mapping.required_claims item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `claim` | string | Yes | minLength: 1 |
| `equals` | string or boolean | Yes |  |

Additional fields are not accepted.

###### application/json body.claim_mapping.required_claims item.equals

At least one alternative must match.

###### application/json body.claim_mapping.required_claims item.equals: alternative 1

Type: `string`. 

###### application/json body.claim_mapping.required_claims item.equals: alternative 2

Type: `boolean`. 

##### application/json body.client_secret_ref

At least one alternative must match.

###### application/json body.client_secret_ref: alternative 1

Type: `string`. 

###### application/json body.client_secret_ref: alternative 2

Type: `null`. 

##### application/json body.jwks_uri

At least one alternative must match.

###### application/json body.jwks_uri: alternative 1

Type: `string`. format: uri

###### application/json body.jwks_uri: alternative 2

Type: `null`. 

##### application/json body.last_probe_at

At least one alternative must match.

###### application/json body.last_probe_at: alternative 1

Type: `string`. 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))$`

###### application/json body.last_probe_at: alternative 2

Type: `null`. 

##### application/json body.last_probe_ok

At least one alternative must match.

###### application/json body.last_probe_ok: alternative 1

Type: `boolean`. 

###### application/json body.last_probe_ok: alternative 2

Type: `null`.


### identity-providers-get 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.


### identity-providers-get Response 401 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.


### identity-providers-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#identity-providers-get-response-401-schema).


### identity-providers-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#identity-providers-get-response-401-schema).


### identity-providers-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#identity-providers-get-response-401-schema).


### identity-providers-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#identity-providers-get-response-400-schema).


### identity-providers-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#identity-providers-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "allowed_clock_skew_seconds": 30,
    "auto_jit_provision": false,
    "claim_mapping": {
      "display_name": "name",
      "email": "email",
      "external_subject": "sub",
      "family_name": "family_name",
      "given_name": "given_name"
    },
    "client_id": "my-oidc-client-id",
    "client_secret_ref": null,
    "created_at": "2026-05-01T10:00:00Z",
    "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "issuer_uri": "https://accounts.google.com",
    "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
    "link_by_verified_email": true,
    "protocol": "oidc",
    "resource": "identity_provider",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /identity-providers/{identity_provider_id}/delete

**Delete identity provider**

Deletes a suspended provider registration and returns an empty JSON object. Active providers must first be suspended. Enterprise identity-stack trust roots cannot be deleted. On production this route returns HTTP 409 with code=state_conflict and data.reason=not_supported; the same reason applies to an enterprise identity-stack deletion in every environment.

**Required capability:** `identity_providers.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `identity_provider_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `reason` | string or null | No |  |

Additional fields are not accepted.

#### Request body schema.reason

At least one alternative must match.

##### Request body schema.reason: alternative 1

Type: `string`. 

##### Request body schema.reason: alternative 2

Type: `null`.

**Request example:**

```json
{
  "reason": "issuer compromised"
}
```

### identity-providers-delete Response 200 schema

Content type: `application/json`.

#### application/json body

Type: `object`. No additional fields


### identity-providers-delete 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.


### identity-providers-delete Response 401 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.


### identity-providers-delete Response 403 schema

Content type: `application/json`.

See [response 401 schema](#identity-providers-delete-response-401-schema).


### identity-providers-delete Response 404 schema

Content type: `application/json`.

See [response 401 schema](#identity-providers-delete-response-401-schema).


### identity-providers-delete Response 409 schema

Content type: `application/json`.

See [response 401 schema](#identity-providers-delete-response-401-schema).


### identity-providers-delete Response 500 schema

Content type: `application/json`.

See [response 401 schema](#identity-providers-delete-response-401-schema).


### identity-providers-delete Response 502 schema

Content type: `application/json`.

See [response 400 schema](#identity-providers-delete-response-400-schema).


### identity-providers-delete Response 503 schema

Content type: `application/json`.

See [response 400 schema](#identity-providers-delete-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {}
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /identity-providers/{identity_provider_id}/reactivate

**Reactivate identity provider**

The identity provider of an enterprise that runs its own identity stack is that enterprise’s trust root: only platform staff may flip it; an enterprise-bound caller gets HTTP 403 with data.reason=platform_only_for_enterprise_idp.

**Required capability:** `identity_providers.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `identity_provider_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `reason` | string or null | No |  |

Additional fields are not accepted.

#### Request body schema.reason

At least one alternative must match.

##### Request body schema.reason: alternative 1

Type: `string`. 

##### Request body schema.reason: alternative 2

Type: `null`.

**Request example:**

```json
{
  "reason": "issuer compromised"
}
```

### identity-providers-reactivate Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `allowed_clock_skew_seconds` | integer or null | No |  |
| `auto_jit_provision` | boolean | Yes |  |
| `claim_mapping` | object | Yes | No additional fields |
| `client_id` | string | Yes | minLength: 1 |
| `client_secret_ref` | string or null | No |  |
| `created_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))$` |
| `etag` | string | Yes | minLength: 1 |
| `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)$` |
| `issuer_uri` | string | Yes | format: uri |
| `jwks_uri` | string or null | No |  |
| `last_probe_at` | string or null | No |  |
| `last_probe_ok` | boolean or null | No |  |
| `link_by_verified_email` | boolean | Yes |  |
| `protocol` | "oidc" | Yes |  |
| `resource` | "identity_provider" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|platform-operators)\/([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})$` |
| `status` | "active" / "suspended" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.allowed_clock_skew_seconds

At least one alternative must match.

###### application/json body.allowed_clock_skew_seconds: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### application/json body.allowed_clock_skew_seconds: alternative 2

Type: `null`. 

##### application/json body.claim_mapping

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `auth_context` | object[] | No |  |
| `display_name` | string or null | No |  |
| `email` | string or null | No |  |
| `external_subject` | string | Yes | minLength: 1 |
| `family_name` | string or null | No |  |
| `given_name` | string or null | No |  |
| `required_claims` | object[] | No |  |

Additional fields are not accepted.

###### application/json body.claim_mapping.auth_context

Type: `object[]`. 

###### application/json body.claim_mapping.auth_context item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `normalized_acr` | "single-factor" / "mfa-if-enrolled" / "mfa" | Yes |  |
| `required_acr` | string | No | minLength: 1 |
| `required_amr` | string[] | No | minItems: 1 |

Additional fields are not accepted.

###### application/json body.claim_mapping.auth_context item.required_amr

Type: `string[]`. minItems: 1

###### application/json body.claim_mapping.auth_context item.required_amr item

Type: `string`. minLength: 1

###### application/json body.claim_mapping.display_name

At least one alternative must match.

###### application/json body.claim_mapping.display_name: alternative 1

Type: `string`. 

###### application/json body.claim_mapping.display_name: alternative 2

Type: `null`. 

###### application/json body.claim_mapping.email

At least one alternative must match.

###### application/json body.claim_mapping.email: alternative 1

Type: `string`. 

###### application/json body.claim_mapping.email: alternative 2

Type: `null`. 

###### application/json body.claim_mapping.family_name

At least one alternative must match.

###### application/json body.claim_mapping.family_name: alternative 1

Type: `string`. 

###### application/json body.claim_mapping.family_name: alternative 2

Type: `null`. 

###### application/json body.claim_mapping.given_name

At least one alternative must match.

###### application/json body.claim_mapping.given_name: alternative 1

Type: `string`. 

###### application/json body.claim_mapping.given_name: alternative 2

Type: `null`. 

###### application/json body.claim_mapping.required_claims

Type: `object[]`. 

###### application/json body.claim_mapping.required_claims item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `claim` | string | Yes | minLength: 1 |
| `equals` | string or boolean | Yes |  |

Additional fields are not accepted.

###### application/json body.claim_mapping.required_claims item.equals

At least one alternative must match.

###### application/json body.claim_mapping.required_claims item.equals: alternative 1

Type: `string`. 

###### application/json body.claim_mapping.required_claims item.equals: alternative 2

Type: `boolean`. 

##### application/json body.client_secret_ref

At least one alternative must match.

###### application/json body.client_secret_ref: alternative 1

Type: `string`. 

###### application/json body.client_secret_ref: alternative 2

Type: `null`. 

##### application/json body.jwks_uri

At least one alternative must match.

###### application/json body.jwks_uri: alternative 1

Type: `string`. format: uri

###### application/json body.jwks_uri: alternative 2

Type: `null`. 

##### application/json body.last_probe_at

At least one alternative must match.

###### application/json body.last_probe_at: alternative 1

Type: `string`. 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))$`

###### application/json body.last_probe_at: alternative 2

Type: `null`. 

##### application/json body.last_probe_ok

At least one alternative must match.

###### application/json body.last_probe_ok: alternative 1

Type: `boolean`. 

###### application/json body.last_probe_ok: alternative 2

Type: `null`.


### identity-providers-reactivate 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.


### identity-providers-reactivate Response 401 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.


### identity-providers-reactivate Response 403 schema

Content type: `application/json`.

See [response 401 schema](#identity-providers-reactivate-response-401-schema).


### identity-providers-reactivate Response 404 schema

Content type: `application/json`.

See [response 401 schema](#identity-providers-reactivate-response-401-schema).


### identity-providers-reactivate Response 409 schema

Content type: `application/json`.

See [response 401 schema](#identity-providers-reactivate-response-401-schema).


### identity-providers-reactivate Response 500 schema

Content type: `application/json`.

See [response 401 schema](#identity-providers-reactivate-response-401-schema).


### identity-providers-reactivate Response 502 schema

Content type: `application/json`.

See [response 400 schema](#identity-providers-reactivate-response-400-schema).


### identity-providers-reactivate Response 503 schema

Content type: `application/json`.

See [response 400 schema](#identity-providers-reactivate-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "allowed_clock_skew_seconds": 30,
    "auto_jit_provision": false,
    "claim_mapping": {
      "display_name": "name",
      "email": "email",
      "external_subject": "sub",
      "family_name": "family_name",
      "given_name": "given_name"
    },
    "client_id": "my-oidc-client-id",
    "client_secret_ref": null,
    "created_at": "2026-05-01T10:00:00Z",
    "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "issuer_uri": "https://accounts.google.com",
    "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
    "link_by_verified_email": true,
    "protocol": "oidc",
    "resource": "identity_provider",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /identity-providers/{identity_provider_id}/suspend

**Suspend identity provider**

The identity provider of an enterprise that runs its own identity stack is that enterprise’s trust root: only platform staff may flip it; an enterprise-bound caller gets HTTP 403 with data.reason=platform_only_for_enterprise_idp.

**Required capability:** `identity_providers.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `identity_provider_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `reason` | string or null | No |  |

Additional fields are not accepted.

#### Request body schema.reason

At least one alternative must match.

##### Request body schema.reason: alternative 1

Type: `string`. 

##### Request body schema.reason: alternative 2

Type: `null`.

**Request example:**

```json
{
  "reason": "issuer compromised"
}
```

### identity-providers-suspend Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `allowed_clock_skew_seconds` | integer or null | No |  |
| `auto_jit_provision` | boolean | Yes |  |
| `claim_mapping` | object | Yes | No additional fields |
| `client_id` | string | Yes | minLength: 1 |
| `client_secret_ref` | string or null | No |  |
| `created_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))$` |
| `etag` | string | Yes | minLength: 1 |
| `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)$` |
| `issuer_uri` | string | Yes | format: uri |
| `jwks_uri` | string or null | No |  |
| `last_probe_at` | string or null | No |  |
| `last_probe_ok` | boolean or null | No |  |
| `link_by_verified_email` | boolean | Yes |  |
| `protocol` | "oidc" | Yes |  |
| `resource` | "identity_provider" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|platform-operators)\/([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})$` |
| `status` | "active" / "suspended" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.allowed_clock_skew_seconds

At least one alternative must match.

###### application/json body.allowed_clock_skew_seconds: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### application/json body.allowed_clock_skew_seconds: alternative 2

Type: `null`. 

##### application/json body.claim_mapping

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `auth_context` | object[] | No |  |
| `display_name` | string or null | No |  |
| `email` | string or null | No |  |
| `external_subject` | string | Yes | minLength: 1 |
| `family_name` | string or null | No |  |
| `given_name` | string or null | No |  |
| `required_claims` | object[] | No |  |

Additional fields are not accepted.

###### application/json body.claim_mapping.auth_context

Type: `object[]`. 

###### application/json body.claim_mapping.auth_context item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `normalized_acr` | "single-factor" / "mfa-if-enrolled" / "mfa" | Yes |  |
| `required_acr` | string | No | minLength: 1 |
| `required_amr` | string[] | No | minItems: 1 |

Additional fields are not accepted.

###### application/json body.claim_mapping.auth_context item.required_amr

Type: `string[]`. minItems: 1

###### application/json body.claim_mapping.auth_context item.required_amr item

Type: `string`. minLength: 1

###### application/json body.claim_mapping.display_name

At least one alternative must match.

###### application/json body.claim_mapping.display_name: alternative 1

Type: `string`. 

###### application/json body.claim_mapping.display_name: alternative 2

Type: `null`. 

###### application/json body.claim_mapping.email

At least one alternative must match.

###### application/json body.claim_mapping.email: alternative 1

Type: `string`. 

###### application/json body.claim_mapping.email: alternative 2

Type: `null`. 

###### application/json body.claim_mapping.family_name

At least one alternative must match.

###### application/json body.claim_mapping.family_name: alternative 1

Type: `string`. 

###### application/json body.claim_mapping.family_name: alternative 2

Type: `null`. 

###### application/json body.claim_mapping.given_name

At least one alternative must match.

###### application/json body.claim_mapping.given_name: alternative 1

Type: `string`. 

###### application/json body.claim_mapping.given_name: alternative 2

Type: `null`. 

###### application/json body.claim_mapping.required_claims

Type: `object[]`. 

###### application/json body.claim_mapping.required_claims item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `claim` | string | Yes | minLength: 1 |
| `equals` | string or boolean | Yes |  |

Additional fields are not accepted.

###### application/json body.claim_mapping.required_claims item.equals

At least one alternative must match.

###### application/json body.claim_mapping.required_claims item.equals: alternative 1

Type: `string`. 

###### application/json body.claim_mapping.required_claims item.equals: alternative 2

Type: `boolean`. 

##### application/json body.client_secret_ref

At least one alternative must match.

###### application/json body.client_secret_ref: alternative 1

Type: `string`. 

###### application/json body.client_secret_ref: alternative 2

Type: `null`. 

##### application/json body.jwks_uri

At least one alternative must match.

###### application/json body.jwks_uri: alternative 1

Type: `string`. format: uri

###### application/json body.jwks_uri: alternative 2

Type: `null`. 

##### application/json body.last_probe_at

At least one alternative must match.

###### application/json body.last_probe_at: alternative 1

Type: `string`. 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))$`

###### application/json body.last_probe_at: alternative 2

Type: `null`. 

##### application/json body.last_probe_ok

At least one alternative must match.

###### application/json body.last_probe_ok: alternative 1

Type: `boolean`. 

###### application/json body.last_probe_ok: alternative 2

Type: `null`.


### identity-providers-suspend 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.


### identity-providers-suspend Response 401 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.


### identity-providers-suspend Response 403 schema

Content type: `application/json`.

See [response 401 schema](#identity-providers-suspend-response-401-schema).


### identity-providers-suspend Response 404 schema

Content type: `application/json`.

See [response 401 schema](#identity-providers-suspend-response-401-schema).


### identity-providers-suspend Response 409 schema

Content type: `application/json`.

See [response 401 schema](#identity-providers-suspend-response-401-schema).


### identity-providers-suspend Response 500 schema

Content type: `application/json`.

See [response 401 schema](#identity-providers-suspend-response-401-schema).


### identity-providers-suspend Response 502 schema

Content type: `application/json`.

See [response 400 schema](#identity-providers-suspend-response-400-schema).


### identity-providers-suspend Response 503 schema

Content type: `application/json`.

See [response 400 schema](#identity-providers-suspend-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "allowed_clock_skew_seconds": 30,
    "auto_jit_provision": false,
    "claim_mapping": {
      "display_name": "name",
      "email": "email",
      "external_subject": "sub",
      "family_name": "family_name",
      "given_name": "given_name"
    },
    "client_id": "my-oidc-client-id",
    "client_secret_ref": null,
    "created_at": "2026-05-01T10:00:00Z",
    "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "issuer_uri": "https://accounts.google.com",
    "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
    "link_by_verified_email": true,
    "protocol": "oidc",
    "resource": "identity_provider",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "suspended",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Capabilities

### GET /capabilities

**List capabilities**

Lists feature enablement flags for the requested topology node, sorted by name. enabled resolves the platform default/override, enterprise override and client override chain; disabled entries remain visible. Requires feature_flags.read with scope coverage. These catalog flags do not describe the caller's role grants; use GET /me/capabilities for current effective RBAC authority. page_size defaults to 100 (maximum 200).

**Required capability:** `feature_flags.read`

**Authentication:** Bearer token required.

**Parameters:**

- `scope_ref` `string` (query) *(required)*
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### capabilities-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1 |
| `enabled` | boolean | Yes |  |

Additional fields are not accepted.

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. 

###### application/json body.next_page_token: alternative 2

Type: `null`.


### capabilities-list 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.


### capabilities-list Response 401 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.


### capabilities-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#capabilities-list-response-401-schema).


### capabilities-list Response 404 schema

Content type: `application/json`.

See [response 401 schema](#capabilities-list-response-401-schema).


### capabilities-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#capabilities-list-response-401-schema).


### capabilities-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#capabilities-list-response-400-schema).


### capabilities-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#capabilities-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "name": "deposit_fiat",
        "enabled": true
      },
      {
        "name": "staking",
        "enabled": false
      },
      {
        "name": "withdrawal",
        "enabled": true
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### PATCH /clients/{client_id}/capabilities/{capability_name}

**Toggle capability override for client (deprecated)**

Retired endpoint. Every authenticated call returns 410 deprecated_endpoint before reading the path or body; it cannot change a feature override. No request body or success response is supported.

**Authentication:** Bearer token required.

**Parameters:**

- `client_id` `string` (path) *(required)*
- `capability_name` `string` (path) *(required)*

### clients-capabilities-update Response 401 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.


### clients-capabilities-update Response 410 schema

Content type: `application/json`.

See [response 401 schema](#clients-capabilities-update-response-401-schema).


**Responses:**

- `401` — Caller is not authenticated or the bearer token is invalid.
- `410` — The endpoint has been retired and returns code deprecated_endpoint.

## Policies

### GET /clients/{client_id}/mfa-assurance

**Read client MFA policy**

Read the MFA assurance setting for this scope. Requires policies.read covering the target scope. own_mode is null when this scope inherits its policy; effective_mode and source_scope_ref describe the resolved policy. owner identifies a scope-owned or platform-owned local row and is null when no local row exists. With no setting in the lineage, effective_mode is optional and source_scope_ref is null. Platform human sessions always have a mandatory MFA floor independent of these enterprise/client settings.

**Required capability:** `policies.read`

**Authentication:** Bearer token required.

**Parameters:**

- `client_id` `string` (path) *(required)*

### clients-mfa-assurance-get Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `effective_mode` | "optional" / "mandatory" | Yes |  |
| `own_mode` | "optional" / "mandatory" or null | Yes |  |
| `owner` | "scope" / "platform" or null | No |  |
| `scope_ref` | string or string | Yes |  |
| `source_scope_ref` | string or string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.own_mode

At least one alternative must match.

###### application/json body.own_mode: alternative 1

Type: `"optional" / "mandatory"`. 

###### application/json body.own_mode: alternative 2

Type: `null`. 

##### application/json body.owner

At least one alternative must match.

###### application/json body.owner: alternative 1

Type: `"scope" / "platform"`. 

###### application/json body.owner: alternative 2

Type: `null`. 

##### application/json body.scope_ref

At least one alternative must match.

###### application/json body.scope_ref: alternative 1

Type: `string`. pattern: `^(enterprises)\/([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})$`

###### application/json body.scope_ref: alternative 2

Type: `string`. pattern: `^(clients)\/([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})$`

##### application/json body.source_scope_ref

At least one alternative must match.

###### application/json body.source_scope_ref: alternative 1

At least one alternative must match.

###### application/json body.source_scope_ref: alternative 1: alternative 1

Type: `string`. pattern: `^(enterprises)\/([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})$`

###### application/json body.source_scope_ref: alternative 1: alternative 2

Type: `string`. pattern: `^(clients)\/([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})$`

###### application/json body.source_scope_ref: alternative 2

Type: `null`.


### clients-mfa-assurance-get 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.


### clients-mfa-assurance-get Response 401 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.


### clients-mfa-assurance-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#clients-mfa-assurance-get-response-401-schema).


### clients-mfa-assurance-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#clients-mfa-assurance-get-response-401-schema).


### clients-mfa-assurance-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#clients-mfa-assurance-get-response-401-schema).


### clients-mfa-assurance-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#clients-mfa-assurance-get-response-400-schema).


### clients-mfa-assurance-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#clients-mfa-assurance-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "effective_mode": "mandatory",
    "own_mode": "mandatory",
    "owner": "scope",
    "scope_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "source_scope_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### PUT /clients/{client_id}/mfa-assurance

**Set client MFA policy**

Requires both policies.manage and policies.read covering the target scope; the current setting is read for the audit diff before writing. Set mode to inherited to remove the scope setting. Setting optional beneath a mandatory ancestor returns HTTP 409 with data.reason=mfa_cannot_relax and data.resource naming that ancestor. A platform-owned setting may only be changed by platform staff with platform-wide policies.manage authority; other callers receive HTTP 403 with data.reason=mfa_setting_platform_owned. The required reason is trimmed and must contain 3 to 500 characters for the audit record. This changes the assurance policy; it does not enroll or remove an authentication factor.

**Required capability:** `policies.manage`, `policies.read`

**Authentication:** Bearer token required.

**Parameters:**

- `client_id` `string` (path) *(required)*

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `mode` | "inherited" or "optional" / "mandatory" | Yes |  |
| `reason` | string | Yes | minLength: 3; maxLength: 500 |

Additional fields are not accepted.

#### Request body schema.mode

At least one alternative must match.

##### Request body schema.mode: alternative 1

Type: `"inherited"`. 

##### Request body schema.mode: alternative 2

Type: `"optional" / "mandatory"`.

**Request example:**

```json
{
  "mode": "mandatory",
  "reason": "Require fresh authentication for protected actions"
}
```

### clients-mfa-assurance-set Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `effective_mode` | "optional" / "mandatory" | Yes |  |
| `own_mode` | "optional" / "mandatory" or null | Yes |  |
| `owner` | "scope" / "platform" or null | No |  |
| `scope_ref` | string or string | Yes |  |
| `source_scope_ref` | string or string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.own_mode

At least one alternative must match.

###### application/json body.own_mode: alternative 1

Type: `"optional" / "mandatory"`. 

###### application/json body.own_mode: alternative 2

Type: `null`. 

##### application/json body.owner

At least one alternative must match.

###### application/json body.owner: alternative 1

Type: `"scope" / "platform"`. 

###### application/json body.owner: alternative 2

Type: `null`. 

##### application/json body.scope_ref

At least one alternative must match.

###### application/json body.scope_ref: alternative 1

Type: `string`. pattern: `^(enterprises)\/([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})$`

###### application/json body.scope_ref: alternative 2

Type: `string`. pattern: `^(clients)\/([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})$`

##### application/json body.source_scope_ref

At least one alternative must match.

###### application/json body.source_scope_ref: alternative 1

At least one alternative must match.

###### application/json body.source_scope_ref: alternative 1: alternative 1

Type: `string`. pattern: `^(enterprises)\/([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})$`

###### application/json body.source_scope_ref: alternative 1: alternative 2

Type: `string`. pattern: `^(clients)\/([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})$`

###### application/json body.source_scope_ref: alternative 2

Type: `null`.


### clients-mfa-assurance-set 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.


### clients-mfa-assurance-set Response 401 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.


### clients-mfa-assurance-set Response 403 schema

Content type: `application/json`.

See [response 401 schema](#clients-mfa-assurance-set-response-401-schema).


### clients-mfa-assurance-set Response 404 schema

Content type: `application/json`.

See [response 401 schema](#clients-mfa-assurance-set-response-401-schema).


### clients-mfa-assurance-set Response 409 schema

Content type: `application/json`.

See [response 401 schema](#clients-mfa-assurance-set-response-401-schema).


### clients-mfa-assurance-set Response 500 schema

Content type: `application/json`.

See [response 401 schema](#clients-mfa-assurance-set-response-401-schema).


### clients-mfa-assurance-set Response 502 schema

Content type: `application/json`.

See [response 400 schema](#clients-mfa-assurance-set-response-400-schema).


### clients-mfa-assurance-set Response 503 schema

Content type: `application/json`.

See [response 400 schema](#clients-mfa-assurance-set-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "effective_mode": "mandatory",
    "own_mode": "mandatory",
    "owner": "scope",
    "scope_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "source_scope_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /enterprises/{enterprise_id}/mfa-assurance

**Read enterprise MFA policy**

Read the MFA assurance setting for this scope. Requires policies.read covering the target scope. own_mode is null when this scope inherits its policy; effective_mode and source_scope_ref describe the resolved policy. owner identifies a scope-owned or platform-owned local row and is null when no local row exists. With no setting in the lineage, effective_mode is optional and source_scope_ref is null. Platform human sessions always have a mandatory MFA floor independent of these enterprise/client settings.

**Required capability:** `policies.read`

**Authentication:** Bearer token required.

**Parameters:**

- `enterprise_id` `string` (path) *(required)*

### enterprises-mfa-assurance-get Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `effective_mode` | "optional" / "mandatory" | Yes |  |
| `own_mode` | "optional" / "mandatory" or null | Yes |  |
| `owner` | "scope" / "platform" or null | No |  |
| `scope_ref` | string or string | Yes |  |
| `source_scope_ref` | string or string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.own_mode

At least one alternative must match.

###### application/json body.own_mode: alternative 1

Type: `"optional" / "mandatory"`. 

###### application/json body.own_mode: alternative 2

Type: `null`. 

##### application/json body.owner

At least one alternative must match.

###### application/json body.owner: alternative 1

Type: `"scope" / "platform"`. 

###### application/json body.owner: alternative 2

Type: `null`. 

##### application/json body.scope_ref

At least one alternative must match.

###### application/json body.scope_ref: alternative 1

Type: `string`. pattern: `^(enterprises)\/([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})$`

###### application/json body.scope_ref: alternative 2

Type: `string`. pattern: `^(clients)\/([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})$`

##### application/json body.source_scope_ref

At least one alternative must match.

###### application/json body.source_scope_ref: alternative 1

At least one alternative must match.

###### application/json body.source_scope_ref: alternative 1: alternative 1

Type: `string`. pattern: `^(enterprises)\/([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})$`

###### application/json body.source_scope_ref: alternative 1: alternative 2

Type: `string`. pattern: `^(clients)\/([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})$`

###### application/json body.source_scope_ref: alternative 2

Type: `null`.


### enterprises-mfa-assurance-get 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.


### enterprises-mfa-assurance-get Response 401 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.


### enterprises-mfa-assurance-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-mfa-assurance-get-response-401-schema).


### enterprises-mfa-assurance-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-mfa-assurance-get-response-401-schema).


### enterprises-mfa-assurance-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-mfa-assurance-get-response-401-schema).


### enterprises-mfa-assurance-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#enterprises-mfa-assurance-get-response-400-schema).


### enterprises-mfa-assurance-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#enterprises-mfa-assurance-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "effective_mode": "mandatory",
    "own_mode": "mandatory",
    "owner": "scope",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "source_scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### PUT /enterprises/{enterprise_id}/mfa-assurance

**Set enterprise MFA policy**

Requires both policies.manage and policies.read covering the target scope; the current setting is read for the audit diff before writing. Set mode to inherited to remove the scope setting. Setting optional beneath a mandatory ancestor returns HTTP 409 with data.reason=mfa_cannot_relax and data.resource naming that ancestor. A platform-owned setting may only be changed by platform staff with platform-wide policies.manage authority; other callers receive HTTP 403 with data.reason=mfa_setting_platform_owned. The required reason is trimmed and must contain 3 to 500 characters for the audit record. This changes the assurance policy; it does not enroll or remove an authentication factor.

**Required capability:** `policies.manage`, `policies.read`

**Authentication:** Bearer token required.

**Parameters:**

- `enterprise_id` `string` (path) *(required)*

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `mode` | "inherited" or "optional" / "mandatory" | Yes |  |
| `reason` | string | Yes | minLength: 3; maxLength: 500 |

Additional fields are not accepted.

#### Request body schema.mode

At least one alternative must match.

##### Request body schema.mode: alternative 1

Type: `"inherited"`. 

##### Request body schema.mode: alternative 2

Type: `"optional" / "mandatory"`.

**Request example:**

```json
{
  "mode": "mandatory",
  "reason": "Require fresh authentication for protected actions"
}
```

### enterprises-mfa-assurance-set Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `effective_mode` | "optional" / "mandatory" | Yes |  |
| `own_mode` | "optional" / "mandatory" or null | Yes |  |
| `owner` | "scope" / "platform" or null | No |  |
| `scope_ref` | string or string | Yes |  |
| `source_scope_ref` | string or string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.own_mode

At least one alternative must match.

###### application/json body.own_mode: alternative 1

Type: `"optional" / "mandatory"`. 

###### application/json body.own_mode: alternative 2

Type: `null`. 

##### application/json body.owner

At least one alternative must match.

###### application/json body.owner: alternative 1

Type: `"scope" / "platform"`. 

###### application/json body.owner: alternative 2

Type: `null`. 

##### application/json body.scope_ref

At least one alternative must match.

###### application/json body.scope_ref: alternative 1

Type: `string`. pattern: `^(enterprises)\/([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})$`

###### application/json body.scope_ref: alternative 2

Type: `string`. pattern: `^(clients)\/([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})$`

##### application/json body.source_scope_ref

At least one alternative must match.

###### application/json body.source_scope_ref: alternative 1

At least one alternative must match.

###### application/json body.source_scope_ref: alternative 1: alternative 1

Type: `string`. pattern: `^(enterprises)\/([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})$`

###### application/json body.source_scope_ref: alternative 1: alternative 2

Type: `string`. pattern: `^(clients)\/([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})$`

###### application/json body.source_scope_ref: alternative 2

Type: `null`.


### enterprises-mfa-assurance-set 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.


### enterprises-mfa-assurance-set Response 401 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.


### enterprises-mfa-assurance-set Response 403 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-mfa-assurance-set-response-401-schema).


### enterprises-mfa-assurance-set Response 404 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-mfa-assurance-set-response-401-schema).


### enterprises-mfa-assurance-set Response 409 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-mfa-assurance-set-response-401-schema).


### enterprises-mfa-assurance-set Response 500 schema

Content type: `application/json`.

See [response 401 schema](#enterprises-mfa-assurance-set-response-401-schema).


### enterprises-mfa-assurance-set Response 502 schema

Content type: `application/json`.

See [response 400 schema](#enterprises-mfa-assurance-set-response-400-schema).


### enterprises-mfa-assurance-set Response 503 schema

Content type: `application/json`.

See [response 400 schema](#enterprises-mfa-assurance-set-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "effective_mode": "mandatory",
    "own_mode": "mandatory",
    "owner": "scope",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "source_scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /policy-rules

**List policy rules**

Lists visible policy rules. Filter by governed scope, operation type or status; repeat status_filter to select several lifecycle states. Draft rules are authoring resources; only active rules participate in policy evaluation.

**Required capability:** `policies.read`

**Authentication:** Bearer token required.

**Parameters:**

- `scope_ref` `string` (query)
- `operation_type` `string` (query)
- `status_filter` `string` (query)
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### policy-rules-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1 |
| `description` | string or null | Yes |  |
| `activated_at` | string or string or null | Yes |  |
| `conditions` | object or object or object or object or object or object[] | Yes |  |
| `created_at` | string or string | Yes |  |
| `decision` | object or object or object | Yes |  |
| `etag` | string | Yes | minLength: 1 |
| `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)$` |
| `operation_type` | "withdrawal" / "conversion" / "external_settlement_conversion" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension" | Yes |  |
| `resource` | "policy_rule" | Yes |  |
| `retired_at` | string or string or null | Yes |  |
| `scope_ref` | string or string | Yes |  |
| `status` | "draft" / "active" / "retired" | Yes |  |
| `updated_at` | string or string | Yes |  |
| `version` | integer | Yes | maximum: 9007199254740991; exclusiveMinimum: 0 |

Additional fields are not accepted.

###### application/json body.items item.description

At least one alternative must match.

###### application/json body.items item.description: alternative 1

Type: `string`. minLength: 1

###### application/json body.items item.description: alternative 2

Type: `null`. 

###### application/json body.items item.activated_at

At least one alternative must match.

###### application/json body.items item.activated_at: alternative 1

At least one alternative must match.

###### application/json body.items item.activated_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.activated_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.activated_at: alternative 2

Type: `null`. 

###### application/json body.items item.conditions

Type: `object or object or object or object or object or object[]`. 

###### application/json body.items item.conditions item

Exactly one alternative must match.

###### application/json body.items item.conditions item: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount_basis` | "native_amount" / "usd_equivalent" | Yes |  |
| `kind` | "amount_threshold" | Yes |  |
| `operator` | "gt" / "gte" / "lt" / "lte" | Yes |  |
| `threshold` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.items item.conditions item: alternative 1.threshold

| 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.

###### application/json body.items item.conditions item: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset_class` | "fiat" / "crypto" | Yes |  |
| `asset_role` | "principal" / "source" / "target" | Yes |  |
| `kind` | "asset_class" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.conditions item: alternative 3

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset_code` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `asset_role` | "principal" / "source" / "target" | Yes |  |
| `kind` | "asset" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.conditions item: alternative 4

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `direction` | "master_to_client" / "client_to_master" / "client_to_client" | Yes |  |
| `kind` | "direction" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.conditions item: alternative 5

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `initiator_ref` | string | Yes | pattern: `^(users\|service-accounts\|platform-principals)\/([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})$` |
| `kind` | "initiator" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.conditions item: alternative 6

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "conversion_asset_class_pair" | Yes |  |
| `source_asset_class` | "fiat" / "crypto" | Yes |  |
| `target_asset_class` | "fiat" / "crypto" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.created_at

At least one alternative must match.

###### application/json body.items item.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.created_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.decision

Exactly one alternative must match.

###### application/json body.items item.decision: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "allow" | Yes |  |
| `reason` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.decision: alternative 1.reason

At least one alternative must match.

###### application/json body.items item.decision: alternative 1.reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.items item.decision: alternative 1.reason: alternative 2

Type: `null`. 

###### application/json body.items item.decision: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "deny" | Yes |  |
| `reason` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.items item.decision: alternative 3

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approver_role_ref` | string or null | No |  |
| `initiator_cannot_approve` | boolean | Yes |  |
| `kind` | "require_approval" | Yes |  |
| `reason` | string | Yes | minLength: 1 |
| `threshold` | integer | Yes | maximum: 9007199254740991; exclusiveMinimum: 0 |

Additional fields are not accepted.

###### application/json body.items item.decision: alternative 3.approver_role_ref

At least one alternative must match.

###### application/json body.items item.decision: alternative 3.approver_role_ref: alternative 1

Type: `string`. pattern: `^(roles)\/([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})$`

###### application/json body.items item.decision: alternative 3.approver_role_ref: alternative 2

Type: `null`. 

###### application/json body.items item.retired_at

At least one alternative must match.

###### application/json body.items item.retired_at: alternative 1

At least one alternative must match.

###### application/json body.items item.retired_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.retired_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.retired_at: alternative 2

Type: `null`. 

###### application/json body.items item.scope_ref

At least one alternative must match.

###### application/json body.items item.scope_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.scope_ref: alternative 2

Type: `string`. 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})$`

###### application/json body.items item.updated_at

At least one alternative must match.

###### application/json body.items item.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.updated_at: alternative 2

Type: `string`. format: date-time

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. 

###### application/json body.next_page_token: alternative 2

Type: `null`.


### policy-rules-list 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.


### policy-rules-list Response 401 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.


### policy-rules-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#policy-rules-list-response-401-schema).


### policy-rules-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#policy-rules-list-response-401-schema).


### policy-rules-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#policy-rules-list-response-400-schema).


### policy-rules-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#policy-rules-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "name": "Large crypto withdrawal approval",
        "description": "Require compliance review for large crypto withdrawals",
        "activated_at": "2026-05-01T10:00:00Z",
        "conditions": [
          {
            "amount_basis": "usd_equivalent",
            "kind": "amount_threshold",
            "operator": "gte",
            "threshold": {
              "currency": "USD",
              "value": "10000.00"
            }
          },
          {
            "asset_class": "crypto",
            "asset_role": "principal",
            "kind": "asset_class"
          }
        ],
        "created_at": "2026-05-01T10:00:00Z",
        "decision": {
          "approver_role_ref": "roles/44444444-4444-4444-8444-444444444444",
          "initiator_cannot_approve": true,
          "kind": "require_approval",
          "reason": "large_crypto_withdrawal",
          "threshold": 2
        },
        "etag": "policy-rule-v2-0001",
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "operation_type": "withdrawal",
        "resource": "policy_rule",
        "retired_at": null,
        "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "status": "active",
        "updated_at": "2026-05-01T10:00:00Z",
        "version": 1
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /policy-rules

**Create policy rule**

Creates a draft rule under the governed scope. Creating a rule does not enforce it: activate the draft separately after authoring. Supply Idempotency-Key for replay-safe creation; it takes precedence over body idempotency_key. When neither is supplied, edge generates a key and a repeated request creates a new rule. A replay with the same Idempotency-Key header returns the original 201 response and original etag. A body-only idempotency_key replay returns the existing rule in its current lifecycle state. Re-read the rule before a later lifecycle action.

**Required capability:** `policies.create`

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1 |
| `description` | string or null | No |  |
| `conditions` | object or object or object or object or object or object[] | Yes |  |
| `decision` | object or object or object | Yes |  |
| `idempotency_key` | string | No | minLength: 1; maxLength: 128 |
| `operation_type` | "withdrawal" / "conversion" / "external_settlement_conversion" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension" | Yes |  |
| `scope_ref` | string or string | Yes |  |

Additional fields are not accepted.

#### Request body schema.description

At least one alternative must match.

##### Request body schema.description: alternative 1

Type: `string`. minLength: 1

##### Request body schema.description: alternative 2

Type: `null`. 

#### Request body schema.conditions

Type: `object or object or object or object or object or object[]`. 

##### Request body schema.conditions item

Exactly one alternative must match.

###### Request body schema.conditions item: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount_basis` | "native_amount" / "usd_equivalent" | Yes |  |
| `kind` | "amount_threshold" | Yes |  |
| `operator` | "gt" / "gte" / "lt" / "lte" | Yes |  |
| `threshold` | object | Yes | No additional fields |

Additional fields are not accepted.

###### Request body schema.conditions item: alternative 1.threshold

| 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.conditions item: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset_class` | "fiat" / "crypto" | Yes |  |
| `asset_role` | "principal" / "source" / "target" | Yes |  |
| `kind` | "asset_class" | Yes |  |

Additional fields are not accepted.

###### Request body schema.conditions item: alternative 3

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset_code` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `asset_role` | "principal" / "source" / "target" | Yes |  |
| `kind` | "asset" | Yes |  |

Additional fields are not accepted.

###### Request body schema.conditions item: alternative 4

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `direction` | "master_to_client" / "client_to_master" / "client_to_client" | Yes |  |
| `kind` | "direction" | Yes |  |

Additional fields are not accepted.

###### Request body schema.conditions item: alternative 5

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `initiator_ref` | string | Yes | pattern: `^(users\|service-accounts\|platform-principals)\/([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})$` |
| `kind` | "initiator" | Yes |  |

Additional fields are not accepted.

###### Request body schema.conditions item: alternative 6

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "conversion_asset_class_pair" | Yes |  |
| `source_asset_class` | "fiat" / "crypto" | Yes |  |
| `target_asset_class` | "fiat" / "crypto" | Yes |  |

Additional fields are not accepted.

#### Request body schema.decision

Exactly one alternative must match.

##### Request body schema.decision: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "allow" | Yes |  |
| `reason` | string or null | No |  |

Additional fields are not accepted.

###### Request body schema.decision: alternative 1.reason

At least one alternative must match.

###### Request body schema.decision: alternative 1.reason: alternative 1

Type: `string`. minLength: 1

###### Request body schema.decision: alternative 1.reason: alternative 2

Type: `null`. 

##### Request body schema.decision: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "deny" | Yes |  |
| `reason` | string | Yes | minLength: 1 |

Additional fields are not accepted.

##### Request body schema.decision: alternative 3

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approver_role_ref` | string or null | No |  |
| `initiator_cannot_approve` | boolean | Yes |  |
| `kind` | "require_approval" | Yes |  |
| `reason` | string | Yes | minLength: 1 |
| `threshold` | integer | Yes | maximum: 9007199254740991; exclusiveMinimum: 0 |

Additional fields are not accepted.

###### Request body schema.decision: alternative 3.approver_role_ref

At least one alternative must match.

###### Request body schema.decision: alternative 3.approver_role_ref: alternative 1

Type: `string`. pattern: `^(roles)\/([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})$`

###### Request body schema.decision: alternative 3.approver_role_ref: alternative 2

Type: `null`. 

#### Request body schema.scope_ref

At least one alternative must match.

##### Request body schema.scope_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

##### Request body schema.scope_ref: alternative 2

Type: `string`. 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})$`

**Request example:**

```json
{
  "name": "Large crypto withdrawal approval",
  "description": "Require compliance review for large crypto withdrawals",
  "conditions": [
    {
      "amount_basis": "usd_equivalent",
      "kind": "amount_threshold",
      "operator": "gte",
      "threshold": {
        "currency": "USD",
        "value": "10000.00"
      }
    },
    {
      "asset_class": "crypto",
      "asset_role": "principal",
      "kind": "asset_class"
    }
  ],
  "decision": {
    "approver_role_ref": "roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "initiator_cannot_approve": true,
    "kind": "require_approval",
    "reason": "large_crypto_withdrawal",
    "threshold": 2
  },
  "operation_type": "withdrawal",
  "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}
```

### policy-rules-create Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1 |
| `description` | string or null | Yes |  |
| `activated_at` | string or string or null | Yes |  |
| `conditions` | object or object or object or object or object or object[] | Yes |  |
| `created_at` | string or string | Yes |  |
| `decision` | object or object or object | Yes |  |
| `etag` | string | Yes | minLength: 1 |
| `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)$` |
| `operation_type` | "withdrawal" / "conversion" / "external_settlement_conversion" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension" | Yes |  |
| `resource` | "policy_rule" | Yes |  |
| `retired_at` | string or string or null | Yes |  |
| `scope_ref` | string or string | Yes |  |
| `status` | "draft" / "active" / "retired" | Yes |  |
| `updated_at` | string or string | Yes |  |
| `version` | integer | Yes | maximum: 9007199254740991; exclusiveMinimum: 0 |

Additional fields are not accepted.

##### application/json body.description

At least one alternative must match.

###### application/json body.description: alternative 1

Type: `string`. minLength: 1

###### application/json body.description: alternative 2

Type: `null`. 

##### application/json body.activated_at

At least one alternative must match.

###### application/json body.activated_at: alternative 1

At least one alternative must match.

###### application/json body.activated_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.activated_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.activated_at: alternative 2

Type: `null`. 

##### application/json body.conditions

Type: `object or object or object or object or object or object[]`. 

###### application/json body.conditions item

Exactly one alternative must match.

###### application/json body.conditions item: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount_basis` | "native_amount" / "usd_equivalent" | Yes |  |
| `kind` | "amount_threshold" | Yes |  |
| `operator` | "gt" / "gte" / "lt" / "lte" | Yes |  |
| `threshold` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.conditions item: alternative 1.threshold

| 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.

###### application/json body.conditions item: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset_class` | "fiat" / "crypto" | Yes |  |
| `asset_role` | "principal" / "source" / "target" | Yes |  |
| `kind` | "asset_class" | Yes |  |

Additional fields are not accepted.

###### application/json body.conditions item: alternative 3

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset_code` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `asset_role` | "principal" / "source" / "target" | Yes |  |
| `kind` | "asset" | Yes |  |

Additional fields are not accepted.

###### application/json body.conditions item: alternative 4

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `direction` | "master_to_client" / "client_to_master" / "client_to_client" | Yes |  |
| `kind` | "direction" | Yes |  |

Additional fields are not accepted.

###### application/json body.conditions item: alternative 5

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `initiator_ref` | string | Yes | pattern: `^(users\|service-accounts\|platform-principals)\/([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})$` |
| `kind` | "initiator" | Yes |  |

Additional fields are not accepted.

###### application/json body.conditions item: alternative 6

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "conversion_asset_class_pair" | Yes |  |
| `source_asset_class` | "fiat" / "crypto" | Yes |  |
| `target_asset_class` | "fiat" / "crypto" | Yes |  |

Additional fields are not accepted.

##### application/json body.created_at

At least one alternative must match.

###### application/json body.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.created_at: alternative 2

Type: `string`. format: date-time

##### application/json body.decision

Exactly one alternative must match.

###### application/json body.decision: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "allow" | Yes |  |
| `reason` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.reason

At least one alternative must match.

###### application/json body.decision: alternative 1.reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.decision: alternative 1.reason: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "deny" | Yes |  |
| `reason` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.decision: alternative 3

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approver_role_ref` | string or null | No |  |
| `initiator_cannot_approve` | boolean | Yes |  |
| `kind` | "require_approval" | Yes |  |
| `reason` | string | Yes | minLength: 1 |
| `threshold` | integer | Yes | maximum: 9007199254740991; exclusiveMinimum: 0 |

Additional fields are not accepted.

###### application/json body.decision: alternative 3.approver_role_ref

At least one alternative must match.

###### application/json body.decision: alternative 3.approver_role_ref: alternative 1

Type: `string`. pattern: `^(roles)\/([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})$`

###### application/json body.decision: alternative 3.approver_role_ref: alternative 2

Type: `null`. 

##### application/json body.retired_at

At least one alternative must match.

###### application/json body.retired_at: alternative 1

At least one alternative must match.

###### application/json body.retired_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.retired_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.retired_at: alternative 2

Type: `null`. 

##### application/json body.scope_ref

At least one alternative must match.

###### application/json body.scope_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.scope_ref: alternative 2

Type: `string`. 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})$`

##### application/json body.updated_at

At least one alternative must match.

###### application/json body.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.updated_at: alternative 2

Type: `string`. format: date-time


### policy-rules-create 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.


### policy-rules-create Response 401 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.


### policy-rules-create Response 403 schema

Content type: `application/json`.

See [response 401 schema](#policy-rules-create-response-401-schema).


### policy-rules-create Response 409 schema

Content type: `application/json`.

See [response 401 schema](#policy-rules-create-response-401-schema).


### policy-rules-create Response 500 schema

Content type: `application/json`.

See [response 401 schema](#policy-rules-create-response-401-schema).


### policy-rules-create Response 502 schema

Content type: `application/json`.

See [response 400 schema](#policy-rules-create-response-400-schema).


### policy-rules-create Response 503 schema

Content type: `application/json`.

See [response 400 schema](#policy-rules-create-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "name": "Large crypto withdrawal approval",
    "description": "Require compliance review for large crypto withdrawals",
    "activated_at": null,
    "conditions": [
      {
        "amount_basis": "usd_equivalent",
        "kind": "amount_threshold",
        "operator": "gte",
        "threshold": {
          "currency": "USD",
          "value": "10000.00"
        }
      },
      {
        "asset_class": "crypto",
        "asset_role": "principal",
        "kind": "asset_class"
      }
    ],
    "created_at": "2026-05-01T10:00:00Z",
    "decision": {
      "approver_role_ref": "roles/44444444-4444-4444-8444-444444444444",
      "initiator_cannot_approve": true,
      "kind": "require_approval",
      "reason": "large_crypto_withdrawal",
      "threshold": 2
    },
    "etag": "policy-rule-v2-0001",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "operation_type": "withdrawal",
    "resource": "policy_rule",
    "retired_at": null,
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "draft",
    "updated_at": "2026-05-01T10:00:00Z",
    "version": 1
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /policy-rules/{rule_id}

**Get policy rule**

Reads a visible policy rule. Use its ETag response header or etag body field as If-Match when updating, activating or retiring the rule.

**Required capability:** `policies.read`

**Authentication:** Bearer token required.

**Parameters:**

- `rule_id` `string` (path) *(required)*

### policy-rules-get Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1 |
| `description` | string or null | Yes |  |
| `activated_at` | string or string or null | Yes |  |
| `conditions` | object or object or object or object or object or object[] | Yes |  |
| `created_at` | string or string | Yes |  |
| `decision` | object or object or object | Yes |  |
| `etag` | string | Yes | minLength: 1 |
| `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)$` |
| `operation_type` | "withdrawal" / "conversion" / "external_settlement_conversion" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension" | Yes |  |
| `resource` | "policy_rule" | Yes |  |
| `retired_at` | string or string or null | Yes |  |
| `scope_ref` | string or string | Yes |  |
| `status` | "draft" / "active" / "retired" | Yes |  |
| `updated_at` | string or string | Yes |  |
| `version` | integer | Yes | maximum: 9007199254740991; exclusiveMinimum: 0 |

Additional fields are not accepted.

##### application/json body.description

At least one alternative must match.

###### application/json body.description: alternative 1

Type: `string`. minLength: 1

###### application/json body.description: alternative 2

Type: `null`. 

##### application/json body.activated_at

At least one alternative must match.

###### application/json body.activated_at: alternative 1

At least one alternative must match.

###### application/json body.activated_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.activated_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.activated_at: alternative 2

Type: `null`. 

##### application/json body.conditions

Type: `object or object or object or object or object or object[]`. 

###### application/json body.conditions item

Exactly one alternative must match.

###### application/json body.conditions item: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount_basis` | "native_amount" / "usd_equivalent" | Yes |  |
| `kind` | "amount_threshold" | Yes |  |
| `operator` | "gt" / "gte" / "lt" / "lte" | Yes |  |
| `threshold` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.conditions item: alternative 1.threshold

| 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.

###### application/json body.conditions item: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset_class` | "fiat" / "crypto" | Yes |  |
| `asset_role` | "principal" / "source" / "target" | Yes |  |
| `kind` | "asset_class" | Yes |  |

Additional fields are not accepted.

###### application/json body.conditions item: alternative 3

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset_code` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `asset_role` | "principal" / "source" / "target" | Yes |  |
| `kind` | "asset" | Yes |  |

Additional fields are not accepted.

###### application/json body.conditions item: alternative 4

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `direction` | "master_to_client" / "client_to_master" / "client_to_client" | Yes |  |
| `kind` | "direction" | Yes |  |

Additional fields are not accepted.

###### application/json body.conditions item: alternative 5

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `initiator_ref` | string | Yes | pattern: `^(users\|service-accounts\|platform-principals)\/([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})$` |
| `kind` | "initiator" | Yes |  |

Additional fields are not accepted.

###### application/json body.conditions item: alternative 6

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "conversion_asset_class_pair" | Yes |  |
| `source_asset_class` | "fiat" / "crypto" | Yes |  |
| `target_asset_class` | "fiat" / "crypto" | Yes |  |

Additional fields are not accepted.

##### application/json body.created_at

At least one alternative must match.

###### application/json body.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.created_at: alternative 2

Type: `string`. format: date-time

##### application/json body.decision

Exactly one alternative must match.

###### application/json body.decision: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "allow" | Yes |  |
| `reason` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.reason

At least one alternative must match.

###### application/json body.decision: alternative 1.reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.decision: alternative 1.reason: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "deny" | Yes |  |
| `reason` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.decision: alternative 3

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approver_role_ref` | string or null | No |  |
| `initiator_cannot_approve` | boolean | Yes |  |
| `kind` | "require_approval" | Yes |  |
| `reason` | string | Yes | minLength: 1 |
| `threshold` | integer | Yes | maximum: 9007199254740991; exclusiveMinimum: 0 |

Additional fields are not accepted.

###### application/json body.decision: alternative 3.approver_role_ref

At least one alternative must match.

###### application/json body.decision: alternative 3.approver_role_ref: alternative 1

Type: `string`. pattern: `^(roles)\/([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})$`

###### application/json body.decision: alternative 3.approver_role_ref: alternative 2

Type: `null`. 

##### application/json body.retired_at

At least one alternative must match.

###### application/json body.retired_at: alternative 1

At least one alternative must match.

###### application/json body.retired_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.retired_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.retired_at: alternative 2

Type: `null`. 

##### application/json body.scope_ref

At least one alternative must match.

###### application/json body.scope_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.scope_ref: alternative 2

Type: `string`. 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})$`

##### application/json body.updated_at

At least one alternative must match.

###### application/json body.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.updated_at: alternative 2

Type: `string`. format: date-time


### policy-rules-get 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.


### policy-rules-get Response 401 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.


### policy-rules-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#policy-rules-get-response-401-schema).


### policy-rules-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#policy-rules-get-response-401-schema).


### policy-rules-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#policy-rules-get-response-401-schema).


### policy-rules-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#policy-rules-get-response-400-schema).


### policy-rules-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#policy-rules-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "name": "Large crypto withdrawal approval",
    "description": "Require compliance review for large crypto withdrawals",
    "activated_at": "2026-05-01T10:00:00Z",
    "conditions": [
      {
        "amount_basis": "usd_equivalent",
        "kind": "amount_threshold",
        "operator": "gte",
        "threshold": {
          "currency": "USD",
          "value": "10000.00"
        }
      },
      {
        "asset_class": "crypto",
        "asset_role": "principal",
        "kind": "asset_class"
      }
    ],
    "created_at": "2026-05-01T10:00:00Z",
    "decision": {
      "approver_role_ref": "roles/44444444-4444-4444-8444-444444444444",
      "initiator_cannot_approve": true,
      "kind": "require_approval",
      "reason": "large_crypto_withdrawal",
      "threshold": 2
    },
    "etag": "policy-rule-v2-0001",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "operation_type": "withdrawal",
    "resource": "policy_rule",
    "retired_at": null,
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z",
    "version": 1
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### PATCH /policy-rules/{rule_id}

**Update policy rule**

Updates authoring fields on a draft rule. Active and retired rules cannot be edited. If-Match is required and must match the current rule etag; stale values are refused. Only supplied fields change, and description may be null.

**Required capability:** `policies.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `rule_id` `string` (path) *(required)*
- `If-Match` `string` (header) *(required)* — Weak entity tag from a prior GET. Mismatch causes the request to fail with 412 Precondition Failed.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | No | minLength: 1 |
| `description` | string or null | No |  |
| `conditions` | object or object or object or object or object or object[] | No |  |
| `decision` | object or object or object | No |  |
| `operation_type` | "withdrawal" / "conversion" / "external_settlement_conversion" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension" | No |  |
| `scope_ref` | string or string | No |  |

Additional fields are not accepted.

#### Request body schema.description

At least one alternative must match.

##### Request body schema.description: alternative 1

Type: `string`. minLength: 1

##### Request body schema.description: alternative 2

Type: `null`. 

#### Request body schema.conditions

Type: `object or object or object or object or object or object[]`. 

##### Request body schema.conditions item

Exactly one alternative must match.

###### Request body schema.conditions item: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount_basis` | "native_amount" / "usd_equivalent" | Yes |  |
| `kind` | "amount_threshold" | Yes |  |
| `operator` | "gt" / "gte" / "lt" / "lte" | Yes |  |
| `threshold` | object | Yes | No additional fields |

Additional fields are not accepted.

###### Request body schema.conditions item: alternative 1.threshold

| 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.conditions item: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset_class` | "fiat" / "crypto" | Yes |  |
| `asset_role` | "principal" / "source" / "target" | Yes |  |
| `kind` | "asset_class" | Yes |  |

Additional fields are not accepted.

###### Request body schema.conditions item: alternative 3

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset_code` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `asset_role` | "principal" / "source" / "target" | Yes |  |
| `kind` | "asset" | Yes |  |

Additional fields are not accepted.

###### Request body schema.conditions item: alternative 4

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `direction` | "master_to_client" / "client_to_master" / "client_to_client" | Yes |  |
| `kind` | "direction" | Yes |  |

Additional fields are not accepted.

###### Request body schema.conditions item: alternative 5

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `initiator_ref` | string | Yes | pattern: `^(users\|service-accounts\|platform-principals)\/([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})$` |
| `kind` | "initiator" | Yes |  |

Additional fields are not accepted.

###### Request body schema.conditions item: alternative 6

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "conversion_asset_class_pair" | Yes |  |
| `source_asset_class` | "fiat" / "crypto" | Yes |  |
| `target_asset_class` | "fiat" / "crypto" | Yes |  |

Additional fields are not accepted.

#### Request body schema.decision

Exactly one alternative must match.

##### Request body schema.decision: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "allow" | Yes |  |
| `reason` | string or null | No |  |

Additional fields are not accepted.

###### Request body schema.decision: alternative 1.reason

At least one alternative must match.

###### Request body schema.decision: alternative 1.reason: alternative 1

Type: `string`. minLength: 1

###### Request body schema.decision: alternative 1.reason: alternative 2

Type: `null`. 

##### Request body schema.decision: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "deny" | Yes |  |
| `reason` | string | Yes | minLength: 1 |

Additional fields are not accepted.

##### Request body schema.decision: alternative 3

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approver_role_ref` | string or null | No |  |
| `initiator_cannot_approve` | boolean | Yes |  |
| `kind` | "require_approval" | Yes |  |
| `reason` | string | Yes | minLength: 1 |
| `threshold` | integer | Yes | maximum: 9007199254740991; exclusiveMinimum: 0 |

Additional fields are not accepted.

###### Request body schema.decision: alternative 3.approver_role_ref

At least one alternative must match.

###### Request body schema.decision: alternative 3.approver_role_ref: alternative 1

Type: `string`. pattern: `^(roles)\/([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})$`

###### Request body schema.decision: alternative 3.approver_role_ref: alternative 2

Type: `null`. 

#### Request body schema.scope_ref

At least one alternative must match.

##### Request body schema.scope_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

##### Request body schema.scope_ref: alternative 2

Type: `string`. 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})$`

**Request example:**

```json
{
  "name": "Updated policy rule name"
}
```

### policy-rules-update Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1 |
| `description` | string or null | Yes |  |
| `activated_at` | string or string or null | Yes |  |
| `conditions` | object or object or object or object or object or object[] | Yes |  |
| `created_at` | string or string | Yes |  |
| `decision` | object or object or object | Yes |  |
| `etag` | string | Yes | minLength: 1 |
| `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)$` |
| `operation_type` | "withdrawal" / "conversion" / "external_settlement_conversion" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension" | Yes |  |
| `resource` | "policy_rule" | Yes |  |
| `retired_at` | string or string or null | Yes |  |
| `scope_ref` | string or string | Yes |  |
| `status` | "draft" / "active" / "retired" | Yes |  |
| `updated_at` | string or string | Yes |  |
| `version` | integer | Yes | maximum: 9007199254740991; exclusiveMinimum: 0 |

Additional fields are not accepted.

##### application/json body.description

At least one alternative must match.

###### application/json body.description: alternative 1

Type: `string`. minLength: 1

###### application/json body.description: alternative 2

Type: `null`. 

##### application/json body.activated_at

At least one alternative must match.

###### application/json body.activated_at: alternative 1

At least one alternative must match.

###### application/json body.activated_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.activated_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.activated_at: alternative 2

Type: `null`. 

##### application/json body.conditions

Type: `object or object or object or object or object or object[]`. 

###### application/json body.conditions item

Exactly one alternative must match.

###### application/json body.conditions item: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount_basis` | "native_amount" / "usd_equivalent" | Yes |  |
| `kind` | "amount_threshold" | Yes |  |
| `operator` | "gt" / "gte" / "lt" / "lte" | Yes |  |
| `threshold` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.conditions item: alternative 1.threshold

| 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.

###### application/json body.conditions item: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset_class` | "fiat" / "crypto" | Yes |  |
| `asset_role` | "principal" / "source" / "target" | Yes |  |
| `kind` | "asset_class" | Yes |  |

Additional fields are not accepted.

###### application/json body.conditions item: alternative 3

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset_code` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `asset_role` | "principal" / "source" / "target" | Yes |  |
| `kind` | "asset" | Yes |  |

Additional fields are not accepted.

###### application/json body.conditions item: alternative 4

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `direction` | "master_to_client" / "client_to_master" / "client_to_client" | Yes |  |
| `kind` | "direction" | Yes |  |

Additional fields are not accepted.

###### application/json body.conditions item: alternative 5

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `initiator_ref` | string | Yes | pattern: `^(users\|service-accounts\|platform-principals)\/([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})$` |
| `kind` | "initiator" | Yes |  |

Additional fields are not accepted.

###### application/json body.conditions item: alternative 6

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "conversion_asset_class_pair" | Yes |  |
| `source_asset_class` | "fiat" / "crypto" | Yes |  |
| `target_asset_class` | "fiat" / "crypto" | Yes |  |

Additional fields are not accepted.

##### application/json body.created_at

At least one alternative must match.

###### application/json body.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.created_at: alternative 2

Type: `string`. format: date-time

##### application/json body.decision

Exactly one alternative must match.

###### application/json body.decision: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "allow" | Yes |  |
| `reason` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.reason

At least one alternative must match.

###### application/json body.decision: alternative 1.reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.decision: alternative 1.reason: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "deny" | Yes |  |
| `reason` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.decision: alternative 3

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approver_role_ref` | string or null | No |  |
| `initiator_cannot_approve` | boolean | Yes |  |
| `kind` | "require_approval" | Yes |  |
| `reason` | string | Yes | minLength: 1 |
| `threshold` | integer | Yes | maximum: 9007199254740991; exclusiveMinimum: 0 |

Additional fields are not accepted.

###### application/json body.decision: alternative 3.approver_role_ref

At least one alternative must match.

###### application/json body.decision: alternative 3.approver_role_ref: alternative 1

Type: `string`. pattern: `^(roles)\/([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})$`

###### application/json body.decision: alternative 3.approver_role_ref: alternative 2

Type: `null`. 

##### application/json body.retired_at

At least one alternative must match.

###### application/json body.retired_at: alternative 1

At least one alternative must match.

###### application/json body.retired_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.retired_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.retired_at: alternative 2

Type: `null`. 

##### application/json body.scope_ref

At least one alternative must match.

###### application/json body.scope_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.scope_ref: alternative 2

Type: `string`. 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})$`

##### application/json body.updated_at

At least one alternative must match.

###### application/json body.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.updated_at: alternative 2

Type: `string`. format: date-time


### policy-rules-update 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.


### policy-rules-update Response 401 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.


### policy-rules-update Response 403 schema

Content type: `application/json`.

See [response 401 schema](#policy-rules-update-response-401-schema).


### policy-rules-update Response 404 schema

Content type: `application/json`.

See [response 401 schema](#policy-rules-update-response-401-schema).


### policy-rules-update Response 409 schema

Content type: `application/json`.

See [response 401 schema](#policy-rules-update-response-401-schema).


### policy-rules-update Response 412 schema

Content type: `application/json`.

See [response 401 schema](#policy-rules-update-response-401-schema).


### policy-rules-update Response 500 schema

Content type: `application/json`.

See [response 401 schema](#policy-rules-update-response-401-schema).


### policy-rules-update Response 502 schema

Content type: `application/json`.

See [response 400 schema](#policy-rules-update-response-400-schema).


### policy-rules-update Response 503 schema

Content type: `application/json`.

See [response 400 schema](#policy-rules-update-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "name": "Large crypto withdrawal approval",
    "description": "Require compliance review for large crypto withdrawals",
    "activated_at": null,
    "conditions": [
      {
        "amount_basis": "usd_equivalent",
        "kind": "amount_threshold",
        "operator": "gte",
        "threshold": {
          "currency": "USD",
          "value": "10000.00"
        }
      },
      {
        "asset_class": "crypto",
        "asset_role": "principal",
        "kind": "asset_class"
      }
    ],
    "created_at": "2026-05-01T10:00:00Z",
    "decision": {
      "approver_role_ref": "roles/44444444-4444-4444-8444-444444444444",
      "initiator_cannot_approve": true,
      "kind": "require_approval",
      "reason": "large_crypto_withdrawal",
      "threshold": 2
    },
    "etag": "policy-rule-v2-0001",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "operation_type": "withdrawal",
    "resource": "policy_rule",
    "retired_at": null,
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "draft",
    "updated_at": "2026-05-01T10:00:00Z",
    "version": 1
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `412` — If-Match check failed; the resource has changed since the cached etag.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /policy-rules/{rule_id}/activate

**Activate policy rule**

Validates a draft and activates it for policy evaluation. If-Match must match the current rule etag. A named approver role must be active, lie within the governed perimeter and permit approval decisions; omitting the role leaves eligible approvers to the governed perimeter. Only draft rules can be activated.

**Required capability:** `policies.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `rule_id` `string` (path) *(required)*
- `If-Match` `string` (header) *(required)* — Weak entity tag from a prior GET. Mismatch causes the request to fail with 412 Precondition Failed.
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

### policy-rules-activate Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1 |
| `description` | string or null | Yes |  |
| `activated_at` | string or string or null | Yes |  |
| `conditions` | object or object or object or object or object or object[] | Yes |  |
| `created_at` | string or string | Yes |  |
| `decision` | object or object or object | Yes |  |
| `etag` | string | Yes | minLength: 1 |
| `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)$` |
| `operation_type` | "withdrawal" / "conversion" / "external_settlement_conversion" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension" | Yes |  |
| `resource` | "policy_rule" | Yes |  |
| `retired_at` | string or string or null | Yes |  |
| `scope_ref` | string or string | Yes |  |
| `status` | "draft" / "active" / "retired" | Yes |  |
| `updated_at` | string or string | Yes |  |
| `version` | integer | Yes | maximum: 9007199254740991; exclusiveMinimum: 0 |

Additional fields are not accepted.

##### application/json body.description

At least one alternative must match.

###### application/json body.description: alternative 1

Type: `string`. minLength: 1

###### application/json body.description: alternative 2

Type: `null`. 

##### application/json body.activated_at

At least one alternative must match.

###### application/json body.activated_at: alternative 1

At least one alternative must match.

###### application/json body.activated_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.activated_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.activated_at: alternative 2

Type: `null`. 

##### application/json body.conditions

Type: `object or object or object or object or object or object[]`. 

###### application/json body.conditions item

Exactly one alternative must match.

###### application/json body.conditions item: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount_basis` | "native_amount" / "usd_equivalent" | Yes |  |
| `kind` | "amount_threshold" | Yes |  |
| `operator` | "gt" / "gte" / "lt" / "lte" | Yes |  |
| `threshold` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.conditions item: alternative 1.threshold

| 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.

###### application/json body.conditions item: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset_class` | "fiat" / "crypto" | Yes |  |
| `asset_role` | "principal" / "source" / "target" | Yes |  |
| `kind` | "asset_class" | Yes |  |

Additional fields are not accepted.

###### application/json body.conditions item: alternative 3

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset_code` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `asset_role` | "principal" / "source" / "target" | Yes |  |
| `kind` | "asset" | Yes |  |

Additional fields are not accepted.

###### application/json body.conditions item: alternative 4

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `direction` | "master_to_client" / "client_to_master" / "client_to_client" | Yes |  |
| `kind` | "direction" | Yes |  |

Additional fields are not accepted.

###### application/json body.conditions item: alternative 5

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `initiator_ref` | string | Yes | pattern: `^(users\|service-accounts\|platform-principals)\/([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})$` |
| `kind` | "initiator" | Yes |  |

Additional fields are not accepted.

###### application/json body.conditions item: alternative 6

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "conversion_asset_class_pair" | Yes |  |
| `source_asset_class` | "fiat" / "crypto" | Yes |  |
| `target_asset_class` | "fiat" / "crypto" | Yes |  |

Additional fields are not accepted.

##### application/json body.created_at

At least one alternative must match.

###### application/json body.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.created_at: alternative 2

Type: `string`. format: date-time

##### application/json body.decision

Exactly one alternative must match.

###### application/json body.decision: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "allow" | Yes |  |
| `reason` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.reason

At least one alternative must match.

###### application/json body.decision: alternative 1.reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.decision: alternative 1.reason: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "deny" | Yes |  |
| `reason` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.decision: alternative 3

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approver_role_ref` | string or null | No |  |
| `initiator_cannot_approve` | boolean | Yes |  |
| `kind` | "require_approval" | Yes |  |
| `reason` | string | Yes | minLength: 1 |
| `threshold` | integer | Yes | maximum: 9007199254740991; exclusiveMinimum: 0 |

Additional fields are not accepted.

###### application/json body.decision: alternative 3.approver_role_ref

At least one alternative must match.

###### application/json body.decision: alternative 3.approver_role_ref: alternative 1

Type: `string`. pattern: `^(roles)\/([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})$`

###### application/json body.decision: alternative 3.approver_role_ref: alternative 2

Type: `null`. 

##### application/json body.retired_at

At least one alternative must match.

###### application/json body.retired_at: alternative 1

At least one alternative must match.

###### application/json body.retired_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.retired_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.retired_at: alternative 2

Type: `null`. 

##### application/json body.scope_ref

At least one alternative must match.

###### application/json body.scope_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.scope_ref: alternative 2

Type: `string`. 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})$`

##### application/json body.updated_at

At least one alternative must match.

###### application/json body.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.updated_at: alternative 2

Type: `string`. format: date-time


### policy-rules-activate 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.


### policy-rules-activate Response 401 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.


### policy-rules-activate Response 403 schema

Content type: `application/json`.

See [response 401 schema](#policy-rules-activate-response-401-schema).


### policy-rules-activate Response 404 schema

Content type: `application/json`.

See [response 401 schema](#policy-rules-activate-response-401-schema).


### policy-rules-activate Response 409 schema

Content type: `application/json`.

See [response 401 schema](#policy-rules-activate-response-401-schema).


### policy-rules-activate Response 412 schema

Content type: `application/json`.

See [response 401 schema](#policy-rules-activate-response-401-schema).


### policy-rules-activate Response 500 schema

Content type: `application/json`.

See [response 401 schema](#policy-rules-activate-response-401-schema).


### policy-rules-activate Response 502 schema

Content type: `application/json`.

See [response 400 schema](#policy-rules-activate-response-400-schema).


### policy-rules-activate Response 503 schema

Content type: `application/json`.

See [response 400 schema](#policy-rules-activate-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "name": "Large crypto withdrawal approval",
    "description": "Require compliance review for large crypto withdrawals",
    "activated_at": "2026-05-01T10:00:00Z",
    "conditions": [
      {
        "amount_basis": "usd_equivalent",
        "kind": "amount_threshold",
        "operator": "gte",
        "threshold": {
          "currency": "USD",
          "value": "10000.00"
        }
      },
      {
        "asset_class": "crypto",
        "asset_role": "principal",
        "kind": "asset_class"
      }
    ],
    "created_at": "2026-05-01T10:00:00Z",
    "decision": {
      "approver_role_ref": "roles/44444444-4444-4444-8444-444444444444",
      "initiator_cannot_approve": true,
      "kind": "require_approval",
      "reason": "large_crypto_withdrawal",
      "threshold": 2
    },
    "etag": "policy-rule-v2-0001",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "operation_type": "withdrawal",
    "resource": "policy_rule",
    "retired_at": null,
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z",
    "version": 1
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `412` — If-Match check failed; the resource has changed since the cached etag.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /policy-rules/{rule_id}/retire

**Retire policy rule**

Retires a draft or active rule while preserving its history. If-Match must match the current rule etag. Retired rules no longer participate in evaluation and cannot be retired again. The optional body may supply a nullable reason.

**Required capability:** `policies.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `rule_id` `string` (path) *(required)*
- `If-Match` `string` (header) *(required)* — Weak entity tag from a prior GET. Mismatch causes the request to fail with 412 Precondition Failed.
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `reason` | string or null | No |  |

Additional fields are not accepted.

#### Request body schema.reason

At least one alternative must match.

##### Request body schema.reason: alternative 1

Type: `string`. minLength: 1

##### Request body schema.reason: alternative 2

Type: `null`.

**Request example:**

```json
{
  "reason": "No longer needed"
}
```

### policy-rules-retire Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1 |
| `description` | string or null | Yes |  |
| `activated_at` | string or string or null | Yes |  |
| `conditions` | object or object or object or object or object or object[] | Yes |  |
| `created_at` | string or string | Yes |  |
| `decision` | object or object or object | Yes |  |
| `etag` | string | Yes | minLength: 1 |
| `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)$` |
| `operation_type` | "withdrawal" / "conversion" / "external_settlement_conversion" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension" | Yes |  |
| `resource` | "policy_rule" | Yes |  |
| `retired_at` | string or string or null | Yes |  |
| `scope_ref` | string or string | Yes |  |
| `status` | "draft" / "active" / "retired" | Yes |  |
| `updated_at` | string or string | Yes |  |
| `version` | integer | Yes | maximum: 9007199254740991; exclusiveMinimum: 0 |

Additional fields are not accepted.

##### application/json body.description

At least one alternative must match.

###### application/json body.description: alternative 1

Type: `string`. minLength: 1

###### application/json body.description: alternative 2

Type: `null`. 

##### application/json body.activated_at

At least one alternative must match.

###### application/json body.activated_at: alternative 1

At least one alternative must match.

###### application/json body.activated_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.activated_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.activated_at: alternative 2

Type: `null`. 

##### application/json body.conditions

Type: `object or object or object or object or object or object[]`. 

###### application/json body.conditions item

Exactly one alternative must match.

###### application/json body.conditions item: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount_basis` | "native_amount" / "usd_equivalent" | Yes |  |
| `kind` | "amount_threshold" | Yes |  |
| `operator` | "gt" / "gte" / "lt" / "lte" | Yes |  |
| `threshold` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.conditions item: alternative 1.threshold

| 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.

###### application/json body.conditions item: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset_class` | "fiat" / "crypto" | Yes |  |
| `asset_role` | "principal" / "source" / "target" | Yes |  |
| `kind` | "asset_class" | Yes |  |

Additional fields are not accepted.

###### application/json body.conditions item: alternative 3

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset_code` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `asset_role` | "principal" / "source" / "target" | Yes |  |
| `kind` | "asset" | Yes |  |

Additional fields are not accepted.

###### application/json body.conditions item: alternative 4

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `direction` | "master_to_client" / "client_to_master" / "client_to_client" | Yes |  |
| `kind` | "direction" | Yes |  |

Additional fields are not accepted.

###### application/json body.conditions item: alternative 5

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `initiator_ref` | string | Yes | pattern: `^(users\|service-accounts\|platform-principals)\/([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})$` |
| `kind` | "initiator" | Yes |  |

Additional fields are not accepted.

###### application/json body.conditions item: alternative 6

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "conversion_asset_class_pair" | Yes |  |
| `source_asset_class` | "fiat" / "crypto" | Yes |  |
| `target_asset_class` | "fiat" / "crypto" | Yes |  |

Additional fields are not accepted.

##### application/json body.created_at

At least one alternative must match.

###### application/json body.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.created_at: alternative 2

Type: `string`. format: date-time

##### application/json body.decision

Exactly one alternative must match.

###### application/json body.decision: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "allow" | Yes |  |
| `reason` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.reason

At least one alternative must match.

###### application/json body.decision: alternative 1.reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.decision: alternative 1.reason: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "deny" | Yes |  |
| `reason` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.decision: alternative 3

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approver_role_ref` | string or null | No |  |
| `initiator_cannot_approve` | boolean | Yes |  |
| `kind` | "require_approval" | Yes |  |
| `reason` | string | Yes | minLength: 1 |
| `threshold` | integer | Yes | maximum: 9007199254740991; exclusiveMinimum: 0 |

Additional fields are not accepted.

###### application/json body.decision: alternative 3.approver_role_ref

At least one alternative must match.

###### application/json body.decision: alternative 3.approver_role_ref: alternative 1

Type: `string`. pattern: `^(roles)\/([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})$`

###### application/json body.decision: alternative 3.approver_role_ref: alternative 2

Type: `null`. 

##### application/json body.retired_at

At least one alternative must match.

###### application/json body.retired_at: alternative 1

At least one alternative must match.

###### application/json body.retired_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.retired_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.retired_at: alternative 2

Type: `null`. 

##### application/json body.scope_ref

At least one alternative must match.

###### application/json body.scope_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.scope_ref: alternative 2

Type: `string`. 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})$`

##### application/json body.updated_at

At least one alternative must match.

###### application/json body.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.updated_at: alternative 2

Type: `string`. format: date-time


### policy-rules-retire 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.


### policy-rules-retire Response 401 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.


### policy-rules-retire Response 403 schema

Content type: `application/json`.

See [response 401 schema](#policy-rules-retire-response-401-schema).


### policy-rules-retire Response 404 schema

Content type: `application/json`.

See [response 401 schema](#policy-rules-retire-response-401-schema).


### policy-rules-retire Response 409 schema

Content type: `application/json`.

See [response 401 schema](#policy-rules-retire-response-401-schema).


### policy-rules-retire Response 412 schema

Content type: `application/json`.

See [response 401 schema](#policy-rules-retire-response-401-schema).


### policy-rules-retire Response 500 schema

Content type: `application/json`.

See [response 401 schema](#policy-rules-retire-response-401-schema).


### policy-rules-retire Response 502 schema

Content type: `application/json`.

See [response 400 schema](#policy-rules-retire-response-400-schema).


### policy-rules-retire Response 503 schema

Content type: `application/json`.

See [response 400 schema](#policy-rules-retire-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "name": "Large crypto withdrawal approval",
    "description": "Require compliance review for large crypto withdrawals",
    "activated_at": "2026-05-01T10:00:00Z",
    "conditions": [
      {
        "amount_basis": "usd_equivalent",
        "kind": "amount_threshold",
        "operator": "gte",
        "threshold": {
          "currency": "USD",
          "value": "10000.00"
        }
      },
      {
        "asset_class": "crypto",
        "asset_role": "principal",
        "kind": "asset_class"
      }
    ],
    "created_at": "2026-05-01T10:00:00Z",
    "decision": {
      "approver_role_ref": "roles/44444444-4444-4444-8444-444444444444",
      "initiator_cannot_approve": true,
      "kind": "require_approval",
      "reason": "large_crypto_withdrawal",
      "threshold": 2
    },
    "etag": "policy-rule-v2-0001",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "operation_type": "withdrawal",
    "resource": "policy_rule",
    "retired_at": "2026-05-01T10:00:00Z",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "retired",
    "updated_at": "2026-05-01T10:00:00Z",
    "version": 1
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `412` — If-Match check failed; the resource has changed since the cached etag.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Action Tokens

### POST /action-tokens

**Issue action token**

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 /withdrawals`
  - `conversion.create` → `POST /conversions`
  - `external_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.

**Authentication:** Bearer token required.

**MFA assurance:** `action_token.issue`; step-up challenge: `insufficient_user_authentication`.

**Request body** (`application/json`):

### 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 example:**

```json
{
  "action": "conversion.create",
  "command": {
    "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "from_amount": {
      "currency": "USDT",
      "value": "100.00"
    },
    "to_currency": "BTC"
  }
}
```

### action-tokens-create 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" |  |

### action-tokens-create 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.


### action-tokens-create 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. |

### action-tokens-create 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.


### action-tokens-create Response 404 schema

Content type: `application/json`.

See [response 403 schema](#action-tokens-create-response-403-schema).


### action-tokens-create Response 409 schema

Content type: `application/json`.

See [response 403 schema](#action-tokens-create-response-403-schema).


### action-tokens-create Response 500 schema

Content type: `application/json`.

See [response 403 schema](#action-tokens-create-response-403-schema).


### action-tokens-create Response 502 schema

Content type: `application/json`.

See [response 400 schema](#action-tokens-create-response-400-schema).


### action-tokens-create Response 503 schema

Content type: `application/json`.

See [response 400 schema](#action-tokens-create-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "bound_actor": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "bound_command_digest": "a67a92ab1ea536ece3702cb97990040a45948c453aeb585e5ed1d8f2ce7734af",
    "expires_at": "2026-05-01T10:00:00Z",
    "token": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Additional user authentication is required. The response includes `code = insufficient_user_authentication`; the `WWW-Authenticate` header carries RFC 9470 `acr_values` and `max_age` parameters that tell the client which step-up assurance to request before retrying.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Approvals

### GET /approvals

**List approvals**

Lists approval cases visible in the required topology scope. Repeat status to select several states. The edge accepts approvals.read or approvals.decide; tenant queues still require read authority over the requested scope, while the platform queue also admits its authorized deciders.

**Requires at least one capability:** `approvals.read` or `approvals.decide`

**Authentication:** Bearer token required.

**Parameters:**

- `scope_ref` `string` (query) *(required)*
- `status` `string` (query)
- `operation_id` `string` (query)
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### approvals-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `action_family` | string | Yes | minLength: 1 |
| `collected_human_approvals` | integer | Yes | minimum: 0; maximum: 9007199254740991 |
| `created_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))$` |
| `decision` | object or null | No |  |
| `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))$` |
| `governed_ref` | string or string | Yes |  |
| `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)$` |
| `initiated_by` | object | Yes | No additional fields |
| `operation_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)$` |
| `requirement_snapshot` | object | Yes | No additional fields |
| `resource` | "approval" | Yes |  |
| `status` | "pending" / "approved" / "rejected" / "cancelled" / "expired" | Yes |  |
| `subject_display` | object or null | No |  |
| `subject_ref` | string or null | No |  |
| `updated_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))$` |

Additional fields are not accepted.

###### application/json body.items item.decision

At least one alternative must match.

###### application/json body.items item.decision: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `decided_at` | string or null | No |  |
| `decided_by` | object or null | No |  |
| `reason` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.decision: alternative 1.decided_at

At least one alternative must match.

###### application/json body.items item.decision: alternative 1.decided_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.decision: alternative 1.decided_at: alternative 2

Type: `null`. 

###### application/json body.items item.decision: alternative 1.decided_by

At least one alternative must match.

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.actor

At least one alternative must match.

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.actor: alternative 2

Type: `null`. 

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.approved_by

At least one alternative must match.

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.approved_by: alternative 2

Type: `null`. 

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.federation

At least one alternative must match.

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.federation: alternative 2

Type: `null`. 

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.initiated_by

At least one alternative must match.

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.initiated_by: alternative 2

Type: `null`. 

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.subject

At least one alternative must match.

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.decision: alternative 1.decided_by: alternative 1.subject: alternative 2

Type: `null`. 

###### application/json body.items item.decision: alternative 1.decided_by: alternative 2

Type: `null`. 

###### application/json body.items item.decision: alternative 1.reason

At least one alternative must match.

###### application/json body.items item.decision: alternative 1.reason: alternative 1

Type: `string`. 

###### application/json body.items item.decision: alternative 1.reason: alternative 2

Type: `null`. 

###### application/json body.items item.decision: alternative 2

Type: `null`. 

###### application/json body.items item.governed_ref

At least one alternative must match.

###### application/json body.items item.governed_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.governed_ref: alternative 2

Type: `string`. 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})$`

###### application/json body.items item.initiated_by

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.initiated_by.actor

At least one alternative must match.

###### application/json body.items item.initiated_by.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.initiated_by.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item.initiated_by.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.initiated_by.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.initiated_by.actor: alternative 2

Type: `null`. 

###### application/json body.items item.initiated_by.approved_by

At least one alternative must match.

###### application/json body.items item.initiated_by.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.initiated_by.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item.initiated_by.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.initiated_by.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.initiated_by.approved_by: alternative 2

Type: `null`. 

###### application/json body.items item.initiated_by.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.initiated_by.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.items item.initiated_by.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.initiated_by.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.initiated_by.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.initiated_by.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.items item.initiated_by.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.initiated_by.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.items item.initiated_by.federation

At least one alternative must match.

###### application/json body.items item.initiated_by.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.items item.initiated_by.federation: alternative 2

Type: `null`. 

###### application/json body.items item.initiated_by.initiated_by

At least one alternative must match.

###### application/json body.items item.initiated_by.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.initiated_by.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item.initiated_by.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.initiated_by.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.initiated_by.initiated_by: alternative 2

Type: `null`. 

###### application/json body.items item.initiated_by.subject

At least one alternative must match.

###### application/json body.items item.initiated_by.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.initiated_by.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item.initiated_by.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.initiated_by.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.initiated_by.subject: alternative 2

Type: `null`. 

###### application/json body.items item.requirement_snapshot

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approver_role_ref` | string or null | No |  |
| `authority_ref` | string | Yes | pattern: `^(enterprises\|platform-operators\|clients)\/([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})$` |
| `expires_at` | string or null | No |  |
| `governed_ref` | string or string | Yes |  |
| `initiator_cannot_approve` | boolean | Yes |  |
| `reason_code` | string | Yes | minLength: 1 |
| `required_human_approvals` | integer | Yes | maximum: 9007199254740991; exclusiveMinimum: 0 |
| `requirement_key` | string | Yes | minLength: 1 |
| `source` | "policy" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.requirement_snapshot.approver_role_ref

At least one alternative must match.

###### application/json body.items item.requirement_snapshot.approver_role_ref: alternative 1

Type: `string`. pattern: `^(roles)\/([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})$`

###### application/json body.items item.requirement_snapshot.approver_role_ref: alternative 2

Type: `null`. 

###### application/json body.items item.requirement_snapshot.expires_at

At least one alternative must match.

###### application/json body.items item.requirement_snapshot.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.requirement_snapshot.expires_at: alternative 2

Type: `null`. 

###### application/json body.items item.requirement_snapshot.governed_ref

At least one alternative must match.

###### application/json body.items item.requirement_snapshot.governed_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.requirement_snapshot.governed_ref: alternative 2

Type: `string`. 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})$`

###### application/json body.items item.subject_display

At least one alternative must match.

###### application/json body.items item.subject_display: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `current_email` | string or null | Yes |  |
| `new_email` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.subject_display: alternative 1.current_email

At least one alternative must match.

###### application/json body.items item.subject_display: alternative 1.current_email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.items item.subject_display: alternative 1.current_email: alternative 2

Type: `null`. 

###### application/json body.items item.subject_display: alternative 1.new_email

At least one alternative must match.

###### application/json body.items item.subject_display: alternative 1.new_email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.items item.subject_display: alternative 1.new_email: alternative 2

Type: `null`. 

###### application/json body.items item.subject_display: alternative 2

Type: `null`. 

###### application/json body.items item.subject_ref

At least one alternative must match.

###### application/json body.items item.subject_ref: alternative 1

Type: `string`. pattern: `^(users)\/([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})$`

###### application/json body.items item.subject_ref: alternative 2

Type: `null`. 

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. 

###### application/json body.next_page_token: alternative 2

Type: `null`.


### approvals-list 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.


### approvals-list Response 401 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.


### approvals-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#approvals-list-response-401-schema).


### approvals-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#approvals-list-response-401-schema).


### approvals-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#approvals-list-response-400-schema).


### approvals-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#approvals-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "action_family": "withdrawal",
        "collected_human_approvals": 0,
        "created_at": "2026-05-01T10:00:00Z",
        "decision": null,
        "expires_at": "2026-05-02T10:00:00Z",
        "governed_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "initiated_by": {
          "actor": null,
          "approved_by": null,
          "authenticated_principal": {
            "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
            "kind": "user",
            "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
          },
          "enterprise_binding": {
            "tenant_type": "enterprise",
            "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
          },
          "federation": null,
          "identity_source": "platform-managed",
          "initiated_by": null,
          "subject": {
            "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
            "kind": "user",
            "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
          }
        },
        "operation_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "requirement_snapshot": {
          "authority_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
          "expires_at": "2026-05-02T10:00:00Z",
          "governed_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
          "initiator_cannot_approve": true,
          "reason_code": "high_value",
          "required_human_approvals": 1,
          "requirement_key": "withdrawal_approval",
          "source": "policy"
        },
        "resource": "approval",
        "status": "pending",
        "updated_at": "2026-05-01T10:00:00Z"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /approvals/{approval_id}

**Get approval**

Reads a visible approval case. The edge accepts approvals.read or approvals.decide; downstream visibility checks still apply to its governed scope. collected_human_approvals records the distinct people who have approved against requirement_snapshot.required_human_approvals.

**Requires at least one capability:** `approvals.read` or `approvals.decide`

**Authentication:** Bearer token required.

**Parameters:**

- `approval_id` `string` (path) *(required)*

### approvals-get Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `action_family` | string | Yes | minLength: 1 |
| `collected_human_approvals` | integer | Yes | minimum: 0; maximum: 9007199254740991 |
| `created_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))$` |
| `decision` | object or null | No |  |
| `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))$` |
| `governed_ref` | string or string | Yes |  |
| `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)$` |
| `initiated_by` | object | Yes | No additional fields |
| `operation_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)$` |
| `requirement_snapshot` | object | Yes | No additional fields |
| `resource` | "approval" | Yes |  |
| `status` | "pending" / "approved" / "rejected" / "cancelled" / "expired" | Yes |  |
| `subject_display` | object or null | No |  |
| `subject_ref` | string or null | No |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.decision

At least one alternative must match.

###### application/json body.decision: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `decided_at` | string or null | No |  |
| `decided_by` | object or null | No |  |
| `reason` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_at

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_at: alternative 1

Type: `string`. 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))$`

###### application/json body.decision: alternative 1.decided_at: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.actor

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.decision: alternative 1.decided_by: alternative 1.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.actor: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.approved_by

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.decision: alternative 1.decided_by: alternative 1.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.approved_by: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.decision: alternative 1.decided_by: alternative 1.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.decision: alternative 1.decided_by: alternative 1.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.federation

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.federation: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.initiated_by

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.decision: alternative 1.decided_by: alternative 1.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.initiated_by: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.subject

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.decision: alternative 1.decided_by: alternative 1.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.subject: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.reason

At least one alternative must match.

###### application/json body.decision: alternative 1.reason: alternative 1

Type: `string`. 

###### application/json body.decision: alternative 1.reason: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 2

Type: `null`. 

##### application/json body.governed_ref

At least one alternative must match.

###### application/json body.governed_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.governed_ref: alternative 2

Type: `string`. 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})$`

##### application/json body.initiated_by

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.initiated_by.actor

At least one alternative must match.

###### application/json body.initiated_by.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.initiated_by.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.initiated_by.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.initiated_by.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.initiated_by.actor: alternative 2

Type: `null`. 

###### application/json body.initiated_by.approved_by

At least one alternative must match.

###### application/json body.initiated_by.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.initiated_by.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.initiated_by.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.initiated_by.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.initiated_by.approved_by: alternative 2

Type: `null`. 

###### application/json body.initiated_by.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.initiated_by.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.initiated_by.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.initiated_by.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.initiated_by.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.initiated_by.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.initiated_by.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.initiated_by.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.initiated_by.federation

At least one alternative must match.

###### application/json body.initiated_by.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.initiated_by.federation: alternative 2

Type: `null`. 

###### application/json body.initiated_by.initiated_by

At least one alternative must match.

###### application/json body.initiated_by.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.initiated_by.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.initiated_by.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.initiated_by.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.initiated_by.initiated_by: alternative 2

Type: `null`. 

###### application/json body.initiated_by.subject

At least one alternative must match.

###### application/json body.initiated_by.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.initiated_by.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.initiated_by.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.initiated_by.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.initiated_by.subject: alternative 2

Type: `null`. 

##### application/json body.requirement_snapshot

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approver_role_ref` | string or null | No |  |
| `authority_ref` | string | Yes | pattern: `^(enterprises\|platform-operators\|clients)\/([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})$` |
| `expires_at` | string or null | No |  |
| `governed_ref` | string or string | Yes |  |
| `initiator_cannot_approve` | boolean | Yes |  |
| `reason_code` | string | Yes | minLength: 1 |
| `required_human_approvals` | integer | Yes | maximum: 9007199254740991; exclusiveMinimum: 0 |
| `requirement_key` | string | Yes | minLength: 1 |
| `source` | "policy" | Yes |  |

Additional fields are not accepted.

###### application/json body.requirement_snapshot.approver_role_ref

At least one alternative must match.

###### application/json body.requirement_snapshot.approver_role_ref: alternative 1

Type: `string`. pattern: `^(roles)\/([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})$`

###### application/json body.requirement_snapshot.approver_role_ref: alternative 2

Type: `null`. 

###### application/json body.requirement_snapshot.expires_at

At least one alternative must match.

###### application/json body.requirement_snapshot.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.requirement_snapshot.expires_at: alternative 2

Type: `null`. 

###### application/json body.requirement_snapshot.governed_ref

At least one alternative must match.

###### application/json body.requirement_snapshot.governed_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.requirement_snapshot.governed_ref: alternative 2

Type: `string`. 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})$`

##### application/json body.subject_display

At least one alternative must match.

###### application/json body.subject_display: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `current_email` | string or null | Yes |  |
| `new_email` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_display: alternative 1.current_email

At least one alternative must match.

###### application/json body.subject_display: alternative 1.current_email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.subject_display: alternative 1.current_email: alternative 2

Type: `null`. 

###### application/json body.subject_display: alternative 1.new_email

At least one alternative must match.

###### application/json body.subject_display: alternative 1.new_email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.subject_display: alternative 1.new_email: alternative 2

Type: `null`. 

###### application/json body.subject_display: alternative 2

Type: `null`. 

##### application/json body.subject_ref

At least one alternative must match.

###### application/json body.subject_ref: alternative 1

Type: `string`. pattern: `^(users)\/([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})$`

###### application/json body.subject_ref: alternative 2

Type: `null`.


### approvals-get 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.


### approvals-get Response 401 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.


### approvals-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#approvals-get-response-401-schema).


### approvals-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#approvals-get-response-401-schema).


### approvals-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#approvals-get-response-401-schema).


### approvals-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#approvals-get-response-400-schema).


### approvals-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#approvals-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "action_family": "withdrawal",
    "collected_human_approvals": 0,
    "created_at": "2026-05-01T10:00:00Z",
    "decision": null,
    "expires_at": "2026-05-02T10:00:00Z",
    "governed_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "initiated_by": {
      "actor": null,
      "approved_by": null,
      "authenticated_principal": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "enterprise_binding": {
        "tenant_type": "enterprise",
        "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "federation": null,
      "identity_source": "platform-managed",
      "initiated_by": null,
      "subject": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      }
    },
    "operation_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "requirement_snapshot": {
      "authority_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "expires_at": "2026-05-02T10:00:00Z",
      "governed_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "initiator_cannot_approve": true,
      "reason_code": "high_value",
      "required_human_approvals": 1,
      "requirement_key": "withdrawal_approval",
      "source": "policy"
    },
    "resource": "approval",
    "status": "pending",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /approvals/{approval_id}/approve

**Approve approval**

Records an eligible human approval on a pending case. The caller needs approvals.decide, scope coverage and any role named in the requirement snapshot; initiator_cannot_approve excludes the initiator when enabled. The case stays pending until enough distinct human approvals are collected, then becomes approved. MFA assurance applies to this decision surface; a step-up challenge is returned when the current session does not meet the resolved requirement.

**Required capability:** `approvals.decide`

**Authentication:** Bearer token required.

**MFA assurance:** `approval.decide`; step-up challenge: `insufficient_user_authentication`.

**Parameters:**

- `approval_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `reason` | string or null | No |  |

Additional fields are not accepted.

#### Request body schema.reason

At least one alternative must match.

##### Request body schema.reason: alternative 1

Type: `string`. 

##### Request body schema.reason: alternative 2

Type: `null`.

**Request example:**

```json
{
  "reason": "Reviewed request"
}
```

### approvals-approve Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `action_family` | string | Yes | minLength: 1 |
| `collected_human_approvals` | integer | Yes | minimum: 0; maximum: 9007199254740991 |
| `created_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))$` |
| `decision` | object or null | No |  |
| `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))$` |
| `governed_ref` | string or string | Yes |  |
| `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)$` |
| `initiated_by` | object | Yes | No additional fields |
| `operation_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)$` |
| `requirement_snapshot` | object | Yes | No additional fields |
| `resource` | "approval" | Yes |  |
| `status` | "pending" / "approved" / "rejected" / "cancelled" / "expired" | Yes |  |
| `subject_display` | object or null | No |  |
| `subject_ref` | string or null | No |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.decision

At least one alternative must match.

###### application/json body.decision: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `decided_at` | string or null | No |  |
| `decided_by` | object or null | No |  |
| `reason` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_at

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_at: alternative 1

Type: `string`. 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))$`

###### application/json body.decision: alternative 1.decided_at: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.actor

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.decision: alternative 1.decided_by: alternative 1.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.actor: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.approved_by

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.decision: alternative 1.decided_by: alternative 1.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.approved_by: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.decision: alternative 1.decided_by: alternative 1.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.decision: alternative 1.decided_by: alternative 1.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.federation

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.federation: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.initiated_by

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.decision: alternative 1.decided_by: alternative 1.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.initiated_by: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.subject

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.decision: alternative 1.decided_by: alternative 1.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.subject: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.reason

At least one alternative must match.

###### application/json body.decision: alternative 1.reason: alternative 1

Type: `string`. 

###### application/json body.decision: alternative 1.reason: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 2

Type: `null`. 

##### application/json body.governed_ref

At least one alternative must match.

###### application/json body.governed_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.governed_ref: alternative 2

Type: `string`. 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})$`

##### application/json body.initiated_by

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.initiated_by.actor

At least one alternative must match.

###### application/json body.initiated_by.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.initiated_by.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.initiated_by.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.initiated_by.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.initiated_by.actor: alternative 2

Type: `null`. 

###### application/json body.initiated_by.approved_by

At least one alternative must match.

###### application/json body.initiated_by.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.initiated_by.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.initiated_by.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.initiated_by.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.initiated_by.approved_by: alternative 2

Type: `null`. 

###### application/json body.initiated_by.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.initiated_by.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.initiated_by.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.initiated_by.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.initiated_by.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.initiated_by.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.initiated_by.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.initiated_by.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.initiated_by.federation

At least one alternative must match.

###### application/json body.initiated_by.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.initiated_by.federation: alternative 2

Type: `null`. 

###### application/json body.initiated_by.initiated_by

At least one alternative must match.

###### application/json body.initiated_by.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.initiated_by.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.initiated_by.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.initiated_by.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.initiated_by.initiated_by: alternative 2

Type: `null`. 

###### application/json body.initiated_by.subject

At least one alternative must match.

###### application/json body.initiated_by.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.initiated_by.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.initiated_by.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.initiated_by.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.initiated_by.subject: alternative 2

Type: `null`. 

##### application/json body.requirement_snapshot

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approver_role_ref` | string or null | No |  |
| `authority_ref` | string | Yes | pattern: `^(enterprises\|platform-operators\|clients)\/([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})$` |
| `expires_at` | string or null | No |  |
| `governed_ref` | string or string | Yes |  |
| `initiator_cannot_approve` | boolean | Yes |  |
| `reason_code` | string | Yes | minLength: 1 |
| `required_human_approvals` | integer | Yes | maximum: 9007199254740991; exclusiveMinimum: 0 |
| `requirement_key` | string | Yes | minLength: 1 |
| `source` | "policy" | Yes |  |

Additional fields are not accepted.

###### application/json body.requirement_snapshot.approver_role_ref

At least one alternative must match.

###### application/json body.requirement_snapshot.approver_role_ref: alternative 1

Type: `string`. pattern: `^(roles)\/([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})$`

###### application/json body.requirement_snapshot.approver_role_ref: alternative 2

Type: `null`. 

###### application/json body.requirement_snapshot.expires_at

At least one alternative must match.

###### application/json body.requirement_snapshot.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.requirement_snapshot.expires_at: alternative 2

Type: `null`. 

###### application/json body.requirement_snapshot.governed_ref

At least one alternative must match.

###### application/json body.requirement_snapshot.governed_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.requirement_snapshot.governed_ref: alternative 2

Type: `string`. 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})$`

##### application/json body.subject_display

At least one alternative must match.

###### application/json body.subject_display: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `current_email` | string or null | Yes |  |
| `new_email` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_display: alternative 1.current_email

At least one alternative must match.

###### application/json body.subject_display: alternative 1.current_email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.subject_display: alternative 1.current_email: alternative 2

Type: `null`. 

###### application/json body.subject_display: alternative 1.new_email

At least one alternative must match.

###### application/json body.subject_display: alternative 1.new_email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.subject_display: alternative 1.new_email: alternative 2

Type: `null`. 

###### application/json body.subject_display: alternative 2

Type: `null`. 

##### application/json body.subject_ref

At least one alternative must match.

###### application/json body.subject_ref: alternative 1

Type: `string`. pattern: `^(users)\/([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})$`

###### application/json body.subject_ref: alternative 2

Type: `null`.


### approvals-approve 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.


### approvals-approve 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. |

### approvals-approve 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.


### approvals-approve Response 404 schema

Content type: `application/json`.

See [response 403 schema](#approvals-approve-response-403-schema).


### approvals-approve Response 409 schema

Content type: `application/json`.

See [response 403 schema](#approvals-approve-response-403-schema).


### approvals-approve Response 500 schema

Content type: `application/json`.

See [response 403 schema](#approvals-approve-response-403-schema).


### approvals-approve Response 502 schema

Content type: `application/json`.

See [response 400 schema](#approvals-approve-response-400-schema).


### approvals-approve Response 503 schema

Content type: `application/json`.

See [response 400 schema](#approvals-approve-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "action_family": "withdrawal",
    "collected_human_approvals": 1,
    "created_at": "2026-05-01T10:00:00Z",
    "decision": {
      "decided_at": "2026-05-01T10:00:00Z",
      "decided_by": {
        "actor": null,
        "approved_by": null,
        "authenticated_principal": {
          "id": "11111111-1111-4111-8111-111111111111",
          "kind": "user",
          "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
        },
        "enterprise_binding": {
          "tenant_type": "enterprise",
          "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
        },
        "federation": null,
        "identity_source": "platform-managed",
        "initiated_by": null,
        "subject": {
          "id": "11111111-1111-4111-8111-111111111111",
          "kind": "user",
          "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
        }
      },
      "reason": "Approved after review"
    },
    "expires_at": "2026-05-02T10:00:00Z",
    "governed_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "initiated_by": {
      "actor": null,
      "approved_by": null,
      "authenticated_principal": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "enterprise_binding": {
        "tenant_type": "enterprise",
        "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "federation": null,
      "identity_source": "platform-managed",
      "initiated_by": null,
      "subject": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      }
    },
    "operation_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "requirement_snapshot": {
      "authority_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "expires_at": "2026-05-02T10:00:00Z",
      "governed_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "initiator_cannot_approve": true,
      "reason_code": "high_value",
      "required_human_approvals": 1,
      "requirement_key": "withdrawal_approval",
      "source": "policy"
    },
    "resource": "approval",
    "status": "approved",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Additional user authentication is required. The response includes `code = insufficient_user_authentication`; the `WWW-Authenticate` header carries RFC 9470 `acr_values` and `max_age` parameters that tell the client which step-up assurance to request before retrying.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /approvals/{approval_id}/cancel

**Cancel approval**

Cancels a pending case on behalf of its original initiator. The edge requires approvals.decide; downstream also verifies that the caller is the original initiator. An optional nullable reason may be supplied. This route has no approval-decision MFA assurance gate.

**Required capability:** `approvals.decide`

**Authentication:** Bearer token required.

**Parameters:**

- `approval_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `reason` | string or null | No |  |

Additional fields are not accepted.

#### Request body schema.reason

At least one alternative must match.

##### Request body schema.reason: alternative 1

Type: `string`. 

##### Request body schema.reason: alternative 2

Type: `null`.

**Request example:**

```json
{
  "reason": "Reviewed request"
}
```

### approvals-cancel Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `action_family` | string | Yes | minLength: 1 |
| `collected_human_approvals` | integer | Yes | minimum: 0; maximum: 9007199254740991 |
| `created_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))$` |
| `decision` | object or null | No |  |
| `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))$` |
| `governed_ref` | string or string | Yes |  |
| `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)$` |
| `initiated_by` | object | Yes | No additional fields |
| `operation_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)$` |
| `requirement_snapshot` | object | Yes | No additional fields |
| `resource` | "approval" | Yes |  |
| `status` | "pending" / "approved" / "rejected" / "cancelled" / "expired" | Yes |  |
| `subject_display` | object or null | No |  |
| `subject_ref` | string or null | No |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.decision

At least one alternative must match.

###### application/json body.decision: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `decided_at` | string or null | No |  |
| `decided_by` | object or null | No |  |
| `reason` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_at

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_at: alternative 1

Type: `string`. 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))$`

###### application/json body.decision: alternative 1.decided_at: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.actor

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.decision: alternative 1.decided_by: alternative 1.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.actor: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.approved_by

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.decision: alternative 1.decided_by: alternative 1.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.approved_by: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.decision: alternative 1.decided_by: alternative 1.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.decision: alternative 1.decided_by: alternative 1.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.federation

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.federation: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.initiated_by

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.decision: alternative 1.decided_by: alternative 1.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.initiated_by: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.subject

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.decision: alternative 1.decided_by: alternative 1.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.subject: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.reason

At least one alternative must match.

###### application/json body.decision: alternative 1.reason: alternative 1

Type: `string`. 

###### application/json body.decision: alternative 1.reason: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 2

Type: `null`. 

##### application/json body.governed_ref

At least one alternative must match.

###### application/json body.governed_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.governed_ref: alternative 2

Type: `string`. 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})$`

##### application/json body.initiated_by

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.initiated_by.actor

At least one alternative must match.

###### application/json body.initiated_by.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.initiated_by.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.initiated_by.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.initiated_by.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.initiated_by.actor: alternative 2

Type: `null`. 

###### application/json body.initiated_by.approved_by

At least one alternative must match.

###### application/json body.initiated_by.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.initiated_by.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.initiated_by.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.initiated_by.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.initiated_by.approved_by: alternative 2

Type: `null`. 

###### application/json body.initiated_by.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.initiated_by.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.initiated_by.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.initiated_by.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.initiated_by.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.initiated_by.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.initiated_by.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.initiated_by.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.initiated_by.federation

At least one alternative must match.

###### application/json body.initiated_by.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.initiated_by.federation: alternative 2

Type: `null`. 

###### application/json body.initiated_by.initiated_by

At least one alternative must match.

###### application/json body.initiated_by.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.initiated_by.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.initiated_by.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.initiated_by.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.initiated_by.initiated_by: alternative 2

Type: `null`. 

###### application/json body.initiated_by.subject

At least one alternative must match.

###### application/json body.initiated_by.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.initiated_by.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.initiated_by.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.initiated_by.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.initiated_by.subject: alternative 2

Type: `null`. 

##### application/json body.requirement_snapshot

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approver_role_ref` | string or null | No |  |
| `authority_ref` | string | Yes | pattern: `^(enterprises\|platform-operators\|clients)\/([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})$` |
| `expires_at` | string or null | No |  |
| `governed_ref` | string or string | Yes |  |
| `initiator_cannot_approve` | boolean | Yes |  |
| `reason_code` | string | Yes | minLength: 1 |
| `required_human_approvals` | integer | Yes | maximum: 9007199254740991; exclusiveMinimum: 0 |
| `requirement_key` | string | Yes | minLength: 1 |
| `source` | "policy" | Yes |  |

Additional fields are not accepted.

###### application/json body.requirement_snapshot.approver_role_ref

At least one alternative must match.

###### application/json body.requirement_snapshot.approver_role_ref: alternative 1

Type: `string`. pattern: `^(roles)\/([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})$`

###### application/json body.requirement_snapshot.approver_role_ref: alternative 2

Type: `null`. 

###### application/json body.requirement_snapshot.expires_at

At least one alternative must match.

###### application/json body.requirement_snapshot.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.requirement_snapshot.expires_at: alternative 2

Type: `null`. 

###### application/json body.requirement_snapshot.governed_ref

At least one alternative must match.

###### application/json body.requirement_snapshot.governed_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.requirement_snapshot.governed_ref: alternative 2

Type: `string`. 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})$`

##### application/json body.subject_display

At least one alternative must match.

###### application/json body.subject_display: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `current_email` | string or null | Yes |  |
| `new_email` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_display: alternative 1.current_email

At least one alternative must match.

###### application/json body.subject_display: alternative 1.current_email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.subject_display: alternative 1.current_email: alternative 2

Type: `null`. 

###### application/json body.subject_display: alternative 1.new_email

At least one alternative must match.

###### application/json body.subject_display: alternative 1.new_email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.subject_display: alternative 1.new_email: alternative 2

Type: `null`. 

###### application/json body.subject_display: alternative 2

Type: `null`. 

##### application/json body.subject_ref

At least one alternative must match.

###### application/json body.subject_ref: alternative 1

Type: `string`. pattern: `^(users)\/([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})$`

###### application/json body.subject_ref: alternative 2

Type: `null`.


### approvals-cancel 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.


### approvals-cancel Response 401 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.


### approvals-cancel Response 403 schema

Content type: `application/json`.

See [response 401 schema](#approvals-cancel-response-401-schema).


### approvals-cancel Response 404 schema

Content type: `application/json`.

See [response 401 schema](#approvals-cancel-response-401-schema).


### approvals-cancel Response 409 schema

Content type: `application/json`.

See [response 401 schema](#approvals-cancel-response-401-schema).


### approvals-cancel Response 500 schema

Content type: `application/json`.

See [response 401 schema](#approvals-cancel-response-401-schema).


### approvals-cancel Response 502 schema

Content type: `application/json`.

See [response 400 schema](#approvals-cancel-response-400-schema).


### approvals-cancel Response 503 schema

Content type: `application/json`.

See [response 400 schema](#approvals-cancel-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "action_family": "withdrawal",
    "collected_human_approvals": 0,
    "created_at": "2026-05-01T10:00:00Z",
    "decision": {
      "decided_at": "2026-05-01T10:00:00Z",
      "decided_by": null,
      "reason": "Cancelled by the original initiator"
    },
    "expires_at": "2026-05-02T10:00:00Z",
    "governed_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "initiated_by": {
      "actor": null,
      "approved_by": null,
      "authenticated_principal": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "enterprise_binding": {
        "tenant_type": "enterprise",
        "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "federation": null,
      "identity_source": "platform-managed",
      "initiated_by": null,
      "subject": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      }
    },
    "operation_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "requirement_snapshot": {
      "authority_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "expires_at": "2026-05-02T10:00:00Z",
      "governed_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "initiator_cannot_approve": true,
      "reason_code": "high_value",
      "required_human_approvals": 1,
      "requirement_key": "withdrawal_approval",
      "source": "policy"
    },
    "resource": "approval",
    "status": "cancelled",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /approvals/{approval_id}/eligible-approvers

**List eligible approvers**

Lists currently eligible human approvers for the case, subject to approvals.read and visibility of its governed scope. Eligibility reflects decide capability, scope coverage, any named approver role and the initiator exclusion. Results are paginated; eligibility is checked again when a decision is submitted.

**Required capability:** `approvals.read`

**Authentication:** Bearer token required.

**Parameters:**

- `approval_id` `string` (path) *(required)*
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### approvals-eligible-approvers Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `display_name` | string or null | No |  |
| `eligibility_basis` | string | Yes | minLength: 1 |
| `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)$` |
| `resource` | "human_actor" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.display_name

At least one alternative must match.

###### application/json body.items item.display_name: alternative 1

Type: `string`. 

###### application/json body.items item.display_name: alternative 2

Type: `null`. 

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. 

###### application/json body.next_page_token: alternative 2

Type: `null`.


### approvals-eligible-approvers 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.


### approvals-eligible-approvers Response 401 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.


### approvals-eligible-approvers Response 403 schema

Content type: `application/json`.

See [response 401 schema](#approvals-eligible-approvers-response-401-schema).


### approvals-eligible-approvers Response 404 schema

Content type: `application/json`.

See [response 401 schema](#approvals-eligible-approvers-response-401-schema).


### approvals-eligible-approvers Response 500 schema

Content type: `application/json`.

See [response 401 schema](#approvals-eligible-approvers-response-401-schema).


### approvals-eligible-approvers Response 502 schema

Content type: `application/json`.

See [response 400 schema](#approvals-eligible-approvers-response-400-schema).


### approvals-eligible-approvers Response 503 schema

Content type: `application/json`.

See [response 400 schema](#approvals-eligible-approvers-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "display_name": "Jane Smith",
        "eligibility_basis": "role_assignment",
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "resource": "human_actor"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /approvals/{approval_id}/reject

**Reject approval**

Rejects a pending case with one eligible human decision, regardless of the approval quorum. The caller needs approvals.decide, scope coverage and any role named in the requirement snapshot; initiator_cannot_approve excludes the initiator when enabled. MFA assurance applies to this decision surface; a step-up challenge is returned when the current session does not meet the resolved requirement.

**Required capability:** `approvals.decide`

**Authentication:** Bearer token required.

**MFA assurance:** `approval.decide`; step-up challenge: `insufficient_user_authentication`.

**Parameters:**

- `approval_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `reason` | string or null | No |  |

Additional fields are not accepted.

#### Request body schema.reason

At least one alternative must match.

##### Request body schema.reason: alternative 1

Type: `string`. 

##### Request body schema.reason: alternative 2

Type: `null`.

**Request example:**

```json
{
  "reason": "Reviewed request"
}
```

### approvals-reject Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `action_family` | string | Yes | minLength: 1 |
| `collected_human_approvals` | integer | Yes | minimum: 0; maximum: 9007199254740991 |
| `created_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))$` |
| `decision` | object or null | No |  |
| `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))$` |
| `governed_ref` | string or string | Yes |  |
| `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)$` |
| `initiated_by` | object | Yes | No additional fields |
| `operation_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)$` |
| `requirement_snapshot` | object | Yes | No additional fields |
| `resource` | "approval" | Yes |  |
| `status` | "pending" / "approved" / "rejected" / "cancelled" / "expired" | Yes |  |
| `subject_display` | object or null | No |  |
| `subject_ref` | string or null | No |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.decision

At least one alternative must match.

###### application/json body.decision: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `decided_at` | string or null | No |  |
| `decided_by` | object or null | No |  |
| `reason` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_at

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_at: alternative 1

Type: `string`. 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))$`

###### application/json body.decision: alternative 1.decided_at: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.actor

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.decision: alternative 1.decided_by: alternative 1.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.actor: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.approved_by

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.decision: alternative 1.decided_by: alternative 1.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.approved_by: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.decision: alternative 1.decided_by: alternative 1.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.decision: alternative 1.decided_by: alternative 1.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.federation

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.federation: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.initiated_by

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.decision: alternative 1.decided_by: alternative 1.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.initiated_by: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.subject

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.decision: alternative 1.decided_by: alternative 1.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.decision: alternative 1.decided_by: alternative 1.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.decision: alternative 1.decided_by: alternative 1.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 1.subject: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.decided_by: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 1.reason

At least one alternative must match.

###### application/json body.decision: alternative 1.reason: alternative 1

Type: `string`. 

###### application/json body.decision: alternative 1.reason: alternative 2

Type: `null`. 

###### application/json body.decision: alternative 2

Type: `null`. 

##### application/json body.governed_ref

At least one alternative must match.

###### application/json body.governed_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.governed_ref: alternative 2

Type: `string`. 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})$`

##### application/json body.initiated_by

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.initiated_by.actor

At least one alternative must match.

###### application/json body.initiated_by.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.initiated_by.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.initiated_by.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.initiated_by.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.initiated_by.actor: alternative 2

Type: `null`. 

###### application/json body.initiated_by.approved_by

At least one alternative must match.

###### application/json body.initiated_by.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.initiated_by.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.initiated_by.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.initiated_by.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.initiated_by.approved_by: alternative 2

Type: `null`. 

###### application/json body.initiated_by.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.initiated_by.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.initiated_by.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.initiated_by.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.initiated_by.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.initiated_by.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.initiated_by.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.initiated_by.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.initiated_by.federation

At least one alternative must match.

###### application/json body.initiated_by.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.initiated_by.federation: alternative 2

Type: `null`. 

###### application/json body.initiated_by.initiated_by

At least one alternative must match.

###### application/json body.initiated_by.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.initiated_by.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.initiated_by.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.initiated_by.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.initiated_by.initiated_by: alternative 2

Type: `null`. 

###### application/json body.initiated_by.subject

At least one alternative must match.

###### application/json body.initiated_by.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.initiated_by.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.initiated_by.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.initiated_by.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.initiated_by.subject: alternative 2

Type: `null`. 

##### application/json body.requirement_snapshot

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approver_role_ref` | string or null | No |  |
| `authority_ref` | string | Yes | pattern: `^(enterprises\|platform-operators\|clients)\/([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})$` |
| `expires_at` | string or null | No |  |
| `governed_ref` | string or string | Yes |  |
| `initiator_cannot_approve` | boolean | Yes |  |
| `reason_code` | string | Yes | minLength: 1 |
| `required_human_approvals` | integer | Yes | maximum: 9007199254740991; exclusiveMinimum: 0 |
| `requirement_key` | string | Yes | minLength: 1 |
| `source` | "policy" | Yes |  |

Additional fields are not accepted.

###### application/json body.requirement_snapshot.approver_role_ref

At least one alternative must match.

###### application/json body.requirement_snapshot.approver_role_ref: alternative 1

Type: `string`. pattern: `^(roles)\/([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})$`

###### application/json body.requirement_snapshot.approver_role_ref: alternative 2

Type: `null`. 

###### application/json body.requirement_snapshot.expires_at

At least one alternative must match.

###### application/json body.requirement_snapshot.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.requirement_snapshot.expires_at: alternative 2

Type: `null`. 

###### application/json body.requirement_snapshot.governed_ref

At least one alternative must match.

###### application/json body.requirement_snapshot.governed_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.requirement_snapshot.governed_ref: alternative 2

Type: `string`. 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})$`

##### application/json body.subject_display

At least one alternative must match.

###### application/json body.subject_display: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `current_email` | string or null | Yes |  |
| `new_email` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_display: alternative 1.current_email

At least one alternative must match.

###### application/json body.subject_display: alternative 1.current_email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.subject_display: alternative 1.current_email: alternative 2

Type: `null`. 

###### application/json body.subject_display: alternative 1.new_email

At least one alternative must match.

###### application/json body.subject_display: alternative 1.new_email: alternative 1

Type: `string`. format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`

###### application/json body.subject_display: alternative 1.new_email: alternative 2

Type: `null`. 

###### application/json body.subject_display: alternative 2

Type: `null`. 

##### application/json body.subject_ref

At least one alternative must match.

###### application/json body.subject_ref: alternative 1

Type: `string`. pattern: `^(users)\/([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})$`

###### application/json body.subject_ref: alternative 2

Type: `null`.


### approvals-reject 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.


### approvals-reject 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. |

### approvals-reject 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.


### approvals-reject Response 404 schema

Content type: `application/json`.

See [response 403 schema](#approvals-reject-response-403-schema).


### approvals-reject Response 409 schema

Content type: `application/json`.

See [response 403 schema](#approvals-reject-response-403-schema).


### approvals-reject Response 500 schema

Content type: `application/json`.

See [response 403 schema](#approvals-reject-response-403-schema).


### approvals-reject Response 502 schema

Content type: `application/json`.

See [response 400 schema](#approvals-reject-response-400-schema).


### approvals-reject Response 503 schema

Content type: `application/json`.

See [response 400 schema](#approvals-reject-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "action_family": "withdrawal",
    "collected_human_approvals": 0,
    "created_at": "2026-05-01T10:00:00Z",
    "decision": {
      "decided_at": "2026-05-01T10:00:00Z",
      "decided_by": {
        "actor": null,
        "approved_by": null,
        "authenticated_principal": {
          "id": "11111111-1111-4111-8111-111111111111",
          "kind": "user",
          "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
        },
        "enterprise_binding": {
          "tenant_type": "enterprise",
          "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
        },
        "federation": null,
        "identity_source": "platform-managed",
        "initiated_by": null,
        "subject": {
          "id": "11111111-1111-4111-8111-111111111111",
          "kind": "user",
          "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
        }
      },
      "reason": "Rejected after review"
    },
    "expires_at": "2026-05-02T10:00:00Z",
    "governed_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "initiated_by": {
      "actor": null,
      "approved_by": null,
      "authenticated_principal": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "enterprise_binding": {
        "tenant_type": "enterprise",
        "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "federation": null,
      "identity_source": "platform-managed",
      "initiated_by": null,
      "subject": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      }
    },
    "operation_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "requirement_snapshot": {
      "authority_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "expires_at": "2026-05-02T10:00:00Z",
      "governed_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "initiator_cannot_approve": true,
      "reason_code": "high_value",
      "required_human_approvals": 1,
      "requirement_key": "withdrawal_approval",
      "source": "policy"
    },
    "resource": "approval",
    "status": "rejected",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Additional user authentication is required. The response includes `code = insufficient_user_authentication`; the `WWW-Authenticate` header carries RFC 9470 `acr_values` and `max_age` parameters that tell the client which step-up assurance to request before retrying.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Balances

### GET /client-accounts/{client_account_id}/balances

**Get client-account balances**

Returns balances for a client account. Pass `?asset=USDC` to fetch a single balance; an omitted or empty asset returns the assets with operating or withdrawal-hold ledger rows. A requested asset without a matching ledger position returns 404. The response preserves ledger availability semantics: `available` excludes held funds, while `held` and `total` remain explicit and total = available + held. Internal conversion holds are excluded from these public totals. The accounts.read grant must cover the account or the call returns 404.

**Required capability:** `accounts.read`

**Authentication:** Bearer token required.

**Parameters:**

- `client_account_id` `string` (path) *(required)*
- `asset` `string` (query)

### client-accounts-balances Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `available` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |
| `held` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |
| `overdraft_headroom` | string or null | No |  |
| `overdraft_limit` | string or null | No |  |
| `overdraft_used` | string or null | No |  |
| `owner_ref` | 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)$` |
| `owner_subtype` | "master_account" / "client_account" / "treasury" | Yes |  |
| `total` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |
| `updated_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))$` |

Additional fields are not accepted.

###### application/json body.items item.overdraft_headroom

At least one alternative must match.

###### application/json body.items item.overdraft_headroom: alternative 1

DecimalString

Type: `string`. pattern: `^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$`

###### application/json body.items item.overdraft_headroom: alternative 2

Type: `null`. 

###### application/json body.items item.overdraft_limit

At least one alternative must match.

###### application/json body.items item.overdraft_limit: alternative 1

DecimalString

Type: `string`. pattern: `^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$`

###### application/json body.items item.overdraft_limit: alternative 2

Type: `null`. 

###### application/json body.items item.overdraft_used

At least one alternative must match.

###### application/json body.items item.overdraft_used: alternative 1

DecimalString

Type: `string`. pattern: `^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$`

###### application/json body.items item.overdraft_used: alternative 2

Type: `null`.


### client-accounts-balances 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.


### client-accounts-balances Response 401 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.


### client-accounts-balances Response 403 schema

Content type: `application/json`.

See [response 401 schema](#client-accounts-balances-response-401-schema).


### client-accounts-balances Response 404 schema

Content type: `application/json`.

See [response 401 schema](#client-accounts-balances-response-401-schema).


### client-accounts-balances Response 500 schema

Content type: `application/json`.

See [response 401 schema](#client-accounts-balances-response-401-schema).


### client-accounts-balances Response 502 schema

Content type: `application/json`.

See [response 400 schema](#client-accounts-balances-response-400-schema).


### client-accounts-balances Response 503 schema

Content type: `application/json`.

See [response 400 schema](#client-accounts-balances-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "asset": "USDC",
        "available": "950.00",
        "held": "50.00",
        "overdraft_headroom": null,
        "overdraft_limit": null,
        "overdraft_used": null,
        "owner_ref": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "owner_subtype": "client_account",
        "total": "1000.00",
        "updated_at": "2026-05-01T10:00:00Z"
      }
    ]
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /master-accounts/{master_account_id}/balances

**Get master-account balances**

Returns balances for a master account. Pass `?asset=USDC` to fetch a single balance; an omitted or empty asset returns the assets with operating or withdrawal-hold ledger rows. A requested asset without a matching ledger position returns 404. The response preserves ledger availability semantics: `available` excludes held funds, while `held` and `total` remain explicit and total = available + held. Internal conversion holds are excluded from these public totals. The accounts.read grant must cover the account or the call returns 404.

**Required capability:** `accounts.read`

**Authentication:** Bearer token required.

**Parameters:**

- `master_account_id` `string` (path) *(required)*
- `asset` `string` (query)

### master-accounts-balances Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `available` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |
| `held` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |
| `overdraft_headroom` | string or null | No |  |
| `overdraft_limit` | string or null | No |  |
| `overdraft_used` | string or null | No |  |
| `owner_ref` | 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)$` |
| `owner_subtype` | "master_account" / "client_account" / "treasury" | Yes |  |
| `total` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |
| `updated_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))$` |

Additional fields are not accepted.

###### application/json body.items item.overdraft_headroom

At least one alternative must match.

###### application/json body.items item.overdraft_headroom: alternative 1

DecimalString

Type: `string`. pattern: `^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$`

###### application/json body.items item.overdraft_headroom: alternative 2

Type: `null`. 

###### application/json body.items item.overdraft_limit

At least one alternative must match.

###### application/json body.items item.overdraft_limit: alternative 1

DecimalString

Type: `string`. pattern: `^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$`

###### application/json body.items item.overdraft_limit: alternative 2

Type: `null`. 

###### application/json body.items item.overdraft_used

At least one alternative must match.

###### application/json body.items item.overdraft_used: alternative 1

DecimalString

Type: `string`. pattern: `^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$`

###### application/json body.items item.overdraft_used: alternative 2

Type: `null`.


### master-accounts-balances 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.


### master-accounts-balances Response 401 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.


### master-accounts-balances Response 403 schema

Content type: `application/json`.

See [response 401 schema](#master-accounts-balances-response-401-schema).


### master-accounts-balances Response 404 schema

Content type: `application/json`.

See [response 401 schema](#master-accounts-balances-response-401-schema).


### master-accounts-balances Response 500 schema

Content type: `application/json`.

See [response 401 schema](#master-accounts-balances-response-401-schema).


### master-accounts-balances Response 502 schema

Content type: `application/json`.

See [response 400 schema](#master-accounts-balances-response-400-schema).


### master-accounts-balances Response 503 schema

Content type: `application/json`.

See [response 400 schema](#master-accounts-balances-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "asset": "USDC",
        "available": "950.00",
        "held": "50.00",
        "overdraft_headroom": "400.00",
        "overdraft_limit": "500.00",
        "overdraft_used": "100.00",
        "owner_ref": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "owner_subtype": "master_account",
        "total": "1000.00",
        "updated_at": "2026-05-01T10:00:00Z"
      }
    ]
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Deposits

### GET /deposits

**List deposits**

**Required capability:** `deposits.read`

**Authentication:** Bearer token required.

**Parameters:**

- `account_ref` `string` (query)
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### deposits-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| 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})$` |
| `admission_hold_reason` | "CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED" or null | Yes |  |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `created_at` | string or string | Yes |  |
| `deposit_instruction_id` | string or null | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "deposit" | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fee_transaction_ids` | string[] or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `funding_endpoint_id` | string or null | Yes |  |
| `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)$` |
| `inbound_attempt_id` | string or null | Yes |  |
| `principal_amount` | object | Yes | No additional fields |
| `principal_transaction_id` | string or null | Yes |  |
| `rail_correlation_ref` | string or null | Yes |  |
| `settled_at` | string or string or null | Yes |  |
| `settlement_ref` | string or null | Yes |  |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.admission_hold_reason

At least one alternative must match.

###### application/json body.items item.admission_hold_reason: alternative 1

Type: `"CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED"`. 

###### application/json body.items item.admission_hold_reason: alternative 2

Type: `null`. 

###### application/json body.items item.approval_ref

At least one alternative must match.

###### application/json body.items item.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body.items item.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body.items item.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body.items item.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body.items item.approval_ref: alternative 2

Type: `null`. 

###### application/json body.items item.compliance_assessment_ref

At least one alternative must match.

###### application/json body.items item.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body.items item.compliance_assessment_ref: alternative 2

Type: `null`. 

###### application/json body.items item.created_at

At least one alternative must match.

###### application/json body.items item.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.created_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.deposit_instruction_id

At least one alternative must match.

###### application/json body.items item.deposit_instruction_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item.deposit_instruction_id: alternative 2

Type: `null`. 

###### application/json body.items item.failure_reason

At least one alternative must match.

###### application/json body.items item.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.items item.failure_reason: alternative 2

Type: `null`. 

###### application/json body.items item.fee_summary

At least one alternative must match.

###### application/json body.items item.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.items item.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body.items item.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.fee_summary: alternative 1.components item.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.

###### application/json body.items item.fee_summary: alternative 1.total

| 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.

###### application/json body.items item.fee_summary: alternative 2

Type: `null`. 

###### application/json body.items item.fee_transaction_ids

At least one alternative must match.

###### application/json body.items item.fee_transaction_ids: alternative 1

Type: `string[]`. 

###### application/json body.items item.fee_transaction_ids: alternative 1 item

Type: `string`. 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)$`

###### application/json body.items item.fee_transaction_ids: alternative 2

Type: `null`. 

###### application/json body.items item.fill_rate

At least one alternative must match.

###### application/json body.items item.fill_rate: alternative 1

Type: `string`. 

###### application/json body.items item.fill_rate: alternative 2

Type: `null`. 

###### application/json body.items item.funding_endpoint_id

At least one alternative must match.

###### application/json body.items item.funding_endpoint_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item.funding_endpoint_id: alternative 2

Type: `null`. 

###### application/json body.items item.inbound_attempt_id

At least one alternative must match.

###### application/json body.items item.inbound_attempt_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item.inbound_attempt_id: alternative 2

Type: `null`. 

###### application/json body.items item.principal_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.

###### application/json body.items item.principal_transaction_id

At least one alternative must match.

###### application/json body.items item.principal_transaction_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item.principal_transaction_id: alternative 2

Type: `null`. 

###### application/json body.items item.rail_correlation_ref

At least one alternative must match.

###### application/json body.items item.rail_correlation_ref: alternative 1

Type: `string`. minLength: 1

###### application/json body.items item.rail_correlation_ref: alternative 2

Type: `null`. 

###### application/json body.items item.settled_at

At least one alternative must match.

###### application/json body.items item.settled_at: alternative 1

At least one alternative must match.

###### application/json body.items item.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.settled_at: alternative 2

Type: `null`. 

###### application/json body.items item.settlement_ref

At least one alternative must match.

###### application/json body.items item.settlement_ref: alternative 1

Type: `string`. minLength: 1

###### application/json body.items item.settlement_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.actor

At least one alternative must match.

###### application/json body.items item.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.approved_by

At least one alternative must match.

###### application/json body.items item.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.items item.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.items item.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.federation

At least one alternative must match.

###### application/json body.items item.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body.items item.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.subject

At least one alternative must match.

###### application/json body.items item.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.subject: alternative 2

Type: `null`. 

###### application/json body.items item.updated_at

At least one alternative must match.

###### application/json body.items item.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.updated_at: alternative 2

Type: `string`. format: date-time

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. 

###### application/json body.next_page_token: alternative 2

Type: `null`.


### deposits-list 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.


### deposits-list Response 401 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.


### deposits-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#deposits-list-response-401-schema).


### deposits-list Response 404 schema

Content type: `application/json`.

See [response 401 schema](#deposits-list-response-401-schema).


### deposits-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#deposits-list-response-401-schema).


### deposits-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#deposits-list-response-400-schema).


### deposits-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#deposits-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "admission_hold_reason": null,
        "approval_ref": null,
        "created_at": "2026-05-01T10:00:00Z",
        "deposit_instruction_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "failure_reason": null,
        "family": "deposit",
        "fee_summary": {
          "components": [
            {
              "amount": {
                "currency": "USDC",
                "value": "1.00"
              },
              "kind": "network_fee"
            }
          ],
          "total": {
            "currency": "USDC",
            "value": "1.00"
          }
        },
        "fee_transaction_ids": [
          "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
        ],
        "fill_rate": null,
        "funding_endpoint_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "inbound_attempt_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "principal_amount": {
          "currency": "USDC",
          "value": "250.00"
        },
        "principal_transaction_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "rail_correlation_ref": "TXN-0001",
        "settled_at": "2026-05-01T10:00:00Z",
        "settlement_ref": "SETTLE-0001",
        "status": "settled",
        "subject_attribution": {
          "actor": null,
          "approved_by": null,
          "authenticated_principal": {
            "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
            "kind": "user",
            "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
          },
          "enterprise_binding": {
            "tenant_type": "enterprise",
            "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
          },
          "federation": null,
          "identity_source": "platform-managed",
          "initiated_by": null,
          "subject": {
            "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
            "kind": "user",
            "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
          }
        },
        "updated_at": "2026-05-01T10:00:00Z"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /deposits/{deposit_id}

**Get deposit**

**Required capability:** `deposits.read`

**Authentication:** Bearer token required.

**Parameters:**

- `deposit_id` `string` (path) *(required)*

### deposits-get Response 200 schema

Content type: `application/json`.

#### application/json body

| 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})$` |
| `admission_hold_reason` | "CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED" or null | Yes |  |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `created_at` | string or string | Yes |  |
| `deposit_instruction_id` | string or null | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "deposit" | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fee_transaction_ids` | string[] or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `funding_endpoint_id` | string or null | Yes |  |
| `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)$` |
| `inbound_attempt_id` | string or null | Yes |  |
| `principal_amount` | object | Yes | No additional fields |
| `principal_transaction_id` | string or null | Yes |  |
| `rail_correlation_ref` | string or null | Yes |  |
| `settled_at` | string or string or null | Yes |  |
| `settlement_ref` | string or null | Yes |  |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

##### application/json body.admission_hold_reason

At least one alternative must match.

###### application/json body.admission_hold_reason: alternative 1

Type: `"CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED"`. 

###### application/json body.admission_hold_reason: alternative 2

Type: `null`. 

##### application/json body.approval_ref

At least one alternative must match.

###### application/json body.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body.approval_ref: alternative 2

Type: `null`. 

##### application/json body.compliance_assessment_ref

At least one alternative must match.

###### application/json body.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body.compliance_assessment_ref: alternative 2

Type: `null`. 

##### application/json body.created_at

At least one alternative must match.

###### application/json body.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.created_at: alternative 2

Type: `string`. format: date-time

##### application/json body.deposit_instruction_id

At least one alternative must match.

###### application/json body.deposit_instruction_id: alternative 1

Type: `string`. 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)$`

###### application/json body.deposit_instruction_id: alternative 2

Type: `null`. 

##### application/json body.failure_reason

At least one alternative must match.

###### application/json body.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.failure_reason: alternative 2

Type: `null`. 

##### application/json body.fee_summary

At least one alternative must match.

###### application/json body.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body.fee_summary: alternative 1.components item.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.

###### application/json body.fee_summary: alternative 1.total

| 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.

###### application/json body.fee_summary: alternative 2

Type: `null`. 

##### application/json body.fee_transaction_ids

At least one alternative must match.

###### application/json body.fee_transaction_ids: alternative 1

Type: `string[]`. 

###### application/json body.fee_transaction_ids: alternative 1 item

Type: `string`. 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)$`

###### application/json body.fee_transaction_ids: alternative 2

Type: `null`. 

##### application/json body.fill_rate

At least one alternative must match.

###### application/json body.fill_rate: alternative 1

Type: `string`. 

###### application/json body.fill_rate: alternative 2

Type: `null`. 

##### application/json body.funding_endpoint_id

At least one alternative must match.

###### application/json body.funding_endpoint_id: alternative 1

Type: `string`. 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)$`

###### application/json body.funding_endpoint_id: alternative 2

Type: `null`. 

##### application/json body.inbound_attempt_id

At least one alternative must match.

###### application/json body.inbound_attempt_id: alternative 1

Type: `string`. 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)$`

###### application/json body.inbound_attempt_id: alternative 2

Type: `null`. 

##### application/json body.principal_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.

##### application/json body.principal_transaction_id

At least one alternative must match.

###### application/json body.principal_transaction_id: alternative 1

Type: `string`. 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)$`

###### application/json body.principal_transaction_id: alternative 2

Type: `null`. 

##### application/json body.rail_correlation_ref

At least one alternative must match.

###### application/json body.rail_correlation_ref: alternative 1

Type: `string`. minLength: 1

###### application/json body.rail_correlation_ref: alternative 2

Type: `null`. 

##### application/json body.settled_at

At least one alternative must match.

###### application/json body.settled_at: alternative 1

At least one alternative must match.

###### application/json body.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.settled_at: alternative 2

Type: `null`. 

##### application/json body.settlement_ref

At least one alternative must match.

###### application/json body.settlement_ref: alternative 1

Type: `string`. minLength: 1

###### application/json body.settlement_ref: alternative 2

Type: `null`. 

##### application/json body.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.federation

At least one alternative must match.

###### application/json body.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject: alternative 2

Type: `null`. 

##### application/json body.updated_at

At least one alternative must match.

###### application/json body.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.updated_at: alternative 2

Type: `string`. format: date-time


### deposits-get 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.


### deposits-get Response 401 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.


### deposits-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#deposits-get-response-401-schema).


### deposits-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#deposits-get-response-401-schema).


### deposits-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#deposits-get-response-401-schema).


### deposits-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#deposits-get-response-400-schema).


### deposits-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#deposits-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "admission_hold_reason": null,
    "approval_ref": null,
    "created_at": "2026-05-01T10:00:00Z",
    "deposit_instruction_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "failure_reason": null,
    "family": "deposit",
    "fee_summary": {
      "components": [
        {
          "amount": {
            "currency": "USDC",
            "value": "1.00"
          },
          "kind": "network_fee"
        }
      ],
      "total": {
        "currency": "USDC",
        "value": "1.00"
      }
    },
    "fee_transaction_ids": [
      "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
    ],
    "fill_rate": null,
    "funding_endpoint_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "inbound_attempt_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "principal_amount": {
      "currency": "USDC",
      "value": "250.00"
    },
    "principal_transaction_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "rail_correlation_ref": "TXN-0001",
    "settled_at": "2026-05-01T10:00:00Z",
    "settlement_ref": "SETTLE-0001",
    "status": "settled",
    "subject_attribution": {
      "actor": null,
      "approved_by": null,
      "authenticated_principal": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "enterprise_binding": {
        "tenant_type": "enterprise",
        "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "federation": null,
      "identity_source": "platform-managed",
      "initiated_by": null,
      "subject": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      }
    },
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Deposit Instructions

### GET /deposit-instructions

**List deposit instructions**

Lists deposit instructions for the selected rail. Crypto instructions route to the custody rails backend; fiat instructions are delegated to `fiat-rails-service` and scoped to the supplied `account_ref`. On fiat resources, `fiat_routing.bank_details` carries the receive details a provider issues — `provider_payment_reference` (`required` says whether a payment without it can fail), `account_holder_address`, `bank_address` and `correspondent_bank` — always present, `null` when the provider issued none. `provider_payment_reference` is the provider's own reference, separate from the pooled ISO 11649 `reference`.

**Required capability:** `deposit_instructions.read`

**Authentication:** Bearer token required.

**Parameters:**

- `account_ref` `string` (query) *(required)*
- `funding_endpoint` `string` (query)
- `rail_class` `string` (query) *(required)*
- `asset` `string` (query)
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### deposit-instructions-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| 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})$` |
| `asset` | string or null | No |  |
| `created_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))$` |
| `crypto_routing` | object or null | No |  |
| `expires_at` | string or null | No |  |
| `fiat_routing` | object or null | No |  |
| `funding_endpoint_id` | string or null | Yes |  |
| `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)$` |
| `rail_class` | "fiat" / "crypto" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

###### application/json body.items item.asset

At least one alternative must match.

###### application/json body.items item.asset: alternative 1

Currency code (ISO-4217 or on-chain ticker)

Type: `string`. pattern: `^[A-Z0-9]{1,16}$`

###### application/json body.items item.asset: alternative 2

Type: `null`. 

###### application/json body.items item.crypto_routing

At least one alternative must match.

###### application/json body.items item.crypto_routing: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `endpoint` | object | Yes | No additional fields |
| `network` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.items item.crypto_routing: alternative 1.endpoint

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `address` | string | Yes | minLength: 1; maxLength: 256 |
| `memo` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.crypto_routing: alternative 1.endpoint.memo

At least one alternative must match.

###### application/json body.items item.crypto_routing: alternative 1.endpoint.memo: alternative 1

Type: `string`. 

###### application/json body.items item.crypto_routing: alternative 1.endpoint.memo: alternative 2

Type: `null`. 

###### application/json body.items item.crypto_routing: alternative 2

Type: `null`. 

###### application/json body.items item.expires_at

At least one alternative must match.

###### application/json body.items item.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.expires_at: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `bank_details` | object or object or null | No |  |
| `fiat_rail` | "sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire" | Yes |  |
| `reference` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_details

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1

Exactly one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_address` | object or null | No |  |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `correspondent_bank` | object or null | No |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `iban` | string | Yes | minLength: 1; maxLength: 34 |
| `provider_payment_reference` | object or null | No |  |
| `scheme` | "iban" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.region

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.region

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_name

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_name: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bic

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bic: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string or null | Yes |  |
| `address` | object or null | Yes |  |
| `bic` | string | Yes | minLength: 1; maxLength: 11 |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.account_number

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.account_number: alternative 1

Type: `string`. minLength: 1; maxLength: 64

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.account_number: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.region

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.provider_payment_reference

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.provider_payment_reference: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `required` | boolean | Yes |  |
| `value` | string | Yes | minLength: 1; maxLength: 140 |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.provider_payment_reference: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_address` | object or null | No |  |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string | Yes | minLength: 1; maxLength: 64 |
| `account_type` | "checking" / "savings" or null | No | Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept. |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `correspondent_bank` | object or null | No |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `provider_payment_reference` | object or null | No |  |
| `routing_codes` | object[] | Yes | minItems: 1; maxItems: 16 |
| `scheme` | "local_account" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.region

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_type

Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept.

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_type: alternative 1

Type: `"checking" / "savings"`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_type: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.region

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_name

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_name: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bic

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bic: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string or null | Yes |  |
| `address` | object or null | Yes |  |
| `bic` | string | Yes | minLength: 1; maxLength: 11 |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.account_number

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.account_number: alternative 1

Type: `string`. minLength: 1; maxLength: 64

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.account_number: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.region

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.provider_payment_reference

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.provider_payment_reference: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `required` | boolean | Yes |  |
| `value` | string | Yes | minLength: 1; maxLength: 140 |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.provider_payment_reference: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.routing_codes

Type: `object[]`. minItems: 1; maxItems: 16

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.routing_codes item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `type` | string | Yes | minLength: 1; maxLength: 64 |
| `value` | string | Yes | minLength: 1; maxLength: 64 |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.reference

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.reference: alternative 1

Type: `string`. 

###### application/json body.items item.fiat_routing: alternative 1.reference: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 2

Type: `null`. 

###### application/json body.items item.funding_endpoint_id

At least one alternative must match.

###### application/json body.items item.funding_endpoint_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item.funding_endpoint_id: alternative 2

Type: `null`. 

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. minLength: 1

###### application/json body.next_page_token: alternative 2

Type: `null`.


### deposit-instructions-list 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.


### deposit-instructions-list Response 401 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.


### deposit-instructions-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#deposit-instructions-list-response-401-schema).


### deposit-instructions-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#deposit-instructions-list-response-401-schema).


### deposit-instructions-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#deposit-instructions-list-response-400-schema).


### deposit-instructions-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#deposit-instructions-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "asset": "USDC",
        "created_at": "2026-05-01T10:00:00Z",
        "crypto_routing": {
          "asset": "USDC",
          "endpoint": {
            "address": "0xAbCd1234567890AbCd1234567890AbCd12345678",
            "memo": null
          },
          "network": "ethereum"
        },
        "expires_at": null,
        "fiat_routing": null,
        "funding_endpoint_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "rail_class": "crypto",
        "updated_at": "2026-05-01T10:00:00Z"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /deposit-instructions

**Create deposit instruction**

Creates a fiat deposit instruction against the pooled fiat route (delegated to `fiat-rails-service`). Crypto is rejected: crypto deposit addresses are minted through funding-endpoint provisioning. `funding_endpoint_id` optionally links a previously provisioned endpoint; null mints a standalone instruction. This is a pooled payment-reference route: virtual-account routes such as an individually provisioned CVU refuse instruction creation with 422 and reason `fiat_unsupported_mode`; use the funding endpoint itself for that route. The pooled route owner is derived server-side and never accepted from the caller. The instruction carries the payment reference that makes pooled coordinates usable, so every request — standalone or linked to an endpoint — is first checked for account admission, before the route availability, the route owner or the endpoint mode is resolved: the account must not be suspended or closed; a client account needs a verified client and an enterprise master account a verified enterprise, and the enterprise behind the account (the parent of the client, or the owner of the master account) must be operational and unrestricted (one still being admitted, offboarding, terminated or restricted is refused); a master account owned by a platform operator is decided on its own status alone. A refused account returns `422` with `code = not_admissible`, `data.reason` one of `CLIENT_NOT_VERIFIED`, `ENTERPRISE_NOT_VERIFIED`, `ENTERPRISE_NOT_OPERATIONAL`, `ENTERPRISE_RESTRICTED`, `ACCOUNT_SUSPENDED`, `ACCOUNT_CLOSED`, `CLIENT_SUSPENDED`, `CLIENT_CLOSED` and `data.source` naming the check that refused (`verification`, `lifecycle`); when admission cannot be checked the request returns `503 temporarily_unavailable`. Neither response creates an instruction. An idempotent retry is checked again, so an account refused since its first request gets the refusal instead of the stored instruction. Idempotent on the required `Idempotency-Key` header; an `idempotency_key` body field is rejected. On fiat resources, `fiat_routing.bank_details` carries the receive details a provider issues — `provider_payment_reference` (`required` says whether a payment without it can fail), `account_holder_address`, `bank_address` and `correspondent_bank` — always present, `null` when the provider issued none. `provider_payment_reference` is the provider's own reference, separate from the pooled ISO 11649 `reference`.

**Required capability:** `deposit_instructions.create`

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) *(required)* — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| 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})$` |
| `funding_endpoint_id` | string or null | No |  |
| `rail_class` | "fiat" | Yes |  |
| `routing` | object | Yes | No additional fields |

Additional fields are not accepted.

#### Request body schema.funding_endpoint_id

At least one alternative must match.

##### Request body schema.funding_endpoint_id: alternative 1

Type: `string`. 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)$`

##### Request body schema.funding_endpoint_id: alternative 2

Type: `null`. 

#### Request body schema.routing

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `bank_details` | object or object or null | No |  |
| `fiat_rail` | "sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire" | Yes |  |
| `reference` | string or null | No |  |

Additional fields are not accepted.

##### Request body schema.routing.bank_details

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1

Exactly one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_address` | object or null | No |  |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `correspondent_bank` | object or null | No |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `iban` | string | Yes | minLength: 1; maxLength: 34 |
| `provider_payment_reference` | object or null | No |  |
| `scheme` | "iban" | Yes |  |

Additional fields are not accepted.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.account_holder_address

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### Request body schema.routing.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema.routing.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.postal_code

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### Request body schema.routing.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.region

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema.routing.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.region: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 1.account_holder_address: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bank_address: alternative 1.postal_code

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bank_address: alternative 1.region

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bank_address: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bank_name

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bank_name: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bic

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bic: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string or null | Yes |  |
| `address` | object or null | Yes |  |
| `bic` | string | Yes | minLength: 1; maxLength: 11 |

Additional fields are not accepted.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.account_number

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.account_number: alternative 1

Type: `string`. minLength: 1; maxLength: 64

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.account_number: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.postal_code

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.region

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.region: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 1.provider_payment_reference

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.provider_payment_reference: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `required` | boolean | Yes |  |
| `value` | string | Yes | minLength: 1; maxLength: 140 |

Additional fields are not accepted.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.provider_payment_reference: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_address` | object or null | No |  |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string | Yes | minLength: 1; maxLength: 64 |
| `account_type` | "checking" / "savings" or null | No | Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept. |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `correspondent_bank` | object or null | No |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `provider_payment_reference` | object or null | No |  |
| `routing_codes` | object[] | Yes | minItems: 1; maxItems: 16 |
| `scheme` | "local_account" | Yes |  |

Additional fields are not accepted.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.account_holder_address

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### Request body schema.routing.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema.routing.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.postal_code

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### Request body schema.routing.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.region

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema.routing.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.region: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.account_holder_address: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.account_type

Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept.

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.account_type: alternative 1

Type: `"checking" / "savings"`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.account_type: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bank_address: alternative 1.postal_code

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bank_address: alternative 1.region

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bank_address: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bank_name

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bank_name: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bic

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bic: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string or null | Yes |  |
| `address` | object or null | Yes |  |
| `bic` | string | Yes | minLength: 1; maxLength: 11 |

Additional fields are not accepted.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.account_number

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.account_number: alternative 1

Type: `string`. minLength: 1; maxLength: 64

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.account_number: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.postal_code

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.region

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.region: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.provider_payment_reference

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.provider_payment_reference: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `required` | boolean | Yes |  |
| `value` | string | Yes | minLength: 1; maxLength: 140 |

Additional fields are not accepted.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.provider_payment_reference: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.routing_codes

Type: `object[]`. minItems: 1; maxItems: 16

###### Request body schema.routing.bank_details: alternative 1: alternative 2.routing_codes item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `type` | string | Yes | minLength: 1; maxLength: 64 |
| `value` | string | Yes | minLength: 1; maxLength: 64 |

Additional fields are not accepted.

###### Request body schema.routing.bank_details: alternative 2

Type: `null`. 

##### Request body schema.routing.reference

At least one alternative must match.

###### Request body schema.routing.reference: alternative 1

Type: `string`. 

###### Request body schema.routing.reference: alternative 2

Type: `null`.

**Request example:**

```json
{
  "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "funding_endpoint_id": null,
  "rail_class": "fiat",
  "routing": {
    "asset": "EUR",
    "fiat_rail": "sepa_credit_transfer"
  }
}
```

### deposit-instructions-create Response 201 schema

Content type: `application/json`.

#### application/json body

| 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})$` |
| `asset` | string or null | No |  |
| `created_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))$` |
| `crypto_routing` | object or null | No |  |
| `expires_at` | string or null | No |  |
| `fiat_routing` | object or null | No |  |
| `funding_endpoint_id` | string or null | Yes |  |
| `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)$` |
| `rail_class` | "fiat" / "crypto" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.asset

At least one alternative must match.

###### application/json body.asset: alternative 1

Currency code (ISO-4217 or on-chain ticker)

Type: `string`. pattern: `^[A-Z0-9]{1,16}$`

###### application/json body.asset: alternative 2

Type: `null`. 

##### application/json body.crypto_routing

At least one alternative must match.

###### application/json body.crypto_routing: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `endpoint` | object | Yes | No additional fields |
| `network` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.crypto_routing: alternative 1.endpoint

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `address` | string | Yes | minLength: 1; maxLength: 256 |
| `memo` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.crypto_routing: alternative 1.endpoint.memo

At least one alternative must match.

###### application/json body.crypto_routing: alternative 1.endpoint.memo: alternative 1

Type: `string`. 

###### application/json body.crypto_routing: alternative 1.endpoint.memo: alternative 2

Type: `null`. 

###### application/json body.crypto_routing: alternative 2

Type: `null`. 

##### application/json body.expires_at

At least one alternative must match.

###### application/json body.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.expires_at: alternative 2

Type: `null`. 

##### application/json body.fiat_routing

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `bank_details` | object or object or null | No |  |
| `fiat_rail` | "sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire" | Yes |  |
| `reference` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1

Exactly one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_address` | object or null | No |  |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `correspondent_bank` | object or null | No |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `iban` | string | Yes | minLength: 1; maxLength: 34 |
| `provider_payment_reference` | object or null | No |  |
| `scheme` | "iban" | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_name

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_name: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bic

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bic: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string or null | Yes |  |
| `address` | object or null | Yes |  |
| `bic` | string | Yes | minLength: 1; maxLength: 11 |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.account_number

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.account_number: alternative 1

Type: `string`. minLength: 1; maxLength: 64

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.account_number: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.provider_payment_reference

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.provider_payment_reference: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `required` | boolean | Yes |  |
| `value` | string | Yes | minLength: 1; maxLength: 140 |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.provider_payment_reference: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_address` | object or null | No |  |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string | Yes | minLength: 1; maxLength: 64 |
| `account_type` | "checking" / "savings" or null | No | Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept. |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `correspondent_bank` | object or null | No |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `provider_payment_reference` | object or null | No |  |
| `routing_codes` | object[] | Yes | minItems: 1; maxItems: 16 |
| `scheme` | "local_account" | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_type

Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_type: alternative 1

Type: `"checking" / "savings"`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_type: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_name

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_name: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bic

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bic: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string or null | Yes |  |
| `address` | object or null | Yes |  |
| `bic` | string | Yes | minLength: 1; maxLength: 11 |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.account_number

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.account_number: alternative 1

Type: `string`. minLength: 1; maxLength: 64

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.account_number: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.provider_payment_reference

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.provider_payment_reference: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `required` | boolean | Yes |  |
| `value` | string | Yes | minLength: 1; maxLength: 140 |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.provider_payment_reference: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.routing_codes

Type: `object[]`. minItems: 1; maxItems: 16

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.routing_codes item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `type` | string | Yes | minLength: 1; maxLength: 64 |
| `value` | string | Yes | minLength: 1; maxLength: 64 |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.reference

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.reference: alternative 1

Type: `string`. 

###### application/json body.fiat_routing: alternative 1.reference: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 2

Type: `null`. 

##### application/json body.funding_endpoint_id

At least one alternative must match.

###### application/json body.funding_endpoint_id: alternative 1

Type: `string`. 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)$`

###### application/json body.funding_endpoint_id: alternative 2

Type: `null`.


### deposit-instructions-create 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.


### deposit-instructions-create Response 401 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.


### deposit-instructions-create Response 403 schema

Content type: `application/json`.

See [response 401 schema](#deposit-instructions-create-response-401-schema).


### deposit-instructions-create Response 404 schema

Content type: `application/json`.

See [response 401 schema](#deposit-instructions-create-response-401-schema).


### deposit-instructions-create Response 409 schema

Content type: `application/json`.

See [response 401 schema](#deposit-instructions-create-response-401-schema).


### deposit-instructions-create Response 422 schema

Content type: `application/json`.

See [response 401 schema](#deposit-instructions-create-response-401-schema).


### deposit-instructions-create Response 500 schema

Content type: `application/json`.

See [response 401 schema](#deposit-instructions-create-response-401-schema).


### deposit-instructions-create Response 502 schema

Content type: `application/json`.

See [response 400 schema](#deposit-instructions-create-response-400-schema).


### deposit-instructions-create Response 503 schema

Content type: `application/json`.

See [response 400 schema](#deposit-instructions-create-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "asset": "EUR",
    "created_at": "2026-05-01T10:00:00Z",
    "crypto_routing": null,
    "expires_at": null,
    "fiat_routing": {
      "asset": "EUR",
      "bank_details": {
        "account_holder_address": null,
        "account_holder_name": "Example Treasury",
        "bank_address": null,
        "bank_name": "Demo Bank",
        "bic": "COBADEFFXXX",
        "correspondent_bank": null,
        "country": "DE",
        "iban": "DE89370400440532013000",
        "provider_payment_reference": null,
        "scheme": "iban"
      },
      "fiat_rail": "sepa_credit_transfer",
      "reference": "RF18539007547034"
    },
    "funding_endpoint_id": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "rail_class": "fiat",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `422` — The request cannot be processed under the resource or route contract. Depending on the endpoint, code can be not_admissible or unsupported_currency; inspect the documented code and data.reason.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /deposit-instructions/{deposit_instruction_id}

**Get deposit instruction**

Reads a deposit instruction by id. The `rail_class` query parameter is required so edge can route directly to the selected backend. Fiat reads also require `account_ref` because fiat deposit instructions are account-scoped; they are delegated to `fiat-rails-service`, and unknown or out-of-scope fiat ids return `resource_not_found`. On fiat resources, `fiat_routing.bank_details` carries the receive details a provider issues — `provider_payment_reference` (`required` says whether a payment without it can fail), `account_holder_address`, `bank_address` and `correspondent_bank` — always present, `null` when the provider issued none. `provider_payment_reference` is the provider's own reference, separate from the pooled ISO 11649 `reference`.

**Required capability:** `deposit_instructions.read`

**Authentication:** Bearer token required.

**Parameters:**

- `deposit_instruction_id` `string` (path) *(required)*
- `rail_class` `string` (query) *(required)*
- `account_ref` `string` (query)

### deposit-instructions-get Response 200 schema

Content type: `application/json`.

#### application/json body

| 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})$` |
| `asset` | string or null | No |  |
| `created_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))$` |
| `crypto_routing` | object or null | No |  |
| `expires_at` | string or null | No |  |
| `fiat_routing` | object or null | No |  |
| `funding_endpoint_id` | string or null | Yes |  |
| `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)$` |
| `rail_class` | "fiat" / "crypto" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.asset

At least one alternative must match.

###### application/json body.asset: alternative 1

Currency code (ISO-4217 or on-chain ticker)

Type: `string`. pattern: `^[A-Z0-9]{1,16}$`

###### application/json body.asset: alternative 2

Type: `null`. 

##### application/json body.crypto_routing

At least one alternative must match.

###### application/json body.crypto_routing: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `endpoint` | object | Yes | No additional fields |
| `network` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.crypto_routing: alternative 1.endpoint

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `address` | string | Yes | minLength: 1; maxLength: 256 |
| `memo` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.crypto_routing: alternative 1.endpoint.memo

At least one alternative must match.

###### application/json body.crypto_routing: alternative 1.endpoint.memo: alternative 1

Type: `string`. 

###### application/json body.crypto_routing: alternative 1.endpoint.memo: alternative 2

Type: `null`. 

###### application/json body.crypto_routing: alternative 2

Type: `null`. 

##### application/json body.expires_at

At least one alternative must match.

###### application/json body.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.expires_at: alternative 2

Type: `null`. 

##### application/json body.fiat_routing

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `bank_details` | object or object or null | No |  |
| `fiat_rail` | "sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire" | Yes |  |
| `reference` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1

Exactly one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_address` | object or null | No |  |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `correspondent_bank` | object or null | No |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `iban` | string | Yes | minLength: 1; maxLength: 34 |
| `provider_payment_reference` | object or null | No |  |
| `scheme` | "iban" | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_name

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_name: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bic

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bic: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string or null | Yes |  |
| `address` | object or null | Yes |  |
| `bic` | string | Yes | minLength: 1; maxLength: 11 |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.account_number

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.account_number: alternative 1

Type: `string`. minLength: 1; maxLength: 64

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.account_number: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.provider_payment_reference

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.provider_payment_reference: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `required` | boolean | Yes |  |
| `value` | string | Yes | minLength: 1; maxLength: 140 |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.provider_payment_reference: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_address` | object or null | No |  |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string | Yes | minLength: 1; maxLength: 64 |
| `account_type` | "checking" / "savings" or null | No | Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept. |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `correspondent_bank` | object or null | No |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `provider_payment_reference` | object or null | No |  |
| `routing_codes` | object[] | Yes | minItems: 1; maxItems: 16 |
| `scheme` | "local_account" | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_type

Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_type: alternative 1

Type: `"checking" / "savings"`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_type: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_name

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_name: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bic

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bic: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string or null | Yes |  |
| `address` | object or null | Yes |  |
| `bic` | string | Yes | minLength: 1; maxLength: 11 |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.account_number

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.account_number: alternative 1

Type: `string`. minLength: 1; maxLength: 64

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.account_number: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.provider_payment_reference

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.provider_payment_reference: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `required` | boolean | Yes |  |
| `value` | string | Yes | minLength: 1; maxLength: 140 |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.provider_payment_reference: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.routing_codes

Type: `object[]`. minItems: 1; maxItems: 16

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.routing_codes item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `type` | string | Yes | minLength: 1; maxLength: 64 |
| `value` | string | Yes | minLength: 1; maxLength: 64 |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.reference

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.reference: alternative 1

Type: `string`. 

###### application/json body.fiat_routing: alternative 1.reference: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 2

Type: `null`. 

##### application/json body.funding_endpoint_id

At least one alternative must match.

###### application/json body.funding_endpoint_id: alternative 1

Type: `string`. 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)$`

###### application/json body.funding_endpoint_id: alternative 2

Type: `null`.


### deposit-instructions-get 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.


### deposit-instructions-get Response 401 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.


### deposit-instructions-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#deposit-instructions-get-response-401-schema).


### deposit-instructions-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#deposit-instructions-get-response-401-schema).


### deposit-instructions-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#deposit-instructions-get-response-401-schema).


### deposit-instructions-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#deposit-instructions-get-response-400-schema).


### deposit-instructions-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#deposit-instructions-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "asset": "USDC",
    "created_at": "2026-05-01T10:00:00Z",
    "crypto_routing": {
      "asset": "USDC",
      "endpoint": {
        "address": "0xAbCd1234567890AbCd1234567890AbCd12345678",
        "memo": null
      },
      "network": "ethereum"
    },
    "expires_at": null,
    "fiat_routing": null,
    "funding_endpoint_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "rail_class": "crypto",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Funding Endpoints

### GET /funding-endpoints

**List funding endpoints**

Lists deposit-side endpoints for the selected rail. Crypto endpoints route to the custody rails backend; fiat endpoints are delegated to `fiat-rails-service` and scoped to the supplied `account_ref`. On fiat resources, `fiat_routing.bank_details` carries the receive details a provider issues — `provider_payment_reference` (`required` says whether a payment without it can fail), `account_holder_address`, `bank_address` and `correspondent_bank` — always present, `null` when the provider issued none. `provider_payment_reference` is the provider's own reference, separate from the pooled ISO 11649 `reference`.

**Required capability:** `funding_endpoints.read`

**Authentication:** Bearer token required.

**Parameters:**

- `account_ref` `string` (query) *(required)*
- `rail_class` `string` (query) *(required)*
- `status` `string` (query)
- `asset` `string` (query)
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### funding-endpoints-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| 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})$` |
| `asset` | string or null | No |  |
| `created_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))$` |
| `crypto_routing` | object or null | No |  |
| `failure` | object or null | No |  |
| `fiat_rail` | "sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire" or null | No |  |
| `fiat_routing` | object or null | No |  |
| `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)$` |
| `network` | string or null | No |  |
| `rail_class` | "fiat" / "crypto" | Yes |  |
| `status` | "provisioning" / "active" / "failed" / "disabled" / "retired" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

###### application/json body.items item.asset

At least one alternative must match.

###### application/json body.items item.asset: alternative 1

Currency code (ISO-4217 or on-chain ticker)

Type: `string`. pattern: `^[A-Z0-9]{1,16}$`

###### application/json body.items item.asset: alternative 2

Type: `null`. 

###### application/json body.items item.crypto_routing

At least one alternative must match.

###### application/json body.items item.crypto_routing: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `endpoint` | object | No | No additional fields |
| `network` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.items item.crypto_routing: alternative 1.endpoint

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `address` | string | Yes | minLength: 1; maxLength: 256 |
| `memo` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.crypto_routing: alternative 1.endpoint.memo

At least one alternative must match.

###### application/json body.items item.crypto_routing: alternative 1.endpoint.memo: alternative 1

Type: `string`. 

###### application/json body.items item.crypto_routing: alternative 1.endpoint.memo: alternative 2

Type: `null`. 

###### application/json body.items item.crypto_routing: alternative 2

Type: `null`. 

###### application/json body.items item.failure

At least one alternative must match.

###### application/json body.items item.failure: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `code` | "party_profile_incomplete" / "party_not_supported" / "party_already_provisioned" / "provider_rejected" / "manual_review_required" / "provisioning_unavailable" | Yes |  |
| `retryable` | boolean | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.failure: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_rail

At least one alternative must match.

###### application/json body.items item.fiat_rail: alternative 1

Type: `"sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire"`. 

###### application/json body.items item.fiat_rail: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `attribution_mode` | "virtual_account" / "payment_reference" | Yes |  |
| `bank_details` | object or object or null | No |  |
| `beneficiary_name` | string or null | No |  |
| `fiat_rail` | "sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire" | Yes |  |
| `reference` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_details

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1

Exactly one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_address` | object or null | No |  |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `correspondent_bank` | object or null | No |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `iban` | string | Yes | minLength: 1; maxLength: 34 |
| `provider_payment_reference` | object or null | No |  |
| `scheme` | "iban" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.region

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.region

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_name

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_name: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bic

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bic: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string or null | Yes |  |
| `address` | object or null | Yes |  |
| `bic` | string | Yes | minLength: 1; maxLength: 11 |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.account_number

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.account_number: alternative 1

Type: `string`. minLength: 1; maxLength: 64

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.account_number: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.region

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.provider_payment_reference

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.provider_payment_reference: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `required` | boolean | Yes |  |
| `value` | string | Yes | minLength: 1; maxLength: 140 |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.provider_payment_reference: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_address` | object or null | No |  |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string | Yes | minLength: 1; maxLength: 64 |
| `account_type` | "checking" / "savings" or null | No | Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept. |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `correspondent_bank` | object or null | No |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `provider_payment_reference` | object or null | No |  |
| `routing_codes` | object[] | Yes | minItems: 1; maxItems: 16 |
| `scheme` | "local_account" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.region

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_type

Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept.

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_type: alternative 1

Type: `"checking" / "savings"`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_type: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.region

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_name

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_name: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bic

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bic: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string or null | Yes |  |
| `address` | object or null | Yes |  |
| `bic` | string | Yes | minLength: 1; maxLength: 11 |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.account_number

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.account_number: alternative 1

Type: `string`. minLength: 1; maxLength: 64

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.account_number: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.region

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.provider_payment_reference

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.provider_payment_reference: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `required` | boolean | Yes |  |
| `value` | string | Yes | minLength: 1; maxLength: 140 |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.provider_payment_reference: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.routing_codes

Type: `object[]`. minItems: 1; maxItems: 16

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.routing_codes item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `type` | string | Yes | minLength: 1; maxLength: 64 |
| `value` | string | Yes | minLength: 1; maxLength: 64 |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_details: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.beneficiary_name

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.beneficiary_name: alternative 1

Type: `string`. 

###### application/json body.items item.fiat_routing: alternative 1.beneficiary_name: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.reference

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.reference: alternative 1

Type: `string`. 

###### application/json body.items item.fiat_routing: alternative 1.reference: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 2

Type: `null`. 

###### application/json body.items item.network

At least one alternative must match.

###### application/json body.items item.network: alternative 1

Type: `string`. 

###### application/json body.items item.network: alternative 2

Type: `null`. 

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. minLength: 1

###### application/json body.next_page_token: alternative 2

Type: `null`.


### funding-endpoints-list 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.


### funding-endpoints-list Response 401 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.


### funding-endpoints-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#funding-endpoints-list-response-401-schema).


### funding-endpoints-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#funding-endpoints-list-response-401-schema).


### funding-endpoints-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#funding-endpoints-list-response-400-schema).


### funding-endpoints-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#funding-endpoints-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "asset": "USDC",
        "created_at": "2026-05-01T10:00:00Z",
        "crypto_routing": {
          "asset": "USDC",
          "endpoint": {
            "address": "0xAbCd1234567890AbCd1234567890AbCd12345678",
            "memo": null
          },
          "network": "ethereum"
        },
        "fiat_rail": null,
        "fiat_routing": null,
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "network": "ethereum",
        "rail_class": "crypto",
        "status": "active",
        "updated_at": "2026-05-01T10:00:00Z"
      },
      {
        "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "asset": "USD",
        "created_at": "2026-05-01T10:00:00Z",
        "crypto_routing": null,
        "failure": null,
        "fiat_rail": "fedwire",
        "fiat_routing": {
          "asset": "USD",
          "attribution_mode": "virtual_account",
          "bank_details": null,
          "beneficiary_name": null,
          "fiat_rail": "fedwire",
          "reference": null
        },
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "rail_class": "fiat",
        "status": "provisioning",
        "updated_at": "2026-05-01T10:00:00Z"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /funding-endpoints

**Provision funding endpoint**

Provisions a new deposit-side endpoint. Crypto routes to the custody rails backend. Fiat requests carry only `account_ref` and `routing`; the pooled fiat route owner is derived server-side inside `rails-router-service` rather than supplied in the request body, and provisioning is delegated to `fiat-rails-service` after the route-guard/availability pipeline approves the route. Two checks can refuse a request with `422` and `code = not_admissible` before anything is provisioned. First, a fiat `local_bank_transfer` request made by a signed-in user needs that user to have accepted the published payment-account terms: otherwise `data.reason` is `legal_acceptance_required`, or `legal_requirement_unavailable` when no terms are published; requests made by service accounts skip this check. Then the account is checked for admission, on fiat and crypto requests alike, before the route or its availability is resolved: the account must not be suspended or closed; a client account needs a verified client and an enterprise master account a verified enterprise, and the enterprise behind the account (the parent of the client, or the owner of the master account) must be operational and unrestricted (one still being admitted, offboarding, terminated or restricted is refused); a master account owned by a platform operator is decided on its own status alone. An account refused admission returns `422` with `code = not_admissible`, `data.reason` one of `CLIENT_NOT_VERIFIED`, `ENTERPRISE_NOT_VERIFIED`, `ENTERPRISE_NOT_OPERATIONAL`, `ENTERPRISE_RESTRICTED`, `ACCOUNT_SUSPENDED`, `ACCOUNT_CLOSED`, `CLIENT_SUSPENDED`, `CLIENT_CLOSED` and `data.source` naming the check that refused (`verification`, `lifecycle`); when admission cannot be checked the request returns `503 temporarily_unavailable`. Neither response creates an endpoint. An idempotent retry is checked again, so an account refused since its first request gets the refusal instead of the stored endpoint. Idempotent on the required `Idempotency-Key` header. On fiat resources, `fiat_routing.bank_details` carries the receive details a provider issues — `provider_payment_reference` (`required` says whether a payment without it can fail), `account_holder_address`, `bank_address` and `correspondent_bank` — always present, `null` when the provider issued none. `provider_payment_reference` is the provider's own reference, separate from the pooled ISO 11649 `reference`.

**Required capability:** `funding_endpoints.provision`

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) *(required)* — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

Exactly one alternative must match.

#### Request body schema: 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})$` |
| `rail_class` | "crypto" | Yes |  |
| `routing` | object | Yes | No additional fields |

Additional fields are not accepted.

##### Request body schema: alternative 1.routing

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `network` | string | Yes | minLength: 1 |

Additional fields are not accepted.

#### Request body schema: 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})$` |
| `rail_class` | "fiat" | Yes |  |
| `routing` | object | Yes | No additional fields |

Additional fields are not accepted.

##### Request body schema: alternative 2.routing

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `fiat_rail` | "sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire" | Yes |  |

Additional fields are not accepted.

**Request example:**

```json
{
  "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "rail_class": "crypto",
  "routing": {
    "asset": "USDC",
    "network": "ethereum"
  }
}
```

### funding-endpoints-create Response 201 schema

Content type: `application/json`.

#### application/json body

| 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})$` |
| `asset` | string or null | No |  |
| `created_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))$` |
| `crypto_routing` | object or null | No |  |
| `failure` | object or null | No |  |
| `fiat_rail` | "sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire" or null | No |  |
| `fiat_routing` | object or null | No |  |
| `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)$` |
| `network` | string or null | No |  |
| `rail_class` | "fiat" / "crypto" | Yes |  |
| `status` | "provisioning" / "active" / "failed" / "disabled" / "retired" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.asset

At least one alternative must match.

###### application/json body.asset: alternative 1

Currency code (ISO-4217 or on-chain ticker)

Type: `string`. pattern: `^[A-Z0-9]{1,16}$`

###### application/json body.asset: alternative 2

Type: `null`. 

##### application/json body.crypto_routing

At least one alternative must match.

###### application/json body.crypto_routing: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `endpoint` | object | No | No additional fields |
| `network` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.crypto_routing: alternative 1.endpoint

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `address` | string | Yes | minLength: 1; maxLength: 256 |
| `memo` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.crypto_routing: alternative 1.endpoint.memo

At least one alternative must match.

###### application/json body.crypto_routing: alternative 1.endpoint.memo: alternative 1

Type: `string`. 

###### application/json body.crypto_routing: alternative 1.endpoint.memo: alternative 2

Type: `null`. 

###### application/json body.crypto_routing: alternative 2

Type: `null`. 

##### application/json body.failure

At least one alternative must match.

###### application/json body.failure: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `code` | "party_profile_incomplete" / "party_not_supported" / "party_already_provisioned" / "provider_rejected" / "manual_review_required" / "provisioning_unavailable" | Yes |  |
| `retryable` | boolean | Yes |  |

Additional fields are not accepted.

###### application/json body.failure: alternative 2

Type: `null`. 

##### application/json body.fiat_rail

At least one alternative must match.

###### application/json body.fiat_rail: alternative 1

Type: `"sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire"`. 

###### application/json body.fiat_rail: alternative 2

Type: `null`. 

##### application/json body.fiat_routing

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `attribution_mode` | "virtual_account" / "payment_reference" | Yes |  |
| `bank_details` | object or object or null | No |  |
| `beneficiary_name` | string or null | No |  |
| `fiat_rail` | "sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire" | Yes |  |
| `reference` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1

Exactly one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_address` | object or null | No |  |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `correspondent_bank` | object or null | No |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `iban` | string | Yes | minLength: 1; maxLength: 34 |
| `provider_payment_reference` | object or null | No |  |
| `scheme` | "iban" | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_name

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_name: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bic

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bic: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string or null | Yes |  |
| `address` | object or null | Yes |  |
| `bic` | string | Yes | minLength: 1; maxLength: 11 |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.account_number

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.account_number: alternative 1

Type: `string`. minLength: 1; maxLength: 64

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.account_number: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.provider_payment_reference

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.provider_payment_reference: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `required` | boolean | Yes |  |
| `value` | string | Yes | minLength: 1; maxLength: 140 |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.provider_payment_reference: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_address` | object or null | No |  |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string | Yes | minLength: 1; maxLength: 64 |
| `account_type` | "checking" / "savings" or null | No | Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept. |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `correspondent_bank` | object or null | No |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `provider_payment_reference` | object or null | No |  |
| `routing_codes` | object[] | Yes | minItems: 1; maxItems: 16 |
| `scheme` | "local_account" | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_type

Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_type: alternative 1

Type: `"checking" / "savings"`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_type: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_name

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_name: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bic

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bic: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string or null | Yes |  |
| `address` | object or null | Yes |  |
| `bic` | string | Yes | minLength: 1; maxLength: 11 |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.account_number

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.account_number: alternative 1

Type: `string`. minLength: 1; maxLength: 64

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.account_number: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.provider_payment_reference

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.provider_payment_reference: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `required` | boolean | Yes |  |
| `value` | string | Yes | minLength: 1; maxLength: 140 |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.provider_payment_reference: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.routing_codes

Type: `object[]`. minItems: 1; maxItems: 16

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.routing_codes item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `type` | string | Yes | minLength: 1; maxLength: 64 |
| `value` | string | Yes | minLength: 1; maxLength: 64 |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.beneficiary_name

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.beneficiary_name: alternative 1

Type: `string`. 

###### application/json body.fiat_routing: alternative 1.beneficiary_name: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.reference

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.reference: alternative 1

Type: `string`. 

###### application/json body.fiat_routing: alternative 1.reference: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 2

Type: `null`. 

##### application/json body.network

At least one alternative must match.

###### application/json body.network: alternative 1

Type: `string`. 

###### application/json body.network: alternative 2

Type: `null`.


### funding-endpoints-create 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.


### funding-endpoints-create Response 401 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.


### funding-endpoints-create Response 403 schema

Content type: `application/json`.

See [response 401 schema](#funding-endpoints-create-response-401-schema).


### funding-endpoints-create Response 409 schema

Content type: `application/json`.

See [response 401 schema](#funding-endpoints-create-response-401-schema).


### funding-endpoints-create Response 422 schema

Content type: `application/json`.

See [response 401 schema](#funding-endpoints-create-response-401-schema).


### funding-endpoints-create Response 500 schema

Content type: `application/json`.

See [response 401 schema](#funding-endpoints-create-response-401-schema).


### funding-endpoints-create Response 502 schema

Content type: `application/json`.

See [response 400 schema](#funding-endpoints-create-response-400-schema).


### funding-endpoints-create Response 503 schema

Content type: `application/json`.

See [response 400 schema](#funding-endpoints-create-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "asset": "USDC",
    "created_at": "2026-05-01T10:00:00Z",
    "crypto_routing": {
      "asset": "USDC",
      "endpoint": {
        "address": "0xAbCd1234567890AbCd1234567890AbCd12345678",
        "memo": null
      },
      "network": "ethereum"
    },
    "fiat_rail": null,
    "fiat_routing": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "network": "ethereum",
    "rail_class": "crypto",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `422` — The request cannot be processed under the resource or route contract. Depending on the endpoint, code can be not_admissible or unsupported_currency; inspect the documented code and data.reason.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /funding-endpoints/{funding_endpoint_id}

**Get funding endpoint**

Reads a funding endpoint by id. The `rail_class` query parameter is required so edge can route directly to the selected backend. Fiat reads also require `account_ref` because fiat funding endpoints are account-scoped; they are delegated to `fiat-rails-service`, and unknown or out-of-scope fiat ids return `resource_not_found`. On fiat resources, `fiat_routing.bank_details` carries the receive details a provider issues — `provider_payment_reference` (`required` says whether a payment without it can fail), `account_holder_address`, `bank_address` and `correspondent_bank` — always present, `null` when the provider issued none. `provider_payment_reference` is the provider's own reference, separate from the pooled ISO 11649 `reference`.

**Required capability:** `funding_endpoints.read`

**Authentication:** Bearer token required.

**Parameters:**

- `funding_endpoint_id` `string` (path) *(required)*
- `rail_class` `string` (query) *(required)*
- `account_ref` `string` (query)

### funding-endpoints-get Response 200 schema

Content type: `application/json`.

#### application/json body

| 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})$` |
| `asset` | string or null | No |  |
| `created_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))$` |
| `crypto_routing` | object or null | No |  |
| `failure` | object or null | No |  |
| `fiat_rail` | "sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire" or null | No |  |
| `fiat_routing` | object or null | No |  |
| `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)$` |
| `network` | string or null | No |  |
| `rail_class` | "fiat" / "crypto" | Yes |  |
| `status` | "provisioning" / "active" / "failed" / "disabled" / "retired" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.asset

At least one alternative must match.

###### application/json body.asset: alternative 1

Currency code (ISO-4217 or on-chain ticker)

Type: `string`. pattern: `^[A-Z0-9]{1,16}$`

###### application/json body.asset: alternative 2

Type: `null`. 

##### application/json body.crypto_routing

At least one alternative must match.

###### application/json body.crypto_routing: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `endpoint` | object | No | No additional fields |
| `network` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.crypto_routing: alternative 1.endpoint

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `address` | string | Yes | minLength: 1; maxLength: 256 |
| `memo` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.crypto_routing: alternative 1.endpoint.memo

At least one alternative must match.

###### application/json body.crypto_routing: alternative 1.endpoint.memo: alternative 1

Type: `string`. 

###### application/json body.crypto_routing: alternative 1.endpoint.memo: alternative 2

Type: `null`. 

###### application/json body.crypto_routing: alternative 2

Type: `null`. 

##### application/json body.failure

At least one alternative must match.

###### application/json body.failure: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `code` | "party_profile_incomplete" / "party_not_supported" / "party_already_provisioned" / "provider_rejected" / "manual_review_required" / "provisioning_unavailable" | Yes |  |
| `retryable` | boolean | Yes |  |

Additional fields are not accepted.

###### application/json body.failure: alternative 2

Type: `null`. 

##### application/json body.fiat_rail

At least one alternative must match.

###### application/json body.fiat_rail: alternative 1

Type: `"sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire"`. 

###### application/json body.fiat_rail: alternative 2

Type: `null`. 

##### application/json body.fiat_routing

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `attribution_mode` | "virtual_account" / "payment_reference" | Yes |  |
| `bank_details` | object or object or null | No |  |
| `beneficiary_name` | string or null | No |  |
| `fiat_rail` | "sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire" | Yes |  |
| `reference` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1

Exactly one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_address` | object or null | No |  |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `correspondent_bank` | object or null | No |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `iban` | string | Yes | minLength: 1; maxLength: 34 |
| `provider_payment_reference` | object or null | No |  |
| `scheme` | "iban" | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_name

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_name: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bic

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bic: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string or null | Yes |  |
| `address` | object or null | Yes |  |
| `bic` | string | Yes | minLength: 1; maxLength: 11 |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.account_number

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.account_number: alternative 1

Type: `string`. minLength: 1; maxLength: 64

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.account_number: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.provider_payment_reference

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.provider_payment_reference: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `required` | boolean | Yes |  |
| `value` | string | Yes | minLength: 1; maxLength: 140 |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.provider_payment_reference: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_address` | object or null | No |  |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string | Yes | minLength: 1; maxLength: 64 |
| `account_type` | "checking" / "savings" or null | No | Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept. |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `correspondent_bank` | object or null | No |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `provider_payment_reference` | object or null | No |  |
| `routing_codes` | object[] | Yes | minItems: 1; maxItems: 16 |
| `scheme` | "local_account" | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_type

Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_type: alternative 1

Type: `"checking" / "savings"`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_type: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_name

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_name: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bic

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bic: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string or null | Yes |  |
| `address` | object or null | Yes |  |
| `bic` | string | Yes | minLength: 1; maxLength: 11 |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.account_number

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.account_number: alternative 1

Type: `string`. minLength: 1; maxLength: 64

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.account_number: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.provider_payment_reference

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.provider_payment_reference: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `required` | boolean | Yes |  |
| `value` | string | Yes | minLength: 1; maxLength: 140 |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.provider_payment_reference: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.routing_codes

Type: `object[]`. minItems: 1; maxItems: 16

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.routing_codes item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `type` | string | Yes | minLength: 1; maxLength: 64 |
| `value` | string | Yes | minLength: 1; maxLength: 64 |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.beneficiary_name

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.beneficiary_name: alternative 1

Type: `string`. 

###### application/json body.fiat_routing: alternative 1.beneficiary_name: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.reference

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.reference: alternative 1

Type: `string`. 

###### application/json body.fiat_routing: alternative 1.reference: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 2

Type: `null`. 

##### application/json body.network

At least one alternative must match.

###### application/json body.network: alternative 1

Type: `string`. 

###### application/json body.network: alternative 2

Type: `null`.


### funding-endpoints-get 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.


### funding-endpoints-get Response 401 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.


### funding-endpoints-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#funding-endpoints-get-response-401-schema).


### funding-endpoints-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#funding-endpoints-get-response-401-schema).


### funding-endpoints-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#funding-endpoints-get-response-401-schema).


### funding-endpoints-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#funding-endpoints-get-response-400-schema).


### funding-endpoints-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#funding-endpoints-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "asset": "USDC",
    "created_at": "2026-05-01T10:00:00Z",
    "crypto_routing": {
      "asset": "USDC",
      "endpoint": {
        "address": "0xAbCd1234567890AbCd1234567890AbCd12345678",
        "memo": null
      },
      "network": "ethereum"
    },
    "fiat_rail": null,
    "fiat_routing": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "network": "ethereum",
    "rail_class": "crypto",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /funding-routes/readiness

**List the deposit fiat routes of an account with their readiness**

Returns active deposit fiat route candidates from the asset catalog, including routes blocked by commercial eligibility, feature flags or runtime readiness. No crypto route is returned. `attribution_mode` names the setup call a route takes: `virtual_account` through `POST /funding-endpoints`, `payment_reference` through `POST /deposit-instructions`, null when the route has no configured mode. A null mode can also mean no commercial route owner could be resolved. Routes are sorted by rail then currency; the complete list has no external pagination. Requires a bound enterprise/client operating scope: missing or platform bindings return 403, and an account outside the bound scope is hidden with 404. An unavailable route carries the reasons it is blocked, the same ones setup refuses it with; `fiat_international_verification_required` means the account holder must complete the international verification first.

**Authentication:** Bearer token required.

**Parameters:**

- `account_ref` `string` (query) *(required)*

### funding-routes-readiness Response 200 schema

Content type: `application/json`.

#### application/json body

| 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})$` |
| `routes` | object[] | Yes |  |

Additional fields are not accepted.

##### application/json body.routes

Type: `object[]`. 

###### application/json body.routes item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `attribution_mode` | "virtual_account" / "payment_reference" or null | Yes |  |
| `availability` | "available" / "unavailable" | Yes |  |
| `currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `method` | string | Yes | pattern: `^[a-z0-9_]+$` |
| `rail` | "sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire" | Yes |  |
| `rail_class` | "fiat" | Yes |  |
| `reasons` | object or object or object or object[] | Yes |  |

Additional fields are not accepted.

###### application/json body.routes item.attribution_mode

At least one alternative must match.

###### application/json body.routes item.attribution_mode: alternative 1

Type: `"virtual_account" / "payment_reference"`. 

###### application/json body.routes item.attribution_mode: alternative 2

Type: `null`. 

###### application/json body.routes item.reasons

Type: `object or object or object or object[]`. 

###### application/json body.routes item.reasons item

Exactly one alternative must match.

###### application/json body.routes item.reasons item: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `code` | "asset_rail_direction_unsupported" | Yes |  |
| `source` | "technical" | Yes |  |

Additional fields are not accepted.

###### application/json body.routes item.reasons item: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `code` | "service_family_ineligible" | Yes |  |
| `source` | "commercial" | Yes |  |

Additional fields are not accepted.

###### application/json body.routes item.reasons item: alternative 3

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `code` | "crypto_route_unavailable" / "crypto_provider_projection_missing" / "crypto_provider_disabled" / "crypto_provider_capability_unavailable" / "crypto_provider_adapter_unavailable" / "fiat_operation_not_implemented" / "fiat_provider_unavailable" / "fiat_catalog_unsupported" / "fiat_provider_disabled" / "fiat_pooled_endpoint_missing" / "fiat_pooled_endpoint_inactive" / "fiat_unsupported_mode" / "fiat_unsupported_currency" / "fiat_unsupported_rail_method" / "fiat_inbound_forwarding_disabled" / "fiat_international_verification_required" | Yes |  |
| `source` | "runtime" | Yes |  |

Additional fields are not accepted.

###### application/json body.routes item.reasons item: alternative 4

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `code` | "service_family_disabled" | Yes |  |
| `source` | "feature_flag" | Yes |  |

Additional fields are not accepted.


### funding-routes-readiness 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.


### funding-routes-readiness Response 401 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.


### funding-routes-readiness Response 403 schema

Content type: `application/json`.

See [response 401 schema](#funding-routes-readiness-response-401-schema).


### funding-routes-readiness Response 404 schema

Content type: `application/json`.

See [response 401 schema](#funding-routes-readiness-response-401-schema).


### funding-routes-readiness Response 500 schema

Content type: `application/json`.

See [response 401 schema](#funding-routes-readiness-response-401-schema).


### funding-routes-readiness Response 502 schema

Content type: `application/json`.

See [response 400 schema](#funding-routes-readiness-response-400-schema).


### funding-routes-readiness Response 503 schema

Content type: `application/json`.

See [response 400 schema](#funding-routes-readiness-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "routes": [
      {
        "attribution_mode": "virtual_account",
        "availability": "unavailable",
        "currency": "USD",
        "method": "fedwire",
        "rail": "fedwire",
        "rail_class": "fiat",
        "reasons": [
          {
            "code": "fiat_international_verification_required",
            "source": "runtime"
          }
        ]
      },
      {
        "attribution_mode": "virtual_account",
        "availability": "available",
        "currency": "ARS",
        "method": "local_bank_transfer",
        "rail": "local_bank_transfer",
        "rail_class": "fiat",
        "reasons": []
      }
    ]
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Payment Methods

### GET /available-payment-methods

**List available payment methods**

Returns fiat deposit methods whose current runtime availability permits setup for the supplied `account_ref`. The account must lie within the caller’s bound enterprise or client scope; an out-of-scope account returns `404 resource_not_found`, and an unbound or platform-bound caller is refused. This is a current setup-readiness signal, not a guarantee that a later deposit succeeds. Use `/payment-methods` for the global reference catalog.

**Authentication:** Bearer token required.

**Parameters:**

- `rail` `string` (query)
- `asset` `string` (query)
- `account_ref` `string` (query) *(required)*
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### available-payment-methods-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `active` | boolean | Yes |  |
| `code` | string | Yes | pattern: `^[a-z0-9_]+$` |
| `currencies` | string[] | Yes | minItems: 1 |
| `display_name` | string | Yes | minLength: 1 |
| `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)$` |
| `rail` | "sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.currencies

Type: `string[]`. minItems: 1

###### application/json body.items item.currencies item

Currency code (ISO-4217 or on-chain ticker)

Type: `string`. pattern: `^[A-Z0-9]{1,16}$`

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. minLength: 1

###### application/json body.next_page_token: alternative 2

Type: `null`.


### available-payment-methods-list 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.


### available-payment-methods-list Response 401 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.


### available-payment-methods-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#available-payment-methods-list-response-401-schema).


### available-payment-methods-list Response 404 schema

Content type: `application/json`.

See [response 401 schema](#available-payment-methods-list-response-401-schema).


### available-payment-methods-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#available-payment-methods-list-response-401-schema).


### available-payment-methods-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#available-payment-methods-list-response-400-schema).


### available-payment-methods-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#available-payment-methods-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "active": true,
        "code": "sepa_credit_transfer",
        "currencies": [
          "EUR"
        ],
        "display_name": "SEPA",
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "rail": "sepa_credit_transfer"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /payment-methods

**List payment methods**

Returns the global fiat deposit payment-method catalog. The `rail` filter uses a fiat rail code and `asset` uses a currency code; unsupported combinations return an empty page. This reference listing does not check account setup readiness. `account_ref` is rejected here; use `/available-payment-methods` for account-scoped discovery. Crypto networks are listed separately through `/crypto-networks`.

**Authentication:** Bearer token required.

**Parameters:**

- `rail` `string` (query)
- `asset` `string` (query)
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### payment-methods-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `active` | boolean | Yes |  |
| `code` | string | Yes | pattern: `^[a-z0-9_]+$` |
| `currencies` | string[] | Yes | minItems: 1 |
| `display_name` | string | Yes | minLength: 1 |
| `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)$` |
| `rail` | "sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.currencies

Type: `string[]`. minItems: 1

###### application/json body.items item.currencies item

Currency code (ISO-4217 or on-chain ticker)

Type: `string`. pattern: `^[A-Z0-9]{1,16}$`

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. minLength: 1

###### application/json body.next_page_token: alternative 2

Type: `null`.


### payment-methods-list 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.


### payment-methods-list Response 401 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.


### payment-methods-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#payment-methods-list-response-401-schema).


### payment-methods-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#payment-methods-list-response-401-schema).


### payment-methods-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#payment-methods-list-response-400-schema).


### payment-methods-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#payment-methods-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "active": true,
        "code": "sepa_credit_transfer",
        "currencies": [
          "EUR"
        ],
        "display_name": "SEPA",
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "rail": "sepa_credit_transfer"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /payment-methods

**Create payment method**

This mutation is unavailable. The fiat payment method catalog is derived from asset/rail support and cannot be changed through this endpoint. Every valid request returns `503 rail_not_available`; no successful creation, update or deletion occurs. Use `GET /payment-methods` to read the catalog.

**Required capability:** `payment_methods.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `active` | boolean | No | default: `true` |
| `code` | string | Yes | pattern: `^[a-z0-9_]+$` |
| `currencies` | string[] | Yes | minItems: 1 |
| `display_name` | string | Yes | minLength: 1 |
| `rail` | string | Yes | minLength: 1 |

Additional fields are not accepted.

#### Request body schema.currencies

Type: `string[]`. minItems: 1

##### Request body schema.currencies item

Currency code (ISO-4217 or on-chain ticker)

Type: `string`. pattern: `^[A-Z0-9]{1,16}$`

**Request example:**

```json
{
  "active": true,
  "code": "sepa_credit_transfer",
  "currencies": [
    "EUR"
  ],
  "display_name": "SEPA",
  "rail": "sepa_credit_transfer"
}
```

### payment-methods-create 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.


### payment-methods-create Response 401 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.


### payment-methods-create Response 403 schema

Content type: `application/json`.

See [response 401 schema](#payment-methods-create-response-401-schema).


### payment-methods-create Response 409 schema

Content type: `application/json`.

See [response 401 schema](#payment-methods-create-response-401-schema).


### payment-methods-create Response 500 schema

Content type: `application/json`.

See [response 401 schema](#payment-methods-create-response-401-schema).


### payment-methods-create Response 502 schema

Content type: `application/json`.

See [response 400 schema](#payment-methods-create-response-400-schema).


### payment-methods-create Response 503 schema

Content type: `application/json`.

See [response 400 schema](#payment-methods-create-response-400-schema).


**Responses:**

- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### PATCH /payment-methods/{payment_method_id}

**Update payment method**

This mutation is unavailable. The fiat payment method catalog is derived from asset/rail support and cannot be changed through this endpoint. Every valid request returns `503 rail_not_available`; no successful creation, update or deletion occurs. Use `GET /payment-methods` to read the catalog.

**Required capability:** `payment_methods.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `payment_method_id` `string` (path) *(required)*

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `active` | boolean | No |  |
| `currencies` | string[] | No | minItems: 1 |
| `display_name` | string | No | minLength: 1 |
| `rail` | string | No | minLength: 1 |

Additional fields are not accepted.

#### Request body schema.currencies

Type: `string[]`. minItems: 1

##### Request body schema.currencies item

Currency code (ISO-4217 or on-chain ticker)

Type: `string`. pattern: `^[A-Z0-9]{1,16}$`

**Request example:**

```json
{
  "active": false,
  "display_name": "SEPA Updated"
}
```

### payment-methods-update 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.


### payment-methods-update Response 401 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.


### payment-methods-update Response 403 schema

Content type: `application/json`.

See [response 401 schema](#payment-methods-update-response-401-schema).


### payment-methods-update Response 404 schema

Content type: `application/json`.

See [response 401 schema](#payment-methods-update-response-401-schema).


### payment-methods-update Response 409 schema

Content type: `application/json`.

See [response 401 schema](#payment-methods-update-response-401-schema).


### payment-methods-update Response 500 schema

Content type: `application/json`.

See [response 401 schema](#payment-methods-update-response-401-schema).


### payment-methods-update Response 502 schema

Content type: `application/json`.

See [response 400 schema](#payment-methods-update-response-400-schema).


### payment-methods-update Response 503 schema

Content type: `application/json`.

See [response 400 schema](#payment-methods-update-response-400-schema).


**Responses:**

- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### DELETE /payment-methods/{payment_method_id}

**Delete payment method**

This mutation is unavailable. The fiat payment method catalog is derived from asset/rail support and cannot be changed through this endpoint. Every valid request returns `503 rail_not_available`; no successful creation, update or deletion occurs. Use `GET /payment-methods` to read the catalog.

**Required capability:** `payment_methods.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `payment_method_id` `string` (path) *(required)*

### payment-methods-delete 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.


### payment-methods-delete Response 401 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.


### payment-methods-delete Response 403 schema

Content type: `application/json`.

See [response 401 schema](#payment-methods-delete-response-401-schema).


### payment-methods-delete Response 404 schema

Content type: `application/json`.

See [response 401 schema](#payment-methods-delete-response-401-schema).


### payment-methods-delete Response 500 schema

Content type: `application/json`.

See [response 401 schema](#payment-methods-delete-response-401-schema).


### payment-methods-delete Response 502 schema

Content type: `application/json`.

See [response 400 schema](#payment-methods-delete-response-400-schema).


### payment-methods-delete Response 503 schema

Content type: `application/json`.

See [response 400 schema](#payment-methods-delete-response-400-schema).


**Responses:**

- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Payout Methods

### GET /eligible-payout-methods

**List eligible payout methods**

Returns fiat withdrawal methods eligible for the supplied enterprise or client `scope_ref`, based on technical, commercial and feature-flag eligibility. The scope must lie within the caller’s bound enterprise or client scope; an out-of-scope target returns `404 resource_not_found`, and an unbound or platform-bound caller is refused. Eligibility does not establish account-level runtime readiness or guarantee execution. Use `/payout-methods` for the global reference catalog.

**Authentication:** Bearer token required.

**Parameters:**

- `rail` `string` (query)
- `asset` `string` (query)
- `scope_ref` `string` (query) *(required)*
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### eligible-payout-methods-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `active` | boolean | Yes |  |
| `code` | string | Yes | pattern: `^[a-z0-9_]+$` |
| `currencies` | string[] | Yes | minItems: 1 |
| `display_name` | string | Yes | minLength: 1 |
| `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)$` |
| `rail` | "sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.currencies

Type: `string[]`. minItems: 1

###### application/json body.items item.currencies item

Currency code (ISO-4217 or on-chain ticker)

Type: `string`. pattern: `^[A-Z0-9]{1,16}$`

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. minLength: 1

###### application/json body.next_page_token: alternative 2

Type: `null`.


### eligible-payout-methods-list 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.


### eligible-payout-methods-list Response 401 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.


### eligible-payout-methods-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#eligible-payout-methods-list-response-401-schema).


### eligible-payout-methods-list Response 404 schema

Content type: `application/json`.

See [response 401 schema](#eligible-payout-methods-list-response-401-schema).


### eligible-payout-methods-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#eligible-payout-methods-list-response-401-schema).


### eligible-payout-methods-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#eligible-payout-methods-list-response-400-schema).


### eligible-payout-methods-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#eligible-payout-methods-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "active": true,
        "code": "sepa_credit_transfer",
        "currencies": [
          "EUR"
        ],
        "display_name": "SEPA",
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "rail": "sepa_credit_transfer"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /payout-methods

**List payout methods**

Returns the global fiat withdrawal payout-method catalog. The `rail` filter uses a fiat rail code and `asset` uses a currency code; unsupported combinations return an empty page. This reference listing does not establish scope eligibility or execution readiness. `scope_ref` is rejected here; use `/eligible-payout-methods` for an enterprise or client scope. Crypto networks are listed separately through `/crypto-networks`.

**Authentication:** Bearer token required.

**Parameters:**

- `rail` `string` (query)
- `asset` `string` (query)
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### payout-methods-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `active` | boolean | Yes |  |
| `code` | string | Yes | pattern: `^[a-z0-9_]+$` |
| `currencies` | string[] | Yes | minItems: 1 |
| `display_name` | string | Yes | minLength: 1 |
| `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)$` |
| `rail` | "sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.currencies

Type: `string[]`. minItems: 1

###### application/json body.items item.currencies item

Currency code (ISO-4217 or on-chain ticker)

Type: `string`. pattern: `^[A-Z0-9]{1,16}$`

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. minLength: 1

###### application/json body.next_page_token: alternative 2

Type: `null`.


### payout-methods-list 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.


### payout-methods-list Response 401 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.


### payout-methods-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#payout-methods-list-response-401-schema).


### payout-methods-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#payout-methods-list-response-401-schema).


### payout-methods-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#payout-methods-list-response-400-schema).


### payout-methods-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#payout-methods-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "active": true,
        "code": "sepa_credit_transfer",
        "currencies": [
          "EUR"
        ],
        "display_name": "SEPA",
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "rail": "sepa_credit_transfer"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /payout-methods

**Create payout method**

This mutation is unavailable. The fiat payout method catalog is derived from asset/rail support and cannot be changed through this endpoint. Every valid request returns `503 rail_not_available`; no successful creation, update or deletion occurs. Use `GET /payout-methods` to read the catalog.

**Required capability:** `payout_methods.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `active` | boolean | No | default: `true` |
| `code` | string | Yes | pattern: `^[a-z0-9_]+$` |
| `currencies` | string[] | Yes | minItems: 1 |
| `display_name` | string | Yes | minLength: 1 |
| `rail` | string | Yes | minLength: 1 |

Additional fields are not accepted.

#### Request body schema.currencies

Type: `string[]`. minItems: 1

##### Request body schema.currencies item

Currency code (ISO-4217 or on-chain ticker)

Type: `string`. pattern: `^[A-Z0-9]{1,16}$`

**Request example:**

```json
{
  "active": true,
  "code": "sepa_credit_transfer",
  "currencies": [
    "EUR"
  ],
  "display_name": "SEPA",
  "rail": "sepa_credit_transfer"
}
```

### payout-methods-create 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.


### payout-methods-create Response 401 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.


### payout-methods-create Response 403 schema

Content type: `application/json`.

See [response 401 schema](#payout-methods-create-response-401-schema).


### payout-methods-create Response 409 schema

Content type: `application/json`.

See [response 401 schema](#payout-methods-create-response-401-schema).


### payout-methods-create Response 500 schema

Content type: `application/json`.

See [response 401 schema](#payout-methods-create-response-401-schema).


### payout-methods-create Response 502 schema

Content type: `application/json`.

See [response 400 schema](#payout-methods-create-response-400-schema).


### payout-methods-create Response 503 schema

Content type: `application/json`.

See [response 400 schema](#payout-methods-create-response-400-schema).


**Responses:**

- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### PATCH /payout-methods/{payout_method_id}

**Update payout method**

This mutation is unavailable. The fiat payout method catalog is derived from asset/rail support and cannot be changed through this endpoint. Every valid request returns `503 rail_not_available`; no successful creation, update or deletion occurs. Use `GET /payout-methods` to read the catalog.

**Required capability:** `payout_methods.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `payout_method_id` `string` (path) *(required)*

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `active` | boolean | No |  |
| `currencies` | string[] | No | minItems: 1 |
| `display_name` | string | No | minLength: 1 |
| `rail` | string | No | minLength: 1 |

Additional fields are not accepted.

#### Request body schema.currencies

Type: `string[]`. minItems: 1

##### Request body schema.currencies item

Currency code (ISO-4217 or on-chain ticker)

Type: `string`. pattern: `^[A-Z0-9]{1,16}$`

**Request example:**

```json
{
  "active": false,
  "display_name": "SEPA Updated"
}
```

### payout-methods-update 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.


### payout-methods-update Response 401 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.


### payout-methods-update Response 403 schema

Content type: `application/json`.

See [response 401 schema](#payout-methods-update-response-401-schema).


### payout-methods-update Response 404 schema

Content type: `application/json`.

See [response 401 schema](#payout-methods-update-response-401-schema).


### payout-methods-update Response 409 schema

Content type: `application/json`.

See [response 401 schema](#payout-methods-update-response-401-schema).


### payout-methods-update Response 500 schema

Content type: `application/json`.

See [response 401 schema](#payout-methods-update-response-401-schema).


### payout-methods-update Response 502 schema

Content type: `application/json`.

See [response 400 schema](#payout-methods-update-response-400-schema).


### payout-methods-update Response 503 schema

Content type: `application/json`.

See [response 400 schema](#payout-methods-update-response-400-schema).


**Responses:**

- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### DELETE /payout-methods/{payout_method_id}

**Delete payout method**

This mutation is unavailable. The fiat payout method catalog is derived from asset/rail support and cannot be changed through this endpoint. Every valid request returns `503 rail_not_available`; no successful creation, update or deletion occurs. Use `GET /payout-methods` to read the catalog.

**Required capability:** `payout_methods.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `payout_method_id` `string` (path) *(required)*

### payout-methods-delete 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.


### payout-methods-delete Response 401 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.


### payout-methods-delete Response 403 schema

Content type: `application/json`.

See [response 401 schema](#payout-methods-delete-response-401-schema).


### payout-methods-delete Response 404 schema

Content type: `application/json`.

See [response 401 schema](#payout-methods-delete-response-401-schema).


### payout-methods-delete Response 500 schema

Content type: `application/json`.

See [response 401 schema](#payout-methods-delete-response-401-schema).


### payout-methods-delete Response 502 schema

Content type: `application/json`.

See [response 400 schema](#payout-methods-delete-response-400-schema).


### payout-methods-delete Response 503 schema

Content type: `application/json`.

See [response 400 schema](#payout-methods-delete-response-400-schema).


**Responses:**

- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Crypto Networks

### GET /available-crypto-networks

**List available crypto networks**

Returns active crypto networks projected from available runtime asset/rail tuples for the required operating account. direction defaults to deposit and also accepts withdrawal. When asset is supplied, each item contains only assets that passed that filter and availability check. Account coverage is checked against an authenticated enterprise tenant binding; unbound and platform-operator callers receive 403, and an account outside the tenant receives 404. This is a current snapshot for the selected direction; funding-endpoint provisioning and withdrawal submission recheck their own requirements.

**Authentication:** Bearer token required.

**Parameters:**

- `asset` `string` (query)
- `direction` `string` (query)
- `account_ref` `string` (query) *(required)*
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### available-crypto-networks-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `active` | boolean | Yes |  |
| `assets` | string[] | Yes |  |
| `code` | string | Yes | minLength: 1 |
| `display_name` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.items item.assets

Type: `string[]`. 

###### application/json body.items item.assets item

Currency code (ISO-4217 or on-chain ticker)

Type: `string`. pattern: `^[A-Z0-9]{1,16}$`

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. minLength: 1

###### application/json body.next_page_token: alternative 2

Type: `null`.


### available-crypto-networks-list 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.


### available-crypto-networks-list Response 401 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.


### available-crypto-networks-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#available-crypto-networks-list-response-401-schema).


### available-crypto-networks-list Response 404 schema

Content type: `application/json`.

See [response 401 schema](#available-crypto-networks-list-response-401-schema).


### available-crypto-networks-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#available-crypto-networks-list-response-401-schema).


### available-crypto-networks-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#available-crypto-networks-list-response-400-schema).


### available-crypto-networks-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#available-crypto-networks-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "active": true,
        "assets": [
          "USDC"
        ],
        "code": "ethereum",
        "display_name": "Ethereum"
      },
      {
        "active": true,
        "assets": [
          "USDC"
        ],
        "code": "polygon",
        "display_name": "Polygon"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /crypto-networks

**List crypto networks**

Returns the authenticated global crypto-network reference catalog without a capability gate. Omitting active selects active networks; active=true and active=false are the supported boolean query spellings, with false selecting inactive networks. asset filters which networks appear; each item still lists all supported assets on that network. account_ref and scope_ref are rejected here. Use /available-crypto-networks for an account runtime-availability snapshot or /eligible-crypto-networks for topology eligibility.

**Authentication:** Bearer token required.

**Parameters:**

- `asset` `string` (query)
- `active` `string` (query)
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### crypto-networks-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `active` | boolean | Yes |  |
| `assets` | string[] | Yes |  |
| `code` | string | Yes | minLength: 1 |
| `display_name` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.items item.assets

Type: `string[]`. 

###### application/json body.items item.assets item

Currency code (ISO-4217 or on-chain ticker)

Type: `string`. pattern: `^[A-Z0-9]{1,16}$`

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. minLength: 1

###### application/json body.next_page_token: alternative 2

Type: `null`.


### crypto-networks-list 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.


### crypto-networks-list Response 401 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.


### crypto-networks-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#crypto-networks-list-response-401-schema).


### crypto-networks-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#crypto-networks-list-response-401-schema).


### crypto-networks-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#crypto-networks-list-response-400-schema).


### crypto-networks-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#crypto-networks-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "active": true,
        "assets": [
          "USDC",
          "ETH"
        ],
        "code": "ethereum",
        "display_name": "Ethereum"
      },
      {
        "active": true,
        "assets": [
          "USDC",
          "POL"
        ],
        "code": "polygon",
        "display_name": "Polygon"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /eligible-crypto-networks

**List eligible crypto networks**

Returns active crypto networks projected from eligible asset/rail tuples for an enterprise or client scope. direction defaults to deposit and also accepts withdrawal. When asset is supplied, each item contains only assets that passed that filter and eligibility check. The caller must have an enterprise tenant binding covering scope_ref; platform-operator and unbound callers receive 403, while a scope outside the tenant receives 404. Use /available-crypto-networks for an operating-account runtime-availability snapshot.

**Authentication:** Bearer token required.

**Parameters:**

- `asset` `string` (query)
- `direction` `string` (query)
- `scope_ref` `string` (query) *(required)*
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### eligible-crypto-networks-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `active` | boolean | Yes |  |
| `assets` | string[] | Yes |  |
| `code` | string | Yes | minLength: 1 |
| `display_name` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.items item.assets

Type: `string[]`. 

###### application/json body.items item.assets item

Currency code (ISO-4217 or on-chain ticker)

Type: `string`. pattern: `^[A-Z0-9]{1,16}$`

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. minLength: 1

###### application/json body.next_page_token: alternative 2

Type: `null`.


### eligible-crypto-networks-list 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.


### eligible-crypto-networks-list Response 401 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.


### eligible-crypto-networks-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#eligible-crypto-networks-list-response-401-schema).


### eligible-crypto-networks-list Response 404 schema

Content type: `application/json`.

See [response 401 schema](#eligible-crypto-networks-list-response-401-schema).


### eligible-crypto-networks-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#eligible-crypto-networks-list-response-401-schema).


### eligible-crypto-networks-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#eligible-crypto-networks-list-response-400-schema).


### eligible-crypto-networks-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#eligible-crypto-networks-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "active": true,
        "assets": [
          "USDC"
        ],
        "code": "ethereum",
        "display_name": "Ethereum"
      },
      {
        "active": true,
        "assets": [
          "USDC"
        ],
        "code": "polygon",
        "display_name": "Polygon"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Conversion Pairs

### GET /conversion-pairs

**List conversion pairs**

Lists global product support corridors for conversions. Conversion pairs describe platform-supported source/target currency directions and static source amount bounds only; they are not account-specific eligibility, pricing, fee, liquidity, or execution guarantees. Omitting active selects active corridors; active=true and active=false are the supported boolean query spellings, with false selecting inactive corridors. Account and topology discovery parameters are rejected on this catalog route. Use conversion preflight/preview for account-specific availability and economics.

**Authentication:** Bearer token required.

**Parameters:**

- `source_currency` `string` (query)
- `target_currency` `string` (query)
- `active` `string` (query)
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### conversion-pairs-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `active` | boolean | Yes |  |
| `display_order` | integer | Yes | minimum: 0; maximum: 9007199254740991 |
| `id` | string | Yes | pattern: `^[a-z0-9]+(?:-[a-z0-9]+)*$`; minLength: 1; maxLength: 128 |
| `max_source_amount` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |
| `min_source_amount` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |
| `settlement_model` | "internal_platform" | Yes |  |
| `source_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `target_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |

Additional fields are not accepted.

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. 

###### application/json body.next_page_token: alternative 2

Type: `null`.


### conversion-pairs-list 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.


### conversion-pairs-list Response 401 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.


### conversion-pairs-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#conversion-pairs-list-response-401-schema).


### conversion-pairs-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#conversion-pairs-list-response-401-schema).


### conversion-pairs-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#conversion-pairs-list-response-400-schema).


### conversion-pairs-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#conversion-pairs-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "active": true,
        "display_order": 0,
        "id": "usdc-btc",
        "max_source_amount": "100000.00",
        "min_source_amount": "10.00",
        "settlement_model": "internal_platform",
        "source_currency": "USDC",
        "target_currency": "BTC"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /conversion-pairs/{conversion_pair_id}

**Get conversion pair**

Returns one global product support corridor by its lowercase catalog id, such as usdc-btc. The ID is a string with lowercase alphanumeric segments separated by hyphens, not a UUID. This is static platform catalog data, not account-specific eligibility or a quote.

**Authentication:** Bearer token required.

**Parameters:**

- `conversion_pair_id` `string` (path) *(required)*

### conversion-pairs-get Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `active` | boolean | Yes |  |
| `display_order` | integer | Yes | minimum: 0; maximum: 9007199254740991 |
| `id` | string | Yes | pattern: `^[a-z0-9]+(?:-[a-z0-9]+)*$`; minLength: 1; maxLength: 128 |
| `max_source_amount` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |
| `min_source_amount` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |
| `settlement_model` | "internal_platform" | Yes |  |
| `source_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `target_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |

Additional fields are not accepted.


### conversion-pairs-get 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.


### conversion-pairs-get Response 401 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.


### conversion-pairs-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#conversion-pairs-get-response-401-schema).


### conversion-pairs-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#conversion-pairs-get-response-401-schema).


### conversion-pairs-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#conversion-pairs-get-response-401-schema).


### conversion-pairs-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#conversion-pairs-get-response-400-schema).


### conversion-pairs-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#conversion-pairs-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "active": true,
    "display_order": 0,
    "id": "usdc-btc",
    "max_source_amount": "100000.00",
    "min_source_amount": "10.00",
    "settlement_model": "internal_platform",
    "source_currency": "USDC",
    "target_currency": "BTC"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Webhook Subscriptions

### GET /webhook-subscriptions

**List webhook subscriptions**

Lists webhook subscriptions. If omitted, `scope_ref` is derived from the authenticated enterprise or client context.

**Required capability:** `webhooks.read`

**Authentication:** Bearer token required.

**Parameters:**

- `scope_ref` `string` (query)
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.
- `status` `string` (query)

### webhook-subscriptions-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `created_at` | string or string | Yes |  |
| `etag` | string | Yes | minLength: 1 |
| `event_types` | "*" / "tenant.enterprise.admission_reviewed.v1" / "tenant.enterprise.admitted.v1" / "tenant.enterprise.activated.v1" / "tenant.enterprise.updated.v1" / "tenant.enterprise.suspended.v1" / "tenant.enterprise.reactivated.v1" / "tenant.enterprise.closed.v1" / "tenant.enterprise.terminated.v1" / "tenant.platform_operator.admitted.v1" / "tenant.platform_operator.restricted.v1" / "tenant.platform_operator.reactivated.v1" / "tenant.platform_operator.offboarded.v1" / "tenant.platform_operator.catalog_updated.v1" / "tenant.master_account.created.v1" / "tenant.master_account.suspended.v1" / "tenant.master_account.closed.v1" / "tenant.client.created.v1" / "tenant.client.updated.v1" / "tenant.client.suspended.v1" / "tenant.client.reactivated.v1" / "tenant.client.closed.v1" / "tenant.client_account.created.v1" / "tenant.client_account.suspended.v1" / "tenant.client_account.reactivated.v1" / "tenant.client_account.closed.v1" / "ledger.transaction.posted.v1" / "operations.withdrawal.requested.v1" / "operations.withdrawal.admissible.v1" / "operations.withdrawal.executing.v1" / "operations.withdrawal.pending_approval.v1" / "operations.withdrawal.pending_compliance.v1" / "operations.withdrawal.approved.v1" / "operations.withdrawal.settled.v1" / "operations.withdrawal.failed.v1" / "operations.withdrawal.cancelled.v1" / "operations.conversion.requested.v1" / "operations.conversion.admissible.v1" / "operations.conversion.pending_approval.v1" / "operations.conversion.pending_compliance.v1" / "operations.conversion.approved.v1" / "operations.conversion.settled.v1" / "operations.conversion.failed.v1" / "operations.conversion.cancelled.v1" / "operations.external_settlement_conversion.pending_compliance.v1" / "operations.internal_transfer.requested.v1" / "operations.internal_transfer.admissible.v1" / "operations.internal_transfer.pending_approval.v1" / "operations.internal_transfer.pending_compliance.v1" / "operations.internal_transfer.approved.v1" / "operations.internal_transfer.settled.v1" / "operations.internal_transfer.failed.v1" / "operations.internal_transfer.cancelled.v1" / "operations.on_ramp.requested.v1" / "operations.on_ramp.admissible.v1" / "operations.on_ramp.pending_approval.v1" / "operations.on_ramp.pending_compliance.v1" / "operations.on_ramp.approved.v1" / "operations.on_ramp.settled.v1" / "operations.on_ramp.failed.v1" / "operations.on_ramp.cancelled.v1" / "operations.off_ramp.requested.v1" / "operations.off_ramp.admissible.v1" / "operations.off_ramp.pending_approval.v1" / "operations.off_ramp.pending_compliance.v1" / "operations.off_ramp.approved.v1" / "operations.off_ramp.settled.v1" / "operations.off_ramp.failed.v1" / "operations.off_ramp.cancelled.v1" / "operations.deposit.requested.v1" / "operations.deposit.admissible.v1" / "operations.deposit.pending_approval.v1" / "operations.deposit.pending_admission.v1" / "operations.deposit.pending_compliance.v1" / "operations.deposit.approved.v1" / "operations.deposit.settled.v1" / "operations.deposit.failed.v1" / "operations.deposit.cancelled.v1" / "rails.deposit.detected.v1" / "rails.dispatch.acknowledged.v1" / "rails.dispatch.rejected.v1" / "rails.settlement.confirmed.v1" / "kyc.verification.reviewed.v1" / "loan.originated.v1" / "loan.origination_failed.v1" / "loan.margin_called.v1" / "loan.margin_call_cleared.v1" / "loan.liquidation_halted.v1" / "loan.liquidated.v1" / "loan.repaid.v1" / "loan.extended.v1" / "loan.closed.v1" / "loan.force_closed.v1" / "loan.reconciliation_discrepancy.v1" / "tenant.enterprise.*.v1" / "tenant.*.v1" / "tenant.platform_operator.*.v1" / "tenant.master_account.*.v1" / "tenant.client.*.v1" / "tenant.client_account.*.v1" / "ledger.transaction.*.v1" / "ledger.*.v1" / "operations.withdrawal.*.v1" / "operations.*.v1" / "operations.conversion.*.v1" / "operations.external_settlement_conversion.*.v1" / "operations.internal_transfer.*.v1" / "operations.on_ramp.*.v1" / "operations.off_ramp.*.v1" / "operations.deposit.*.v1" / "rails.deposit.*.v1" / "rails.*.v1" / "rails.dispatch.*.v1" / "rails.settlement.*.v1" / "kyc.verification.*.v1" / "kyc.*.v1" / "loan.loan.*.v1" / "loan.*.v1" / "identity.human_actor.created.v1" / "identity.human_actor.pending_created.v1" / "identity.human_actor.activated.v1" / "identity.human_actor.suspended.v1" / "identity.human_actor.reactivated.v1" / "identity.human_actor.deactivated.v1" / "identity.human_actor.updated.v1" / "identity.human_actor.federation_bound.v1" / "identity.human_actor.*.v1" / "identity.human_actor.access_resend_requested.v1" / "identity.human_actor.recovery_requested.v1"[] | Yes | minItems: 1 |
| `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)$` |
| `kind` | "public" / "identity" / "command" | Yes | Which catalog classes the subscription admits: public → public events; identity → public and identity events; command → command events only. |
| `managed_by` | string or null | Yes | identity_provider_id of the IdP row that owns a core-managed subscription; null for tenant-created ones. |
| `resource` | "webhook_subscription" | Yes |  |
| `scope_ref` | string or string | Yes | Webhook subscriptions can be scoped only to an enterprise or client. |
| `signing` | "hmac" / "asymmetric" | Yes | hmac: v1 HMAC header plus the v2 Ed25519 header; asymmetric: v2 only, verified against the published JWKS. |
| `status` | "active" / "paused" / "deleted" | Yes |  |
| `updated_at` | string or string | Yes |  |
| `url` | string | Yes | format: uri |

Additional fields are not accepted.

###### application/json body.items item.created_at

At least one alternative must match.

###### application/json body.items item.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.created_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.event_types

Type: `"*" / "tenant.enterprise.admission_reviewed.v1" / "tenant.enterprise.admitted.v1" / "tenant.enterprise.activated.v1" / "tenant.enterprise.updated.v1" / "tenant.enterprise.suspended.v1" / "tenant.enterprise.reactivated.v1" / "tenant.enterprise.closed.v1" / "tenant.enterprise.terminated.v1" / "tenant.platform_operator.admitted.v1" / "tenant.platform_operator.restricted.v1" / "tenant.platform_operator.reactivated.v1" / "tenant.platform_operator.offboarded.v1" / "tenant.platform_operator.catalog_updated.v1" / "tenant.master_account.created.v1" / "tenant.master_account.suspended.v1" / "tenant.master_account.closed.v1" / "tenant.client.created.v1" / "tenant.client.updated.v1" / "tenant.client.suspended.v1" / "tenant.client.reactivated.v1" / "tenant.client.closed.v1" / "tenant.client_account.created.v1" / "tenant.client_account.suspended.v1" / "tenant.client_account.reactivated.v1" / "tenant.client_account.closed.v1" / "ledger.transaction.posted.v1" / "operations.withdrawal.requested.v1" / "operations.withdrawal.admissible.v1" / "operations.withdrawal.executing.v1" / "operations.withdrawal.pending_approval.v1" / "operations.withdrawal.pending_compliance.v1" / "operations.withdrawal.approved.v1" / "operations.withdrawal.settled.v1" / "operations.withdrawal.failed.v1" / "operations.withdrawal.cancelled.v1" / "operations.conversion.requested.v1" / "operations.conversion.admissible.v1" / "operations.conversion.pending_approval.v1" / "operations.conversion.pending_compliance.v1" / "operations.conversion.approved.v1" / "operations.conversion.settled.v1" / "operations.conversion.failed.v1" / "operations.conversion.cancelled.v1" / "operations.external_settlement_conversion.pending_compliance.v1" / "operations.internal_transfer.requested.v1" / "operations.internal_transfer.admissible.v1" / "operations.internal_transfer.pending_approval.v1" / "operations.internal_transfer.pending_compliance.v1" / "operations.internal_transfer.approved.v1" / "operations.internal_transfer.settled.v1" / "operations.internal_transfer.failed.v1" / "operations.internal_transfer.cancelled.v1" / "operations.on_ramp.requested.v1" / "operations.on_ramp.admissible.v1" / "operations.on_ramp.pending_approval.v1" / "operations.on_ramp.pending_compliance.v1" / "operations.on_ramp.approved.v1" / "operations.on_ramp.settled.v1" / "operations.on_ramp.failed.v1" / "operations.on_ramp.cancelled.v1" / "operations.off_ramp.requested.v1" / "operations.off_ramp.admissible.v1" / "operations.off_ramp.pending_approval.v1" / "operations.off_ramp.pending_compliance.v1" / "operations.off_ramp.approved.v1" / "operations.off_ramp.settled.v1" / "operations.off_ramp.failed.v1" / "operations.off_ramp.cancelled.v1" / "operations.deposit.requested.v1" / "operations.deposit.admissible.v1" / "operations.deposit.pending_approval.v1" / "operations.deposit.pending_admission.v1" / "operations.deposit.pending_compliance.v1" / "operations.deposit.approved.v1" / "operations.deposit.settled.v1" / "operations.deposit.failed.v1" / "operations.deposit.cancelled.v1" / "rails.deposit.detected.v1" / "rails.dispatch.acknowledged.v1" / "rails.dispatch.rejected.v1" / "rails.settlement.confirmed.v1" / "kyc.verification.reviewed.v1" / "loan.originated.v1" / "loan.origination_failed.v1" / "loan.margin_called.v1" / "loan.margin_call_cleared.v1" / "loan.liquidation_halted.v1" / "loan.liquidated.v1" / "loan.repaid.v1" / "loan.extended.v1" / "loan.closed.v1" / "loan.force_closed.v1" / "loan.reconciliation_discrepancy.v1" / "tenant.enterprise.*.v1" / "tenant.*.v1" / "tenant.platform_operator.*.v1" / "tenant.master_account.*.v1" / "tenant.client.*.v1" / "tenant.client_account.*.v1" / "ledger.transaction.*.v1" / "ledger.*.v1" / "operations.withdrawal.*.v1" / "operations.*.v1" / "operations.conversion.*.v1" / "operations.external_settlement_conversion.*.v1" / "operations.internal_transfer.*.v1" / "operations.on_ramp.*.v1" / "operations.off_ramp.*.v1" / "operations.deposit.*.v1" / "rails.deposit.*.v1" / "rails.*.v1" / "rails.dispatch.*.v1" / "rails.settlement.*.v1" / "kyc.verification.*.v1" / "kyc.*.v1" / "loan.loan.*.v1" / "loan.*.v1" / "identity.human_actor.created.v1" / "identity.human_actor.pending_created.v1" / "identity.human_actor.activated.v1" / "identity.human_actor.suspended.v1" / "identity.human_actor.reactivated.v1" / "identity.human_actor.deactivated.v1" / "identity.human_actor.updated.v1" / "identity.human_actor.federation_bound.v1" / "identity.human_actor.*.v1" / "identity.human_actor.access_resend_requested.v1" / "identity.human_actor.recovery_requested.v1"[]`. minItems: 1

###### application/json body.items item.event_types item

Type: `"*" / "tenant.enterprise.admission_reviewed.v1" / "tenant.enterprise.admitted.v1" / "tenant.enterprise.activated.v1" / "tenant.enterprise.updated.v1" / "tenant.enterprise.suspended.v1" / "tenant.enterprise.reactivated.v1" / "tenant.enterprise.closed.v1" / "tenant.enterprise.terminated.v1" / "tenant.platform_operator.admitted.v1" / "tenant.platform_operator.restricted.v1" / "tenant.platform_operator.reactivated.v1" / "tenant.platform_operator.offboarded.v1" / "tenant.platform_operator.catalog_updated.v1" / "tenant.master_account.created.v1" / "tenant.master_account.suspended.v1" / "tenant.master_account.closed.v1" / "tenant.client.created.v1" / "tenant.client.updated.v1" / "tenant.client.suspended.v1" / "tenant.client.reactivated.v1" / "tenant.client.closed.v1" / "tenant.client_account.created.v1" / "tenant.client_account.suspended.v1" / "tenant.client_account.reactivated.v1" / "tenant.client_account.closed.v1" / "ledger.transaction.posted.v1" / "operations.withdrawal.requested.v1" / "operations.withdrawal.admissible.v1" / "operations.withdrawal.executing.v1" / "operations.withdrawal.pending_approval.v1" / "operations.withdrawal.pending_compliance.v1" / "operations.withdrawal.approved.v1" / "operations.withdrawal.settled.v1" / "operations.withdrawal.failed.v1" / "operations.withdrawal.cancelled.v1" / "operations.conversion.requested.v1" / "operations.conversion.admissible.v1" / "operations.conversion.pending_approval.v1" / "operations.conversion.pending_compliance.v1" / "operations.conversion.approved.v1" / "operations.conversion.settled.v1" / "operations.conversion.failed.v1" / "operations.conversion.cancelled.v1" / "operations.external_settlement_conversion.pending_compliance.v1" / "operations.internal_transfer.requested.v1" / "operations.internal_transfer.admissible.v1" / "operations.internal_transfer.pending_approval.v1" / "operations.internal_transfer.pending_compliance.v1" / "operations.internal_transfer.approved.v1" / "operations.internal_transfer.settled.v1" / "operations.internal_transfer.failed.v1" / "operations.internal_transfer.cancelled.v1" / "operations.on_ramp.requested.v1" / "operations.on_ramp.admissible.v1" / "operations.on_ramp.pending_approval.v1" / "operations.on_ramp.pending_compliance.v1" / "operations.on_ramp.approved.v1" / "operations.on_ramp.settled.v1" / "operations.on_ramp.failed.v1" / "operations.on_ramp.cancelled.v1" / "operations.off_ramp.requested.v1" / "operations.off_ramp.admissible.v1" / "operations.off_ramp.pending_approval.v1" / "operations.off_ramp.pending_compliance.v1" / "operations.off_ramp.approved.v1" / "operations.off_ramp.settled.v1" / "operations.off_ramp.failed.v1" / "operations.off_ramp.cancelled.v1" / "operations.deposit.requested.v1" / "operations.deposit.admissible.v1" / "operations.deposit.pending_approval.v1" / "operations.deposit.pending_admission.v1" / "operations.deposit.pending_compliance.v1" / "operations.deposit.approved.v1" / "operations.deposit.settled.v1" / "operations.deposit.failed.v1" / "operations.deposit.cancelled.v1" / "rails.deposit.detected.v1" / "rails.dispatch.acknowledged.v1" / "rails.dispatch.rejected.v1" / "rails.settlement.confirmed.v1" / "kyc.verification.reviewed.v1" / "loan.originated.v1" / "loan.origination_failed.v1" / "loan.margin_called.v1" / "loan.margin_call_cleared.v1" / "loan.liquidation_halted.v1" / "loan.liquidated.v1" / "loan.repaid.v1" / "loan.extended.v1" / "loan.closed.v1" / "loan.force_closed.v1" / "loan.reconciliation_discrepancy.v1" / "tenant.enterprise.*.v1" / "tenant.*.v1" / "tenant.platform_operator.*.v1" / "tenant.master_account.*.v1" / "tenant.client.*.v1" / "tenant.client_account.*.v1" / "ledger.transaction.*.v1" / "ledger.*.v1" / "operations.withdrawal.*.v1" / "operations.*.v1" / "operations.conversion.*.v1" / "operations.external_settlement_conversion.*.v1" / "operations.internal_transfer.*.v1" / "operations.on_ramp.*.v1" / "operations.off_ramp.*.v1" / "operations.deposit.*.v1" / "rails.deposit.*.v1" / "rails.*.v1" / "rails.dispatch.*.v1" / "rails.settlement.*.v1" / "kyc.verification.*.v1" / "kyc.*.v1" / "loan.loan.*.v1" / "loan.*.v1" / "identity.human_actor.created.v1" / "identity.human_actor.pending_created.v1" / "identity.human_actor.activated.v1" / "identity.human_actor.suspended.v1" / "identity.human_actor.reactivated.v1" / "identity.human_actor.deactivated.v1" / "identity.human_actor.updated.v1" / "identity.human_actor.federation_bound.v1" / "identity.human_actor.*.v1" / "identity.human_actor.access_resend_requested.v1" / "identity.human_actor.recovery_requested.v1"`. 

###### application/json body.items item.managed_by

identity_provider_id of the IdP row that owns a core-managed subscription; null for tenant-created ones.

At least one alternative must match.

###### application/json body.items item.managed_by: alternative 1

Type: `string`. 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)$`

###### application/json body.items item.managed_by: alternative 2

Type: `null`. 

###### application/json body.items item.scope_ref

Webhook subscriptions can be scoped only to an enterprise or client.

At least one alternative must match.

###### application/json body.items item.scope_ref: alternative 1

Type: `string`. pattern: `^(enterprises)\/([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})$`

###### application/json body.items item.scope_ref: alternative 2

Type: `string`. pattern: `^(clients)\/([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})$`

###### application/json body.items item.updated_at

At least one alternative must match.

###### application/json body.items item.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.updated_at: alternative 2

Type: `string`. format: date-time

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. 

###### application/json body.next_page_token: alternative 2

Type: `null`.


### webhook-subscriptions-list 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.


### webhook-subscriptions-list Response 401 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.


### webhook-subscriptions-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-list-response-401-schema).


### webhook-subscriptions-list Response 404 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-list-response-401-schema).


### webhook-subscriptions-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-list-response-401-schema).


### webhook-subscriptions-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#webhook-subscriptions-list-response-400-schema).


### webhook-subscriptions-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#webhook-subscriptions-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "created_at": "2026-05-01T10:00:00Z",
        "etag": "2026-05-01T10:00:00Z",
        "event_types": [
          "operations.withdrawal.settled.v1"
        ],
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "public",
        "managed_by": null,
        "resource": "webhook_subscription",
        "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "signing": "hmac",
        "status": "active",
        "updated_at": "2026-05-01T10:00:00Z",
        "url": "https://example.com/webhooks"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /webhook-subscriptions

**Create webhook subscription**

Creates an active webhook subscription. If omitted, `scope_ref` is derived from the authenticated enterprise or client context; absence of both returns 400. Only enterprise and client subscription scopes are accepted. Use a public HTTPS callback URL and a non-empty signing secret. Public catalog event types and documented group wildcards are accepted; command types are refused with `event_type_not_subscribable`. Identity event filters additionally require users.read covering the whole subscription scope.

**Required capability:** `webhooks.create`

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `event_types` | "*" / "tenant.enterprise.admission_reviewed.v1" / "tenant.enterprise.admitted.v1" / "tenant.enterprise.activated.v1" / "tenant.enterprise.updated.v1" / "tenant.enterprise.suspended.v1" / "tenant.enterprise.reactivated.v1" / "tenant.enterprise.closed.v1" / "tenant.enterprise.terminated.v1" / "tenant.platform_operator.admitted.v1" / "tenant.platform_operator.restricted.v1" / "tenant.platform_operator.reactivated.v1" / "tenant.platform_operator.offboarded.v1" / "tenant.platform_operator.catalog_updated.v1" / "tenant.master_account.created.v1" / "tenant.master_account.suspended.v1" / "tenant.master_account.closed.v1" / "tenant.client.created.v1" / "tenant.client.updated.v1" / "tenant.client.suspended.v1" / "tenant.client.reactivated.v1" / "tenant.client.closed.v1" / "tenant.client_account.created.v1" / "tenant.client_account.suspended.v1" / "tenant.client_account.reactivated.v1" / "tenant.client_account.closed.v1" / "ledger.transaction.posted.v1" / "operations.withdrawal.requested.v1" / "operations.withdrawal.admissible.v1" / "operations.withdrawal.executing.v1" / "operations.withdrawal.pending_approval.v1" / "operations.withdrawal.pending_compliance.v1" / "operations.withdrawal.approved.v1" / "operations.withdrawal.settled.v1" / "operations.withdrawal.failed.v1" / "operations.withdrawal.cancelled.v1" / "operations.conversion.requested.v1" / "operations.conversion.admissible.v1" / "operations.conversion.pending_approval.v1" / "operations.conversion.pending_compliance.v1" / "operations.conversion.approved.v1" / "operations.conversion.settled.v1" / "operations.conversion.failed.v1" / "operations.conversion.cancelled.v1" / "operations.external_settlement_conversion.pending_compliance.v1" / "operations.internal_transfer.requested.v1" / "operations.internal_transfer.admissible.v1" / "operations.internal_transfer.pending_approval.v1" / "operations.internal_transfer.pending_compliance.v1" / "operations.internal_transfer.approved.v1" / "operations.internal_transfer.settled.v1" / "operations.internal_transfer.failed.v1" / "operations.internal_transfer.cancelled.v1" / "operations.on_ramp.requested.v1" / "operations.on_ramp.admissible.v1" / "operations.on_ramp.pending_approval.v1" / "operations.on_ramp.pending_compliance.v1" / "operations.on_ramp.approved.v1" / "operations.on_ramp.settled.v1" / "operations.on_ramp.failed.v1" / "operations.on_ramp.cancelled.v1" / "operations.off_ramp.requested.v1" / "operations.off_ramp.admissible.v1" / "operations.off_ramp.pending_approval.v1" / "operations.off_ramp.pending_compliance.v1" / "operations.off_ramp.approved.v1" / "operations.off_ramp.settled.v1" / "operations.off_ramp.failed.v1" / "operations.off_ramp.cancelled.v1" / "operations.deposit.requested.v1" / "operations.deposit.admissible.v1" / "operations.deposit.pending_approval.v1" / "operations.deposit.pending_admission.v1" / "operations.deposit.pending_compliance.v1" / "operations.deposit.approved.v1" / "operations.deposit.settled.v1" / "operations.deposit.failed.v1" / "operations.deposit.cancelled.v1" / "rails.deposit.detected.v1" / "rails.dispatch.acknowledged.v1" / "rails.dispatch.rejected.v1" / "rails.settlement.confirmed.v1" / "kyc.verification.reviewed.v1" / "loan.originated.v1" / "loan.origination_failed.v1" / "loan.margin_called.v1" / "loan.margin_call_cleared.v1" / "loan.liquidation_halted.v1" / "loan.liquidated.v1" / "loan.repaid.v1" / "loan.extended.v1" / "loan.closed.v1" / "loan.force_closed.v1" / "loan.reconciliation_discrepancy.v1" / "tenant.enterprise.*.v1" / "tenant.*.v1" / "tenant.platform_operator.*.v1" / "tenant.master_account.*.v1" / "tenant.client.*.v1" / "tenant.client_account.*.v1" / "ledger.transaction.*.v1" / "ledger.*.v1" / "operations.withdrawal.*.v1" / "operations.*.v1" / "operations.conversion.*.v1" / "operations.external_settlement_conversion.*.v1" / "operations.internal_transfer.*.v1" / "operations.on_ramp.*.v1" / "operations.off_ramp.*.v1" / "operations.deposit.*.v1" / "rails.deposit.*.v1" / "rails.*.v1" / "rails.dispatch.*.v1" / "rails.settlement.*.v1" / "kyc.verification.*.v1" / "kyc.*.v1" / "loan.loan.*.v1" / "loan.*.v1" / "identity.human_actor.created.v1" / "identity.human_actor.pending_created.v1" / "identity.human_actor.activated.v1" / "identity.human_actor.suspended.v1" / "identity.human_actor.reactivated.v1" / "identity.human_actor.deactivated.v1" / "identity.human_actor.updated.v1" / "identity.human_actor.federation_bound.v1" / "identity.human_actor.*.v1"[] | Yes | Non-empty event type filter. Use ["*"] to subscribe to all event types; otherwise provide exact catalog event types or catalog-derived group wildcards such as "operations.withdrawal.*.v1" and "operations.*.v1". minItems: 1 |
| `scope_ref` | string or string | No | Webhook subscriptions can be scoped only to an enterprise or client. |
| `secret` | string | Yes | minLength: 1 |
| `url` | string | Yes | HTTPS callback URL on a public host. Plain http, private and internal addresses are refused with callback_url_not_allowed. format: uri |

Additional fields are not accepted.

#### Request body schema.event_types

Non-empty event type filter. Use ["*"] to subscribe to all event types; otherwise provide exact catalog event types or catalog-derived group wildcards such as "operations.withdrawal.*.v1" and "operations.*.v1".

Type: `"*" / "tenant.enterprise.admission_reviewed.v1" / "tenant.enterprise.admitted.v1" / "tenant.enterprise.activated.v1" / "tenant.enterprise.updated.v1" / "tenant.enterprise.suspended.v1" / "tenant.enterprise.reactivated.v1" / "tenant.enterprise.closed.v1" / "tenant.enterprise.terminated.v1" / "tenant.platform_operator.admitted.v1" / "tenant.platform_operator.restricted.v1" / "tenant.platform_operator.reactivated.v1" / "tenant.platform_operator.offboarded.v1" / "tenant.platform_operator.catalog_updated.v1" / "tenant.master_account.created.v1" / "tenant.master_account.suspended.v1" / "tenant.master_account.closed.v1" / "tenant.client.created.v1" / "tenant.client.updated.v1" / "tenant.client.suspended.v1" / "tenant.client.reactivated.v1" / "tenant.client.closed.v1" / "tenant.client_account.created.v1" / "tenant.client_account.suspended.v1" / "tenant.client_account.reactivated.v1" / "tenant.client_account.closed.v1" / "ledger.transaction.posted.v1" / "operations.withdrawal.requested.v1" / "operations.withdrawal.admissible.v1" / "operations.withdrawal.executing.v1" / "operations.withdrawal.pending_approval.v1" / "operations.withdrawal.pending_compliance.v1" / "operations.withdrawal.approved.v1" / "operations.withdrawal.settled.v1" / "operations.withdrawal.failed.v1" / "operations.withdrawal.cancelled.v1" / "operations.conversion.requested.v1" / "operations.conversion.admissible.v1" / "operations.conversion.pending_approval.v1" / "operations.conversion.pending_compliance.v1" / "operations.conversion.approved.v1" / "operations.conversion.settled.v1" / "operations.conversion.failed.v1" / "operations.conversion.cancelled.v1" / "operations.external_settlement_conversion.pending_compliance.v1" / "operations.internal_transfer.requested.v1" / "operations.internal_transfer.admissible.v1" / "operations.internal_transfer.pending_approval.v1" / "operations.internal_transfer.pending_compliance.v1" / "operations.internal_transfer.approved.v1" / "operations.internal_transfer.settled.v1" / "operations.internal_transfer.failed.v1" / "operations.internal_transfer.cancelled.v1" / "operations.on_ramp.requested.v1" / "operations.on_ramp.admissible.v1" / "operations.on_ramp.pending_approval.v1" / "operations.on_ramp.pending_compliance.v1" / "operations.on_ramp.approved.v1" / "operations.on_ramp.settled.v1" / "operations.on_ramp.failed.v1" / "operations.on_ramp.cancelled.v1" / "operations.off_ramp.requested.v1" / "operations.off_ramp.admissible.v1" / "operations.off_ramp.pending_approval.v1" / "operations.off_ramp.pending_compliance.v1" / "operations.off_ramp.approved.v1" / "operations.off_ramp.settled.v1" / "operations.off_ramp.failed.v1" / "operations.off_ramp.cancelled.v1" / "operations.deposit.requested.v1" / "operations.deposit.admissible.v1" / "operations.deposit.pending_approval.v1" / "operations.deposit.pending_admission.v1" / "operations.deposit.pending_compliance.v1" / "operations.deposit.approved.v1" / "operations.deposit.settled.v1" / "operations.deposit.failed.v1" / "operations.deposit.cancelled.v1" / "rails.deposit.detected.v1" / "rails.dispatch.acknowledged.v1" / "rails.dispatch.rejected.v1" / "rails.settlement.confirmed.v1" / "kyc.verification.reviewed.v1" / "loan.originated.v1" / "loan.origination_failed.v1" / "loan.margin_called.v1" / "loan.margin_call_cleared.v1" / "loan.liquidation_halted.v1" / "loan.liquidated.v1" / "loan.repaid.v1" / "loan.extended.v1" / "loan.closed.v1" / "loan.force_closed.v1" / "loan.reconciliation_discrepancy.v1" / "tenant.enterprise.*.v1" / "tenant.*.v1" / "tenant.platform_operator.*.v1" / "tenant.master_account.*.v1" / "tenant.client.*.v1" / "tenant.client_account.*.v1" / "ledger.transaction.*.v1" / "ledger.*.v1" / "operations.withdrawal.*.v1" / "operations.*.v1" / "operations.conversion.*.v1" / "operations.external_settlement_conversion.*.v1" / "operations.internal_transfer.*.v1" / "operations.on_ramp.*.v1" / "operations.off_ramp.*.v1" / "operations.deposit.*.v1" / "rails.deposit.*.v1" / "rails.*.v1" / "rails.dispatch.*.v1" / "rails.settlement.*.v1" / "kyc.verification.*.v1" / "kyc.*.v1" / "loan.loan.*.v1" / "loan.*.v1" / "identity.human_actor.created.v1" / "identity.human_actor.pending_created.v1" / "identity.human_actor.activated.v1" / "identity.human_actor.suspended.v1" / "identity.human_actor.reactivated.v1" / "identity.human_actor.deactivated.v1" / "identity.human_actor.updated.v1" / "identity.human_actor.federation_bound.v1" / "identity.human_actor.*.v1"[]`. minItems: 1

##### Request body schema.event_types item

Webhook event type filter value. Use exact catalog event types, "*" for every event, "<domain>.<resource>.*.v<major>" for a resource group, or "<domain>.*.v<major>" for a domain group.

Type: `"*" / "tenant.enterprise.admission_reviewed.v1" / "tenant.enterprise.admitted.v1" / "tenant.enterprise.activated.v1" / "tenant.enterprise.updated.v1" / "tenant.enterprise.suspended.v1" / "tenant.enterprise.reactivated.v1" / "tenant.enterprise.closed.v1" / "tenant.enterprise.terminated.v1" / "tenant.platform_operator.admitted.v1" / "tenant.platform_operator.restricted.v1" / "tenant.platform_operator.reactivated.v1" / "tenant.platform_operator.offboarded.v1" / "tenant.platform_operator.catalog_updated.v1" / "tenant.master_account.created.v1" / "tenant.master_account.suspended.v1" / "tenant.master_account.closed.v1" / "tenant.client.created.v1" / "tenant.client.updated.v1" / "tenant.client.suspended.v1" / "tenant.client.reactivated.v1" / "tenant.client.closed.v1" / "tenant.client_account.created.v1" / "tenant.client_account.suspended.v1" / "tenant.client_account.reactivated.v1" / "tenant.client_account.closed.v1" / "ledger.transaction.posted.v1" / "operations.withdrawal.requested.v1" / "operations.withdrawal.admissible.v1" / "operations.withdrawal.executing.v1" / "operations.withdrawal.pending_approval.v1" / "operations.withdrawal.pending_compliance.v1" / "operations.withdrawal.approved.v1" / "operations.withdrawal.settled.v1" / "operations.withdrawal.failed.v1" / "operations.withdrawal.cancelled.v1" / "operations.conversion.requested.v1" / "operations.conversion.admissible.v1" / "operations.conversion.pending_approval.v1" / "operations.conversion.pending_compliance.v1" / "operations.conversion.approved.v1" / "operations.conversion.settled.v1" / "operations.conversion.failed.v1" / "operations.conversion.cancelled.v1" / "operations.external_settlement_conversion.pending_compliance.v1" / "operations.internal_transfer.requested.v1" / "operations.internal_transfer.admissible.v1" / "operations.internal_transfer.pending_approval.v1" / "operations.internal_transfer.pending_compliance.v1" / "operations.internal_transfer.approved.v1" / "operations.internal_transfer.settled.v1" / "operations.internal_transfer.failed.v1" / "operations.internal_transfer.cancelled.v1" / "operations.on_ramp.requested.v1" / "operations.on_ramp.admissible.v1" / "operations.on_ramp.pending_approval.v1" / "operations.on_ramp.pending_compliance.v1" / "operations.on_ramp.approved.v1" / "operations.on_ramp.settled.v1" / "operations.on_ramp.failed.v1" / "operations.on_ramp.cancelled.v1" / "operations.off_ramp.requested.v1" / "operations.off_ramp.admissible.v1" / "operations.off_ramp.pending_approval.v1" / "operations.off_ramp.pending_compliance.v1" / "operations.off_ramp.approved.v1" / "operations.off_ramp.settled.v1" / "operations.off_ramp.failed.v1" / "operations.off_ramp.cancelled.v1" / "operations.deposit.requested.v1" / "operations.deposit.admissible.v1" / "operations.deposit.pending_approval.v1" / "operations.deposit.pending_admission.v1" / "operations.deposit.pending_compliance.v1" / "operations.deposit.approved.v1" / "operations.deposit.settled.v1" / "operations.deposit.failed.v1" / "operations.deposit.cancelled.v1" / "rails.deposit.detected.v1" / "rails.dispatch.acknowledged.v1" / "rails.dispatch.rejected.v1" / "rails.settlement.confirmed.v1" / "kyc.verification.reviewed.v1" / "loan.originated.v1" / "loan.origination_failed.v1" / "loan.margin_called.v1" / "loan.margin_call_cleared.v1" / "loan.liquidation_halted.v1" / "loan.liquidated.v1" / "loan.repaid.v1" / "loan.extended.v1" / "loan.closed.v1" / "loan.force_closed.v1" / "loan.reconciliation_discrepancy.v1" / "tenant.enterprise.*.v1" / "tenant.*.v1" / "tenant.platform_operator.*.v1" / "tenant.master_account.*.v1" / "tenant.client.*.v1" / "tenant.client_account.*.v1" / "ledger.transaction.*.v1" / "ledger.*.v1" / "operations.withdrawal.*.v1" / "operations.*.v1" / "operations.conversion.*.v1" / "operations.external_settlement_conversion.*.v1" / "operations.internal_transfer.*.v1" / "operations.on_ramp.*.v1" / "operations.off_ramp.*.v1" / "operations.deposit.*.v1" / "rails.deposit.*.v1" / "rails.*.v1" / "rails.dispatch.*.v1" / "rails.settlement.*.v1" / "kyc.verification.*.v1" / "kyc.*.v1" / "loan.loan.*.v1" / "loan.*.v1" / "identity.human_actor.created.v1" / "identity.human_actor.pending_created.v1" / "identity.human_actor.activated.v1" / "identity.human_actor.suspended.v1" / "identity.human_actor.reactivated.v1" / "identity.human_actor.deactivated.v1" / "identity.human_actor.updated.v1" / "identity.human_actor.federation_bound.v1" / "identity.human_actor.*.v1"`. 

#### Request body schema.scope_ref

Webhook subscriptions can be scoped only to an enterprise or client.

At least one alternative must match.

##### Request body schema.scope_ref: alternative 1

Type: `string`. pattern: `^(enterprises)\/([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})$`

##### Request body schema.scope_ref: alternative 2

Type: `string`. pattern: `^(clients)\/([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})$`

**Request example:**

```json
{
  "event_types": [
    "operations.withdrawal.settled.v1"
  ],
  "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "secret": "wh_secret_placeholder",
  "url": "https://example.com/webhooks"
}
```

### webhook-subscriptions-create Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `created_at` | string or string | Yes |  |
| `etag` | string | Yes | minLength: 1 |
| `event_types` | "*" / "tenant.enterprise.admission_reviewed.v1" / "tenant.enterprise.admitted.v1" / "tenant.enterprise.activated.v1" / "tenant.enterprise.updated.v1" / "tenant.enterprise.suspended.v1" / "tenant.enterprise.reactivated.v1" / "tenant.enterprise.closed.v1" / "tenant.enterprise.terminated.v1" / "tenant.platform_operator.admitted.v1" / "tenant.platform_operator.restricted.v1" / "tenant.platform_operator.reactivated.v1" / "tenant.platform_operator.offboarded.v1" / "tenant.platform_operator.catalog_updated.v1" / "tenant.master_account.created.v1" / "tenant.master_account.suspended.v1" / "tenant.master_account.closed.v1" / "tenant.client.created.v1" / "tenant.client.updated.v1" / "tenant.client.suspended.v1" / "tenant.client.reactivated.v1" / "tenant.client.closed.v1" / "tenant.client_account.created.v1" / "tenant.client_account.suspended.v1" / "tenant.client_account.reactivated.v1" / "tenant.client_account.closed.v1" / "ledger.transaction.posted.v1" / "operations.withdrawal.requested.v1" / "operations.withdrawal.admissible.v1" / "operations.withdrawal.executing.v1" / "operations.withdrawal.pending_approval.v1" / "operations.withdrawal.pending_compliance.v1" / "operations.withdrawal.approved.v1" / "operations.withdrawal.settled.v1" / "operations.withdrawal.failed.v1" / "operations.withdrawal.cancelled.v1" / "operations.conversion.requested.v1" / "operations.conversion.admissible.v1" / "operations.conversion.pending_approval.v1" / "operations.conversion.pending_compliance.v1" / "operations.conversion.approved.v1" / "operations.conversion.settled.v1" / "operations.conversion.failed.v1" / "operations.conversion.cancelled.v1" / "operations.external_settlement_conversion.pending_compliance.v1" / "operations.internal_transfer.requested.v1" / "operations.internal_transfer.admissible.v1" / "operations.internal_transfer.pending_approval.v1" / "operations.internal_transfer.pending_compliance.v1" / "operations.internal_transfer.approved.v1" / "operations.internal_transfer.settled.v1" / "operations.internal_transfer.failed.v1" / "operations.internal_transfer.cancelled.v1" / "operations.on_ramp.requested.v1" / "operations.on_ramp.admissible.v1" / "operations.on_ramp.pending_approval.v1" / "operations.on_ramp.pending_compliance.v1" / "operations.on_ramp.approved.v1" / "operations.on_ramp.settled.v1" / "operations.on_ramp.failed.v1" / "operations.on_ramp.cancelled.v1" / "operations.off_ramp.requested.v1" / "operations.off_ramp.admissible.v1" / "operations.off_ramp.pending_approval.v1" / "operations.off_ramp.pending_compliance.v1" / "operations.off_ramp.approved.v1" / "operations.off_ramp.settled.v1" / "operations.off_ramp.failed.v1" / "operations.off_ramp.cancelled.v1" / "operations.deposit.requested.v1" / "operations.deposit.admissible.v1" / "operations.deposit.pending_approval.v1" / "operations.deposit.pending_admission.v1" / "operations.deposit.pending_compliance.v1" / "operations.deposit.approved.v1" / "operations.deposit.settled.v1" / "operations.deposit.failed.v1" / "operations.deposit.cancelled.v1" / "rails.deposit.detected.v1" / "rails.dispatch.acknowledged.v1" / "rails.dispatch.rejected.v1" / "rails.settlement.confirmed.v1" / "kyc.verification.reviewed.v1" / "loan.originated.v1" / "loan.origination_failed.v1" / "loan.margin_called.v1" / "loan.margin_call_cleared.v1" / "loan.liquidation_halted.v1" / "loan.liquidated.v1" / "loan.repaid.v1" / "loan.extended.v1" / "loan.closed.v1" / "loan.force_closed.v1" / "loan.reconciliation_discrepancy.v1" / "tenant.enterprise.*.v1" / "tenant.*.v1" / "tenant.platform_operator.*.v1" / "tenant.master_account.*.v1" / "tenant.client.*.v1" / "tenant.client_account.*.v1" / "ledger.transaction.*.v1" / "ledger.*.v1" / "operations.withdrawal.*.v1" / "operations.*.v1" / "operations.conversion.*.v1" / "operations.external_settlement_conversion.*.v1" / "operations.internal_transfer.*.v1" / "operations.on_ramp.*.v1" / "operations.off_ramp.*.v1" / "operations.deposit.*.v1" / "rails.deposit.*.v1" / "rails.*.v1" / "rails.dispatch.*.v1" / "rails.settlement.*.v1" / "kyc.verification.*.v1" / "kyc.*.v1" / "loan.loan.*.v1" / "loan.*.v1" / "identity.human_actor.created.v1" / "identity.human_actor.pending_created.v1" / "identity.human_actor.activated.v1" / "identity.human_actor.suspended.v1" / "identity.human_actor.reactivated.v1" / "identity.human_actor.deactivated.v1" / "identity.human_actor.updated.v1" / "identity.human_actor.federation_bound.v1" / "identity.human_actor.*.v1" / "identity.human_actor.access_resend_requested.v1" / "identity.human_actor.recovery_requested.v1"[] | Yes | minItems: 1 |
| `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)$` |
| `kind` | "public" / "identity" / "command" | Yes | Which catalog classes the subscription admits: public → public events; identity → public and identity events; command → command events only. |
| `managed_by` | string or null | Yes | identity_provider_id of the IdP row that owns a core-managed subscription; null for tenant-created ones. |
| `resource` | "webhook_subscription" | Yes |  |
| `scope_ref` | string or string | Yes | Webhook subscriptions can be scoped only to an enterprise or client. |
| `signing` | "hmac" / "asymmetric" | Yes | hmac: v1 HMAC header plus the v2 Ed25519 header; asymmetric: v2 only, verified against the published JWKS. |
| `status` | "active" / "paused" / "deleted" | Yes |  |
| `updated_at` | string or string | Yes |  |
| `url` | string | Yes | format: uri |

Additional fields are not accepted.

##### application/json body.created_at

At least one alternative must match.

###### application/json body.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.created_at: alternative 2

Type: `string`. format: date-time

##### application/json body.event_types

Type: `"*" / "tenant.enterprise.admission_reviewed.v1" / "tenant.enterprise.admitted.v1" / "tenant.enterprise.activated.v1" / "tenant.enterprise.updated.v1" / "tenant.enterprise.suspended.v1" / "tenant.enterprise.reactivated.v1" / "tenant.enterprise.closed.v1" / "tenant.enterprise.terminated.v1" / "tenant.platform_operator.admitted.v1" / "tenant.platform_operator.restricted.v1" / "tenant.platform_operator.reactivated.v1" / "tenant.platform_operator.offboarded.v1" / "tenant.platform_operator.catalog_updated.v1" / "tenant.master_account.created.v1" / "tenant.master_account.suspended.v1" / "tenant.master_account.closed.v1" / "tenant.client.created.v1" / "tenant.client.updated.v1" / "tenant.client.suspended.v1" / "tenant.client.reactivated.v1" / "tenant.client.closed.v1" / "tenant.client_account.created.v1" / "tenant.client_account.suspended.v1" / "tenant.client_account.reactivated.v1" / "tenant.client_account.closed.v1" / "ledger.transaction.posted.v1" / "operations.withdrawal.requested.v1" / "operations.withdrawal.admissible.v1" / "operations.withdrawal.executing.v1" / "operations.withdrawal.pending_approval.v1" / "operations.withdrawal.pending_compliance.v1" / "operations.withdrawal.approved.v1" / "operations.withdrawal.settled.v1" / "operations.withdrawal.failed.v1" / "operations.withdrawal.cancelled.v1" / "operations.conversion.requested.v1" / "operations.conversion.admissible.v1" / "operations.conversion.pending_approval.v1" / "operations.conversion.pending_compliance.v1" / "operations.conversion.approved.v1" / "operations.conversion.settled.v1" / "operations.conversion.failed.v1" / "operations.conversion.cancelled.v1" / "operations.external_settlement_conversion.pending_compliance.v1" / "operations.internal_transfer.requested.v1" / "operations.internal_transfer.admissible.v1" / "operations.internal_transfer.pending_approval.v1" / "operations.internal_transfer.pending_compliance.v1" / "operations.internal_transfer.approved.v1" / "operations.internal_transfer.settled.v1" / "operations.internal_transfer.failed.v1" / "operations.internal_transfer.cancelled.v1" / "operations.on_ramp.requested.v1" / "operations.on_ramp.admissible.v1" / "operations.on_ramp.pending_approval.v1" / "operations.on_ramp.pending_compliance.v1" / "operations.on_ramp.approved.v1" / "operations.on_ramp.settled.v1" / "operations.on_ramp.failed.v1" / "operations.on_ramp.cancelled.v1" / "operations.off_ramp.requested.v1" / "operations.off_ramp.admissible.v1" / "operations.off_ramp.pending_approval.v1" / "operations.off_ramp.pending_compliance.v1" / "operations.off_ramp.approved.v1" / "operations.off_ramp.settled.v1" / "operations.off_ramp.failed.v1" / "operations.off_ramp.cancelled.v1" / "operations.deposit.requested.v1" / "operations.deposit.admissible.v1" / "operations.deposit.pending_approval.v1" / "operations.deposit.pending_admission.v1" / "operations.deposit.pending_compliance.v1" / "operations.deposit.approved.v1" / "operations.deposit.settled.v1" / "operations.deposit.failed.v1" / "operations.deposit.cancelled.v1" / "rails.deposit.detected.v1" / "rails.dispatch.acknowledged.v1" / "rails.dispatch.rejected.v1" / "rails.settlement.confirmed.v1" / "kyc.verification.reviewed.v1" / "loan.originated.v1" / "loan.origination_failed.v1" / "loan.margin_called.v1" / "loan.margin_call_cleared.v1" / "loan.liquidation_halted.v1" / "loan.liquidated.v1" / "loan.repaid.v1" / "loan.extended.v1" / "loan.closed.v1" / "loan.force_closed.v1" / "loan.reconciliation_discrepancy.v1" / "tenant.enterprise.*.v1" / "tenant.*.v1" / "tenant.platform_operator.*.v1" / "tenant.master_account.*.v1" / "tenant.client.*.v1" / "tenant.client_account.*.v1" / "ledger.transaction.*.v1" / "ledger.*.v1" / "operations.withdrawal.*.v1" / "operations.*.v1" / "operations.conversion.*.v1" / "operations.external_settlement_conversion.*.v1" / "operations.internal_transfer.*.v1" / "operations.on_ramp.*.v1" / "operations.off_ramp.*.v1" / "operations.deposit.*.v1" / "rails.deposit.*.v1" / "rails.*.v1" / "rails.dispatch.*.v1" / "rails.settlement.*.v1" / "kyc.verification.*.v1" / "kyc.*.v1" / "loan.loan.*.v1" / "loan.*.v1" / "identity.human_actor.created.v1" / "identity.human_actor.pending_created.v1" / "identity.human_actor.activated.v1" / "identity.human_actor.suspended.v1" / "identity.human_actor.reactivated.v1" / "identity.human_actor.deactivated.v1" / "identity.human_actor.updated.v1" / "identity.human_actor.federation_bound.v1" / "identity.human_actor.*.v1" / "identity.human_actor.access_resend_requested.v1" / "identity.human_actor.recovery_requested.v1"[]`. minItems: 1

###### application/json body.event_types item

Type: `"*" / "tenant.enterprise.admission_reviewed.v1" / "tenant.enterprise.admitted.v1" / "tenant.enterprise.activated.v1" / "tenant.enterprise.updated.v1" / "tenant.enterprise.suspended.v1" / "tenant.enterprise.reactivated.v1" / "tenant.enterprise.closed.v1" / "tenant.enterprise.terminated.v1" / "tenant.platform_operator.admitted.v1" / "tenant.platform_operator.restricted.v1" / "tenant.platform_operator.reactivated.v1" / "tenant.platform_operator.offboarded.v1" / "tenant.platform_operator.catalog_updated.v1" / "tenant.master_account.created.v1" / "tenant.master_account.suspended.v1" / "tenant.master_account.closed.v1" / "tenant.client.created.v1" / "tenant.client.updated.v1" / "tenant.client.suspended.v1" / "tenant.client.reactivated.v1" / "tenant.client.closed.v1" / "tenant.client_account.created.v1" / "tenant.client_account.suspended.v1" / "tenant.client_account.reactivated.v1" / "tenant.client_account.closed.v1" / "ledger.transaction.posted.v1" / "operations.withdrawal.requested.v1" / "operations.withdrawal.admissible.v1" / "operations.withdrawal.executing.v1" / "operations.withdrawal.pending_approval.v1" / "operations.withdrawal.pending_compliance.v1" / "operations.withdrawal.approved.v1" / "operations.withdrawal.settled.v1" / "operations.withdrawal.failed.v1" / "operations.withdrawal.cancelled.v1" / "operations.conversion.requested.v1" / "operations.conversion.admissible.v1" / "operations.conversion.pending_approval.v1" / "operations.conversion.pending_compliance.v1" / "operations.conversion.approved.v1" / "operations.conversion.settled.v1" / "operations.conversion.failed.v1" / "operations.conversion.cancelled.v1" / "operations.external_settlement_conversion.pending_compliance.v1" / "operations.internal_transfer.requested.v1" / "operations.internal_transfer.admissible.v1" / "operations.internal_transfer.pending_approval.v1" / "operations.internal_transfer.pending_compliance.v1" / "operations.internal_transfer.approved.v1" / "operations.internal_transfer.settled.v1" / "operations.internal_transfer.failed.v1" / "operations.internal_transfer.cancelled.v1" / "operations.on_ramp.requested.v1" / "operations.on_ramp.admissible.v1" / "operations.on_ramp.pending_approval.v1" / "operations.on_ramp.pending_compliance.v1" / "operations.on_ramp.approved.v1" / "operations.on_ramp.settled.v1" / "operations.on_ramp.failed.v1" / "operations.on_ramp.cancelled.v1" / "operations.off_ramp.requested.v1" / "operations.off_ramp.admissible.v1" / "operations.off_ramp.pending_approval.v1" / "operations.off_ramp.pending_compliance.v1" / "operations.off_ramp.approved.v1" / "operations.off_ramp.settled.v1" / "operations.off_ramp.failed.v1" / "operations.off_ramp.cancelled.v1" / "operations.deposit.requested.v1" / "operations.deposit.admissible.v1" / "operations.deposit.pending_approval.v1" / "operations.deposit.pending_admission.v1" / "operations.deposit.pending_compliance.v1" / "operations.deposit.approved.v1" / "operations.deposit.settled.v1" / "operations.deposit.failed.v1" / "operations.deposit.cancelled.v1" / "rails.deposit.detected.v1" / "rails.dispatch.acknowledged.v1" / "rails.dispatch.rejected.v1" / "rails.settlement.confirmed.v1" / "kyc.verification.reviewed.v1" / "loan.originated.v1" / "loan.origination_failed.v1" / "loan.margin_called.v1" / "loan.margin_call_cleared.v1" / "loan.liquidation_halted.v1" / "loan.liquidated.v1" / "loan.repaid.v1" / "loan.extended.v1" / "loan.closed.v1" / "loan.force_closed.v1" / "loan.reconciliation_discrepancy.v1" / "tenant.enterprise.*.v1" / "tenant.*.v1" / "tenant.platform_operator.*.v1" / "tenant.master_account.*.v1" / "tenant.client.*.v1" / "tenant.client_account.*.v1" / "ledger.transaction.*.v1" / "ledger.*.v1" / "operations.withdrawal.*.v1" / "operations.*.v1" / "operations.conversion.*.v1" / "operations.external_settlement_conversion.*.v1" / "operations.internal_transfer.*.v1" / "operations.on_ramp.*.v1" / "operations.off_ramp.*.v1" / "operations.deposit.*.v1" / "rails.deposit.*.v1" / "rails.*.v1" / "rails.dispatch.*.v1" / "rails.settlement.*.v1" / "kyc.verification.*.v1" / "kyc.*.v1" / "loan.loan.*.v1" / "loan.*.v1" / "identity.human_actor.created.v1" / "identity.human_actor.pending_created.v1" / "identity.human_actor.activated.v1" / "identity.human_actor.suspended.v1" / "identity.human_actor.reactivated.v1" / "identity.human_actor.deactivated.v1" / "identity.human_actor.updated.v1" / "identity.human_actor.federation_bound.v1" / "identity.human_actor.*.v1" / "identity.human_actor.access_resend_requested.v1" / "identity.human_actor.recovery_requested.v1"`. 

##### application/json body.managed_by

identity_provider_id of the IdP row that owns a core-managed subscription; null for tenant-created ones.

At least one alternative must match.

###### application/json body.managed_by: alternative 1

Type: `string`. 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)$`

###### application/json body.managed_by: alternative 2

Type: `null`. 

##### application/json body.scope_ref

Webhook subscriptions can be scoped only to an enterprise or client.

At least one alternative must match.

###### application/json body.scope_ref: alternative 1

Type: `string`. pattern: `^(enterprises)\/([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})$`

###### application/json body.scope_ref: alternative 2

Type: `string`. pattern: `^(clients)\/([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})$`

##### application/json body.updated_at

At least one alternative must match.

###### application/json body.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.updated_at: alternative 2

Type: `string`. format: date-time


### webhook-subscriptions-create 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.


### webhook-subscriptions-create Response 401 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.


### webhook-subscriptions-create Response 403 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-create-response-401-schema).


### webhook-subscriptions-create Response 404 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-create-response-401-schema).


### webhook-subscriptions-create Response 409 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-create-response-401-schema).


### webhook-subscriptions-create Response 500 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-create-response-401-schema).


### webhook-subscriptions-create Response 502 schema

Content type: `application/json`.

See [response 400 schema](#webhook-subscriptions-create-response-400-schema).


### webhook-subscriptions-create Response 503 schema

Content type: `application/json`.

See [response 400 schema](#webhook-subscriptions-create-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "created_at": "2026-05-01T10:00:00Z",
    "etag": "2026-05-01T10:00:00Z",
    "event_types": [
      "operations.withdrawal.settled.v1"
    ],
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "kind": "public",
    "managed_by": null,
    "resource": "webhook_subscription",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "signing": "hmac",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z",
    "url": "https://example.com/webhooks"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /webhook-subscriptions/{subscription_id}

**Get webhook subscription**

**Required capability:** `webhooks.read`

**Authentication:** Bearer token required.

**Parameters:**

- `subscription_id` `string` (path) *(required)*

### webhook-subscriptions-get Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `created_at` | string or string | Yes |  |
| `etag` | string | Yes | minLength: 1 |
| `event_types` | "*" / "tenant.enterprise.admission_reviewed.v1" / "tenant.enterprise.admitted.v1" / "tenant.enterprise.activated.v1" / "tenant.enterprise.updated.v1" / "tenant.enterprise.suspended.v1" / "tenant.enterprise.reactivated.v1" / "tenant.enterprise.closed.v1" / "tenant.enterprise.terminated.v1" / "tenant.platform_operator.admitted.v1" / "tenant.platform_operator.restricted.v1" / "tenant.platform_operator.reactivated.v1" / "tenant.platform_operator.offboarded.v1" / "tenant.platform_operator.catalog_updated.v1" / "tenant.master_account.created.v1" / "tenant.master_account.suspended.v1" / "tenant.master_account.closed.v1" / "tenant.client.created.v1" / "tenant.client.updated.v1" / "tenant.client.suspended.v1" / "tenant.client.reactivated.v1" / "tenant.client.closed.v1" / "tenant.client_account.created.v1" / "tenant.client_account.suspended.v1" / "tenant.client_account.reactivated.v1" / "tenant.client_account.closed.v1" / "ledger.transaction.posted.v1" / "operations.withdrawal.requested.v1" / "operations.withdrawal.admissible.v1" / "operations.withdrawal.executing.v1" / "operations.withdrawal.pending_approval.v1" / "operations.withdrawal.pending_compliance.v1" / "operations.withdrawal.approved.v1" / "operations.withdrawal.settled.v1" / "operations.withdrawal.failed.v1" / "operations.withdrawal.cancelled.v1" / "operations.conversion.requested.v1" / "operations.conversion.admissible.v1" / "operations.conversion.pending_approval.v1" / "operations.conversion.pending_compliance.v1" / "operations.conversion.approved.v1" / "operations.conversion.settled.v1" / "operations.conversion.failed.v1" / "operations.conversion.cancelled.v1" / "operations.external_settlement_conversion.pending_compliance.v1" / "operations.internal_transfer.requested.v1" / "operations.internal_transfer.admissible.v1" / "operations.internal_transfer.pending_approval.v1" / "operations.internal_transfer.pending_compliance.v1" / "operations.internal_transfer.approved.v1" / "operations.internal_transfer.settled.v1" / "operations.internal_transfer.failed.v1" / "operations.internal_transfer.cancelled.v1" / "operations.on_ramp.requested.v1" / "operations.on_ramp.admissible.v1" / "operations.on_ramp.pending_approval.v1" / "operations.on_ramp.pending_compliance.v1" / "operations.on_ramp.approved.v1" / "operations.on_ramp.settled.v1" / "operations.on_ramp.failed.v1" / "operations.on_ramp.cancelled.v1" / "operations.off_ramp.requested.v1" / "operations.off_ramp.admissible.v1" / "operations.off_ramp.pending_approval.v1" / "operations.off_ramp.pending_compliance.v1" / "operations.off_ramp.approved.v1" / "operations.off_ramp.settled.v1" / "operations.off_ramp.failed.v1" / "operations.off_ramp.cancelled.v1" / "operations.deposit.requested.v1" / "operations.deposit.admissible.v1" / "operations.deposit.pending_approval.v1" / "operations.deposit.pending_admission.v1" / "operations.deposit.pending_compliance.v1" / "operations.deposit.approved.v1" / "operations.deposit.settled.v1" / "operations.deposit.failed.v1" / "operations.deposit.cancelled.v1" / "rails.deposit.detected.v1" / "rails.dispatch.acknowledged.v1" / "rails.dispatch.rejected.v1" / "rails.settlement.confirmed.v1" / "kyc.verification.reviewed.v1" / "loan.originated.v1" / "loan.origination_failed.v1" / "loan.margin_called.v1" / "loan.margin_call_cleared.v1" / "loan.liquidation_halted.v1" / "loan.liquidated.v1" / "loan.repaid.v1" / "loan.extended.v1" / "loan.closed.v1" / "loan.force_closed.v1" / "loan.reconciliation_discrepancy.v1" / "tenant.enterprise.*.v1" / "tenant.*.v1" / "tenant.platform_operator.*.v1" / "tenant.master_account.*.v1" / "tenant.client.*.v1" / "tenant.client_account.*.v1" / "ledger.transaction.*.v1" / "ledger.*.v1" / "operations.withdrawal.*.v1" / "operations.*.v1" / "operations.conversion.*.v1" / "operations.external_settlement_conversion.*.v1" / "operations.internal_transfer.*.v1" / "operations.on_ramp.*.v1" / "operations.off_ramp.*.v1" / "operations.deposit.*.v1" / "rails.deposit.*.v1" / "rails.*.v1" / "rails.dispatch.*.v1" / "rails.settlement.*.v1" / "kyc.verification.*.v1" / "kyc.*.v1" / "loan.loan.*.v1" / "loan.*.v1" / "identity.human_actor.created.v1" / "identity.human_actor.pending_created.v1" / "identity.human_actor.activated.v1" / "identity.human_actor.suspended.v1" / "identity.human_actor.reactivated.v1" / "identity.human_actor.deactivated.v1" / "identity.human_actor.updated.v1" / "identity.human_actor.federation_bound.v1" / "identity.human_actor.*.v1" / "identity.human_actor.access_resend_requested.v1" / "identity.human_actor.recovery_requested.v1"[] | Yes | minItems: 1 |
| `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)$` |
| `kind` | "public" / "identity" / "command" | Yes | Which catalog classes the subscription admits: public → public events; identity → public and identity events; command → command events only. |
| `managed_by` | string or null | Yes | identity_provider_id of the IdP row that owns a core-managed subscription; null for tenant-created ones. |
| `resource` | "webhook_subscription" | Yes |  |
| `scope_ref` | string or string | Yes | Webhook subscriptions can be scoped only to an enterprise or client. |
| `signing` | "hmac" / "asymmetric" | Yes | hmac: v1 HMAC header plus the v2 Ed25519 header; asymmetric: v2 only, verified against the published JWKS. |
| `status` | "active" / "paused" / "deleted" | Yes |  |
| `updated_at` | string or string | Yes |  |
| `url` | string | Yes | format: uri |

Additional fields are not accepted.

##### application/json body.created_at

At least one alternative must match.

###### application/json body.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.created_at: alternative 2

Type: `string`. format: date-time

##### application/json body.event_types

Type: `"*" / "tenant.enterprise.admission_reviewed.v1" / "tenant.enterprise.admitted.v1" / "tenant.enterprise.activated.v1" / "tenant.enterprise.updated.v1" / "tenant.enterprise.suspended.v1" / "tenant.enterprise.reactivated.v1" / "tenant.enterprise.closed.v1" / "tenant.enterprise.terminated.v1" / "tenant.platform_operator.admitted.v1" / "tenant.platform_operator.restricted.v1" / "tenant.platform_operator.reactivated.v1" / "tenant.platform_operator.offboarded.v1" / "tenant.platform_operator.catalog_updated.v1" / "tenant.master_account.created.v1" / "tenant.master_account.suspended.v1" / "tenant.master_account.closed.v1" / "tenant.client.created.v1" / "tenant.client.updated.v1" / "tenant.client.suspended.v1" / "tenant.client.reactivated.v1" / "tenant.client.closed.v1" / "tenant.client_account.created.v1" / "tenant.client_account.suspended.v1" / "tenant.client_account.reactivated.v1" / "tenant.client_account.closed.v1" / "ledger.transaction.posted.v1" / "operations.withdrawal.requested.v1" / "operations.withdrawal.admissible.v1" / "operations.withdrawal.executing.v1" / "operations.withdrawal.pending_approval.v1" / "operations.withdrawal.pending_compliance.v1" / "operations.withdrawal.approved.v1" / "operations.withdrawal.settled.v1" / "operations.withdrawal.failed.v1" / "operations.withdrawal.cancelled.v1" / "operations.conversion.requested.v1" / "operations.conversion.admissible.v1" / "operations.conversion.pending_approval.v1" / "operations.conversion.pending_compliance.v1" / "operations.conversion.approved.v1" / "operations.conversion.settled.v1" / "operations.conversion.failed.v1" / "operations.conversion.cancelled.v1" / "operations.external_settlement_conversion.pending_compliance.v1" / "operations.internal_transfer.requested.v1" / "operations.internal_transfer.admissible.v1" / "operations.internal_transfer.pending_approval.v1" / "operations.internal_transfer.pending_compliance.v1" / "operations.internal_transfer.approved.v1" / "operations.internal_transfer.settled.v1" / "operations.internal_transfer.failed.v1" / "operations.internal_transfer.cancelled.v1" / "operations.on_ramp.requested.v1" / "operations.on_ramp.admissible.v1" / "operations.on_ramp.pending_approval.v1" / "operations.on_ramp.pending_compliance.v1" / "operations.on_ramp.approved.v1" / "operations.on_ramp.settled.v1" / "operations.on_ramp.failed.v1" / "operations.on_ramp.cancelled.v1" / "operations.off_ramp.requested.v1" / "operations.off_ramp.admissible.v1" / "operations.off_ramp.pending_approval.v1" / "operations.off_ramp.pending_compliance.v1" / "operations.off_ramp.approved.v1" / "operations.off_ramp.settled.v1" / "operations.off_ramp.failed.v1" / "operations.off_ramp.cancelled.v1" / "operations.deposit.requested.v1" / "operations.deposit.admissible.v1" / "operations.deposit.pending_approval.v1" / "operations.deposit.pending_admission.v1" / "operations.deposit.pending_compliance.v1" / "operations.deposit.approved.v1" / "operations.deposit.settled.v1" / "operations.deposit.failed.v1" / "operations.deposit.cancelled.v1" / "rails.deposit.detected.v1" / "rails.dispatch.acknowledged.v1" / "rails.dispatch.rejected.v1" / "rails.settlement.confirmed.v1" / "kyc.verification.reviewed.v1" / "loan.originated.v1" / "loan.origination_failed.v1" / "loan.margin_called.v1" / "loan.margin_call_cleared.v1" / "loan.liquidation_halted.v1" / "loan.liquidated.v1" / "loan.repaid.v1" / "loan.extended.v1" / "loan.closed.v1" / "loan.force_closed.v1" / "loan.reconciliation_discrepancy.v1" / "tenant.enterprise.*.v1" / "tenant.*.v1" / "tenant.platform_operator.*.v1" / "tenant.master_account.*.v1" / "tenant.client.*.v1" / "tenant.client_account.*.v1" / "ledger.transaction.*.v1" / "ledger.*.v1" / "operations.withdrawal.*.v1" / "operations.*.v1" / "operations.conversion.*.v1" / "operations.external_settlement_conversion.*.v1" / "operations.internal_transfer.*.v1" / "operations.on_ramp.*.v1" / "operations.off_ramp.*.v1" / "operations.deposit.*.v1" / "rails.deposit.*.v1" / "rails.*.v1" / "rails.dispatch.*.v1" / "rails.settlement.*.v1" / "kyc.verification.*.v1" / "kyc.*.v1" / "loan.loan.*.v1" / "loan.*.v1" / "identity.human_actor.created.v1" / "identity.human_actor.pending_created.v1" / "identity.human_actor.activated.v1" / "identity.human_actor.suspended.v1" / "identity.human_actor.reactivated.v1" / "identity.human_actor.deactivated.v1" / "identity.human_actor.updated.v1" / "identity.human_actor.federation_bound.v1" / "identity.human_actor.*.v1" / "identity.human_actor.access_resend_requested.v1" / "identity.human_actor.recovery_requested.v1"[]`. minItems: 1

###### application/json body.event_types item

Type: `"*" / "tenant.enterprise.admission_reviewed.v1" / "tenant.enterprise.admitted.v1" / "tenant.enterprise.activated.v1" / "tenant.enterprise.updated.v1" / "tenant.enterprise.suspended.v1" / "tenant.enterprise.reactivated.v1" / "tenant.enterprise.closed.v1" / "tenant.enterprise.terminated.v1" / "tenant.platform_operator.admitted.v1" / "tenant.platform_operator.restricted.v1" / "tenant.platform_operator.reactivated.v1" / "tenant.platform_operator.offboarded.v1" / "tenant.platform_operator.catalog_updated.v1" / "tenant.master_account.created.v1" / "tenant.master_account.suspended.v1" / "tenant.master_account.closed.v1" / "tenant.client.created.v1" / "tenant.client.updated.v1" / "tenant.client.suspended.v1" / "tenant.client.reactivated.v1" / "tenant.client.closed.v1" / "tenant.client_account.created.v1" / "tenant.client_account.suspended.v1" / "tenant.client_account.reactivated.v1" / "tenant.client_account.closed.v1" / "ledger.transaction.posted.v1" / "operations.withdrawal.requested.v1" / "operations.withdrawal.admissible.v1" / "operations.withdrawal.executing.v1" / "operations.withdrawal.pending_approval.v1" / "operations.withdrawal.pending_compliance.v1" / "operations.withdrawal.approved.v1" / "operations.withdrawal.settled.v1" / "operations.withdrawal.failed.v1" / "operations.withdrawal.cancelled.v1" / "operations.conversion.requested.v1" / "operations.conversion.admissible.v1" / "operations.conversion.pending_approval.v1" / "operations.conversion.pending_compliance.v1" / "operations.conversion.approved.v1" / "operations.conversion.settled.v1" / "operations.conversion.failed.v1" / "operations.conversion.cancelled.v1" / "operations.external_settlement_conversion.pending_compliance.v1" / "operations.internal_transfer.requested.v1" / "operations.internal_transfer.admissible.v1" / "operations.internal_transfer.pending_approval.v1" / "operations.internal_transfer.pending_compliance.v1" / "operations.internal_transfer.approved.v1" / "operations.internal_transfer.settled.v1" / "operations.internal_transfer.failed.v1" / "operations.internal_transfer.cancelled.v1" / "operations.on_ramp.requested.v1" / "operations.on_ramp.admissible.v1" / "operations.on_ramp.pending_approval.v1" / "operations.on_ramp.pending_compliance.v1" / "operations.on_ramp.approved.v1" / "operations.on_ramp.settled.v1" / "operations.on_ramp.failed.v1" / "operations.on_ramp.cancelled.v1" / "operations.off_ramp.requested.v1" / "operations.off_ramp.admissible.v1" / "operations.off_ramp.pending_approval.v1" / "operations.off_ramp.pending_compliance.v1" / "operations.off_ramp.approved.v1" / "operations.off_ramp.settled.v1" / "operations.off_ramp.failed.v1" / "operations.off_ramp.cancelled.v1" / "operations.deposit.requested.v1" / "operations.deposit.admissible.v1" / "operations.deposit.pending_approval.v1" / "operations.deposit.pending_admission.v1" / "operations.deposit.pending_compliance.v1" / "operations.deposit.approved.v1" / "operations.deposit.settled.v1" / "operations.deposit.failed.v1" / "operations.deposit.cancelled.v1" / "rails.deposit.detected.v1" / "rails.dispatch.acknowledged.v1" / "rails.dispatch.rejected.v1" / "rails.settlement.confirmed.v1" / "kyc.verification.reviewed.v1" / "loan.originated.v1" / "loan.origination_failed.v1" / "loan.margin_called.v1" / "loan.margin_call_cleared.v1" / "loan.liquidation_halted.v1" / "loan.liquidated.v1" / "loan.repaid.v1" / "loan.extended.v1" / "loan.closed.v1" / "loan.force_closed.v1" / "loan.reconciliation_discrepancy.v1" / "tenant.enterprise.*.v1" / "tenant.*.v1" / "tenant.platform_operator.*.v1" / "tenant.master_account.*.v1" / "tenant.client.*.v1" / "tenant.client_account.*.v1" / "ledger.transaction.*.v1" / "ledger.*.v1" / "operations.withdrawal.*.v1" / "operations.*.v1" / "operations.conversion.*.v1" / "operations.external_settlement_conversion.*.v1" / "operations.internal_transfer.*.v1" / "operations.on_ramp.*.v1" / "operations.off_ramp.*.v1" / "operations.deposit.*.v1" / "rails.deposit.*.v1" / "rails.*.v1" / "rails.dispatch.*.v1" / "rails.settlement.*.v1" / "kyc.verification.*.v1" / "kyc.*.v1" / "loan.loan.*.v1" / "loan.*.v1" / "identity.human_actor.created.v1" / "identity.human_actor.pending_created.v1" / "identity.human_actor.activated.v1" / "identity.human_actor.suspended.v1" / "identity.human_actor.reactivated.v1" / "identity.human_actor.deactivated.v1" / "identity.human_actor.updated.v1" / "identity.human_actor.federation_bound.v1" / "identity.human_actor.*.v1" / "identity.human_actor.access_resend_requested.v1" / "identity.human_actor.recovery_requested.v1"`. 

##### application/json body.managed_by

identity_provider_id of the IdP row that owns a core-managed subscription; null for tenant-created ones.

At least one alternative must match.

###### application/json body.managed_by: alternative 1

Type: `string`. 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)$`

###### application/json body.managed_by: alternative 2

Type: `null`. 

##### application/json body.scope_ref

Webhook subscriptions can be scoped only to an enterprise or client.

At least one alternative must match.

###### application/json body.scope_ref: alternative 1

Type: `string`. pattern: `^(enterprises)\/([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})$`

###### application/json body.scope_ref: alternative 2

Type: `string`. pattern: `^(clients)\/([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})$`

##### application/json body.updated_at

At least one alternative must match.

###### application/json body.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.updated_at: alternative 2

Type: `string`. format: date-time


### webhook-subscriptions-get 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.


### webhook-subscriptions-get Response 401 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.


### webhook-subscriptions-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-get-response-401-schema).


### webhook-subscriptions-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-get-response-401-schema).


### webhook-subscriptions-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-get-response-401-schema).


### webhook-subscriptions-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#webhook-subscriptions-get-response-400-schema).


### webhook-subscriptions-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#webhook-subscriptions-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "created_at": "2026-05-01T10:00:00Z",
    "etag": "2026-05-01T10:00:00Z",
    "event_types": [
      "operations.withdrawal.settled.v1"
    ],
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "kind": "public",
    "managed_by": null,
    "resource": "webhook_subscription",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "signing": "hmac",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z",
    "url": "https://example.com/webhooks"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### PATCH /webhook-subscriptions/{subscription_id}

**Update webhook subscription**

Updates the supplied fields and requires the current If-Match entity tag from a prior resource read. Platform-managed subscriptions cannot be changed here. Deleted subscriptions cannot be updated or reactivated; attempts return 409 with reason `webhook_subscription_not_active`. Keeping or widening an identity event stream additionally requires users.read covering the subscription scope; pausing or deleting without other changes only narrows the stream.

**Required capability:** `webhooks.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `subscription_id` `string` (path) *(required)*
- `If-Match` `string` (header) *(required)* — Weak entity tag from a prior GET. Mismatch causes the request to fail with 412 Precondition Failed.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `event_types` | "*" / "tenant.enterprise.admission_reviewed.v1" / "tenant.enterprise.admitted.v1" / "tenant.enterprise.activated.v1" / "tenant.enterprise.updated.v1" / "tenant.enterprise.suspended.v1" / "tenant.enterprise.reactivated.v1" / "tenant.enterprise.closed.v1" / "tenant.enterprise.terminated.v1" / "tenant.platform_operator.admitted.v1" / "tenant.platform_operator.restricted.v1" / "tenant.platform_operator.reactivated.v1" / "tenant.platform_operator.offboarded.v1" / "tenant.platform_operator.catalog_updated.v1" / "tenant.master_account.created.v1" / "tenant.master_account.suspended.v1" / "tenant.master_account.closed.v1" / "tenant.client.created.v1" / "tenant.client.updated.v1" / "tenant.client.suspended.v1" / "tenant.client.reactivated.v1" / "tenant.client.closed.v1" / "tenant.client_account.created.v1" / "tenant.client_account.suspended.v1" / "tenant.client_account.reactivated.v1" / "tenant.client_account.closed.v1" / "ledger.transaction.posted.v1" / "operations.withdrawal.requested.v1" / "operations.withdrawal.admissible.v1" / "operations.withdrawal.executing.v1" / "operations.withdrawal.pending_approval.v1" / "operations.withdrawal.pending_compliance.v1" / "operations.withdrawal.approved.v1" / "operations.withdrawal.settled.v1" / "operations.withdrawal.failed.v1" / "operations.withdrawal.cancelled.v1" / "operations.conversion.requested.v1" / "operations.conversion.admissible.v1" / "operations.conversion.pending_approval.v1" / "operations.conversion.pending_compliance.v1" / "operations.conversion.approved.v1" / "operations.conversion.settled.v1" / "operations.conversion.failed.v1" / "operations.conversion.cancelled.v1" / "operations.external_settlement_conversion.pending_compliance.v1" / "operations.internal_transfer.requested.v1" / "operations.internal_transfer.admissible.v1" / "operations.internal_transfer.pending_approval.v1" / "operations.internal_transfer.pending_compliance.v1" / "operations.internal_transfer.approved.v1" / "operations.internal_transfer.settled.v1" / "operations.internal_transfer.failed.v1" / "operations.internal_transfer.cancelled.v1" / "operations.on_ramp.requested.v1" / "operations.on_ramp.admissible.v1" / "operations.on_ramp.pending_approval.v1" / "operations.on_ramp.pending_compliance.v1" / "operations.on_ramp.approved.v1" / "operations.on_ramp.settled.v1" / "operations.on_ramp.failed.v1" / "operations.on_ramp.cancelled.v1" / "operations.off_ramp.requested.v1" / "operations.off_ramp.admissible.v1" / "operations.off_ramp.pending_approval.v1" / "operations.off_ramp.pending_compliance.v1" / "operations.off_ramp.approved.v1" / "operations.off_ramp.settled.v1" / "operations.off_ramp.failed.v1" / "operations.off_ramp.cancelled.v1" / "operations.deposit.requested.v1" / "operations.deposit.admissible.v1" / "operations.deposit.pending_approval.v1" / "operations.deposit.pending_admission.v1" / "operations.deposit.pending_compliance.v1" / "operations.deposit.approved.v1" / "operations.deposit.settled.v1" / "operations.deposit.failed.v1" / "operations.deposit.cancelled.v1" / "rails.deposit.detected.v1" / "rails.dispatch.acknowledged.v1" / "rails.dispatch.rejected.v1" / "rails.settlement.confirmed.v1" / "kyc.verification.reviewed.v1" / "loan.originated.v1" / "loan.origination_failed.v1" / "loan.margin_called.v1" / "loan.margin_call_cleared.v1" / "loan.liquidation_halted.v1" / "loan.liquidated.v1" / "loan.repaid.v1" / "loan.extended.v1" / "loan.closed.v1" / "loan.force_closed.v1" / "loan.reconciliation_discrepancy.v1" / "tenant.enterprise.*.v1" / "tenant.*.v1" / "tenant.platform_operator.*.v1" / "tenant.master_account.*.v1" / "tenant.client.*.v1" / "tenant.client_account.*.v1" / "ledger.transaction.*.v1" / "ledger.*.v1" / "operations.withdrawal.*.v1" / "operations.*.v1" / "operations.conversion.*.v1" / "operations.external_settlement_conversion.*.v1" / "operations.internal_transfer.*.v1" / "operations.on_ramp.*.v1" / "operations.off_ramp.*.v1" / "operations.deposit.*.v1" / "rails.deposit.*.v1" / "rails.*.v1" / "rails.dispatch.*.v1" / "rails.settlement.*.v1" / "kyc.verification.*.v1" / "kyc.*.v1" / "loan.loan.*.v1" / "loan.*.v1" / "identity.human_actor.created.v1" / "identity.human_actor.pending_created.v1" / "identity.human_actor.activated.v1" / "identity.human_actor.suspended.v1" / "identity.human_actor.reactivated.v1" / "identity.human_actor.deactivated.v1" / "identity.human_actor.updated.v1" / "identity.human_actor.federation_bound.v1" / "identity.human_actor.*.v1"[] | No | Non-empty event type filter. Use ["*"] to subscribe to all event types; otherwise provide exact catalog event types or catalog-derived group wildcards such as "operations.withdrawal.*.v1" and "operations.*.v1". minItems: 1 |
| `status` | "active" / "paused" / "deleted" | No |  |
| `url` | string | No | HTTPS callback URL on a public host. Plain http, private and internal addresses are refused with callback_url_not_allowed. format: uri |

Additional fields are not accepted.

#### Request body schema.event_types

Non-empty event type filter. Use ["*"] to subscribe to all event types; otherwise provide exact catalog event types or catalog-derived group wildcards such as "operations.withdrawal.*.v1" and "operations.*.v1".

Type: `"*" / "tenant.enterprise.admission_reviewed.v1" / "tenant.enterprise.admitted.v1" / "tenant.enterprise.activated.v1" / "tenant.enterprise.updated.v1" / "tenant.enterprise.suspended.v1" / "tenant.enterprise.reactivated.v1" / "tenant.enterprise.closed.v1" / "tenant.enterprise.terminated.v1" / "tenant.platform_operator.admitted.v1" / "tenant.platform_operator.restricted.v1" / "tenant.platform_operator.reactivated.v1" / "tenant.platform_operator.offboarded.v1" / "tenant.platform_operator.catalog_updated.v1" / "tenant.master_account.created.v1" / "tenant.master_account.suspended.v1" / "tenant.master_account.closed.v1" / "tenant.client.created.v1" / "tenant.client.updated.v1" / "tenant.client.suspended.v1" / "tenant.client.reactivated.v1" / "tenant.client.closed.v1" / "tenant.client_account.created.v1" / "tenant.client_account.suspended.v1" / "tenant.client_account.reactivated.v1" / "tenant.client_account.closed.v1" / "ledger.transaction.posted.v1" / "operations.withdrawal.requested.v1" / "operations.withdrawal.admissible.v1" / "operations.withdrawal.executing.v1" / "operations.withdrawal.pending_approval.v1" / "operations.withdrawal.pending_compliance.v1" / "operations.withdrawal.approved.v1" / "operations.withdrawal.settled.v1" / "operations.withdrawal.failed.v1" / "operations.withdrawal.cancelled.v1" / "operations.conversion.requested.v1" / "operations.conversion.admissible.v1" / "operations.conversion.pending_approval.v1" / "operations.conversion.pending_compliance.v1" / "operations.conversion.approved.v1" / "operations.conversion.settled.v1" / "operations.conversion.failed.v1" / "operations.conversion.cancelled.v1" / "operations.external_settlement_conversion.pending_compliance.v1" / "operations.internal_transfer.requested.v1" / "operations.internal_transfer.admissible.v1" / "operations.internal_transfer.pending_approval.v1" / "operations.internal_transfer.pending_compliance.v1" / "operations.internal_transfer.approved.v1" / "operations.internal_transfer.settled.v1" / "operations.internal_transfer.failed.v1" / "operations.internal_transfer.cancelled.v1" / "operations.on_ramp.requested.v1" / "operations.on_ramp.admissible.v1" / "operations.on_ramp.pending_approval.v1" / "operations.on_ramp.pending_compliance.v1" / "operations.on_ramp.approved.v1" / "operations.on_ramp.settled.v1" / "operations.on_ramp.failed.v1" / "operations.on_ramp.cancelled.v1" / "operations.off_ramp.requested.v1" / "operations.off_ramp.admissible.v1" / "operations.off_ramp.pending_approval.v1" / "operations.off_ramp.pending_compliance.v1" / "operations.off_ramp.approved.v1" / "operations.off_ramp.settled.v1" / "operations.off_ramp.failed.v1" / "operations.off_ramp.cancelled.v1" / "operations.deposit.requested.v1" / "operations.deposit.admissible.v1" / "operations.deposit.pending_approval.v1" / "operations.deposit.pending_admission.v1" / "operations.deposit.pending_compliance.v1" / "operations.deposit.approved.v1" / "operations.deposit.settled.v1" / "operations.deposit.failed.v1" / "operations.deposit.cancelled.v1" / "rails.deposit.detected.v1" / "rails.dispatch.acknowledged.v1" / "rails.dispatch.rejected.v1" / "rails.settlement.confirmed.v1" / "kyc.verification.reviewed.v1" / "loan.originated.v1" / "loan.origination_failed.v1" / "loan.margin_called.v1" / "loan.margin_call_cleared.v1" / "loan.liquidation_halted.v1" / "loan.liquidated.v1" / "loan.repaid.v1" / "loan.extended.v1" / "loan.closed.v1" / "loan.force_closed.v1" / "loan.reconciliation_discrepancy.v1" / "tenant.enterprise.*.v1" / "tenant.*.v1" / "tenant.platform_operator.*.v1" / "tenant.master_account.*.v1" / "tenant.client.*.v1" / "tenant.client_account.*.v1" / "ledger.transaction.*.v1" / "ledger.*.v1" / "operations.withdrawal.*.v1" / "operations.*.v1" / "operations.conversion.*.v1" / "operations.external_settlement_conversion.*.v1" / "operations.internal_transfer.*.v1" / "operations.on_ramp.*.v1" / "operations.off_ramp.*.v1" / "operations.deposit.*.v1" / "rails.deposit.*.v1" / "rails.*.v1" / "rails.dispatch.*.v1" / "rails.settlement.*.v1" / "kyc.verification.*.v1" / "kyc.*.v1" / "loan.loan.*.v1" / "loan.*.v1" / "identity.human_actor.created.v1" / "identity.human_actor.pending_created.v1" / "identity.human_actor.activated.v1" / "identity.human_actor.suspended.v1" / "identity.human_actor.reactivated.v1" / "identity.human_actor.deactivated.v1" / "identity.human_actor.updated.v1" / "identity.human_actor.federation_bound.v1" / "identity.human_actor.*.v1"[]`. minItems: 1

##### Request body schema.event_types item

Webhook event type filter value. Use exact catalog event types, "*" for every event, "<domain>.<resource>.*.v<major>" for a resource group, or "<domain>.*.v<major>" for a domain group.

Type: `"*" / "tenant.enterprise.admission_reviewed.v1" / "tenant.enterprise.admitted.v1" / "tenant.enterprise.activated.v1" / "tenant.enterprise.updated.v1" / "tenant.enterprise.suspended.v1" / "tenant.enterprise.reactivated.v1" / "tenant.enterprise.closed.v1" / "tenant.enterprise.terminated.v1" / "tenant.platform_operator.admitted.v1" / "tenant.platform_operator.restricted.v1" / "tenant.platform_operator.reactivated.v1" / "tenant.platform_operator.offboarded.v1" / "tenant.platform_operator.catalog_updated.v1" / "tenant.master_account.created.v1" / "tenant.master_account.suspended.v1" / "tenant.master_account.closed.v1" / "tenant.client.created.v1" / "tenant.client.updated.v1" / "tenant.client.suspended.v1" / "tenant.client.reactivated.v1" / "tenant.client.closed.v1" / "tenant.client_account.created.v1" / "tenant.client_account.suspended.v1" / "tenant.client_account.reactivated.v1" / "tenant.client_account.closed.v1" / "ledger.transaction.posted.v1" / "operations.withdrawal.requested.v1" / "operations.withdrawal.admissible.v1" / "operations.withdrawal.executing.v1" / "operations.withdrawal.pending_approval.v1" / "operations.withdrawal.pending_compliance.v1" / "operations.withdrawal.approved.v1" / "operations.withdrawal.settled.v1" / "operations.withdrawal.failed.v1" / "operations.withdrawal.cancelled.v1" / "operations.conversion.requested.v1" / "operations.conversion.admissible.v1" / "operations.conversion.pending_approval.v1" / "operations.conversion.pending_compliance.v1" / "operations.conversion.approved.v1" / "operations.conversion.settled.v1" / "operations.conversion.failed.v1" / "operations.conversion.cancelled.v1" / "operations.external_settlement_conversion.pending_compliance.v1" / "operations.internal_transfer.requested.v1" / "operations.internal_transfer.admissible.v1" / "operations.internal_transfer.pending_approval.v1" / "operations.internal_transfer.pending_compliance.v1" / "operations.internal_transfer.approved.v1" / "operations.internal_transfer.settled.v1" / "operations.internal_transfer.failed.v1" / "operations.internal_transfer.cancelled.v1" / "operations.on_ramp.requested.v1" / "operations.on_ramp.admissible.v1" / "operations.on_ramp.pending_approval.v1" / "operations.on_ramp.pending_compliance.v1" / "operations.on_ramp.approved.v1" / "operations.on_ramp.settled.v1" / "operations.on_ramp.failed.v1" / "operations.on_ramp.cancelled.v1" / "operations.off_ramp.requested.v1" / "operations.off_ramp.admissible.v1" / "operations.off_ramp.pending_approval.v1" / "operations.off_ramp.pending_compliance.v1" / "operations.off_ramp.approved.v1" / "operations.off_ramp.settled.v1" / "operations.off_ramp.failed.v1" / "operations.off_ramp.cancelled.v1" / "operations.deposit.requested.v1" / "operations.deposit.admissible.v1" / "operations.deposit.pending_approval.v1" / "operations.deposit.pending_admission.v1" / "operations.deposit.pending_compliance.v1" / "operations.deposit.approved.v1" / "operations.deposit.settled.v1" / "operations.deposit.failed.v1" / "operations.deposit.cancelled.v1" / "rails.deposit.detected.v1" / "rails.dispatch.acknowledged.v1" / "rails.dispatch.rejected.v1" / "rails.settlement.confirmed.v1" / "kyc.verification.reviewed.v1" / "loan.originated.v1" / "loan.origination_failed.v1" / "loan.margin_called.v1" / "loan.margin_call_cleared.v1" / "loan.liquidation_halted.v1" / "loan.liquidated.v1" / "loan.repaid.v1" / "loan.extended.v1" / "loan.closed.v1" / "loan.force_closed.v1" / "loan.reconciliation_discrepancy.v1" / "tenant.enterprise.*.v1" / "tenant.*.v1" / "tenant.platform_operator.*.v1" / "tenant.master_account.*.v1" / "tenant.client.*.v1" / "tenant.client_account.*.v1" / "ledger.transaction.*.v1" / "ledger.*.v1" / "operations.withdrawal.*.v1" / "operations.*.v1" / "operations.conversion.*.v1" / "operations.external_settlement_conversion.*.v1" / "operations.internal_transfer.*.v1" / "operations.on_ramp.*.v1" / "operations.off_ramp.*.v1" / "operations.deposit.*.v1" / "rails.deposit.*.v1" / "rails.*.v1" / "rails.dispatch.*.v1" / "rails.settlement.*.v1" / "kyc.verification.*.v1" / "kyc.*.v1" / "loan.loan.*.v1" / "loan.*.v1" / "identity.human_actor.created.v1" / "identity.human_actor.pending_created.v1" / "identity.human_actor.activated.v1" / "identity.human_actor.suspended.v1" / "identity.human_actor.reactivated.v1" / "identity.human_actor.deactivated.v1" / "identity.human_actor.updated.v1" / "identity.human_actor.federation_bound.v1" / "identity.human_actor.*.v1"`.

**Request example:**

```json
{
  "status": "paused",
  "url": "https://example.com/webhooks/updated"
}
```

### webhook-subscriptions-update Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `created_at` | string or string | Yes |  |
| `etag` | string | Yes | minLength: 1 |
| `event_types` | "*" / "tenant.enterprise.admission_reviewed.v1" / "tenant.enterprise.admitted.v1" / "tenant.enterprise.activated.v1" / "tenant.enterprise.updated.v1" / "tenant.enterprise.suspended.v1" / "tenant.enterprise.reactivated.v1" / "tenant.enterprise.closed.v1" / "tenant.enterprise.terminated.v1" / "tenant.platform_operator.admitted.v1" / "tenant.platform_operator.restricted.v1" / "tenant.platform_operator.reactivated.v1" / "tenant.platform_operator.offboarded.v1" / "tenant.platform_operator.catalog_updated.v1" / "tenant.master_account.created.v1" / "tenant.master_account.suspended.v1" / "tenant.master_account.closed.v1" / "tenant.client.created.v1" / "tenant.client.updated.v1" / "tenant.client.suspended.v1" / "tenant.client.reactivated.v1" / "tenant.client.closed.v1" / "tenant.client_account.created.v1" / "tenant.client_account.suspended.v1" / "tenant.client_account.reactivated.v1" / "tenant.client_account.closed.v1" / "ledger.transaction.posted.v1" / "operations.withdrawal.requested.v1" / "operations.withdrawal.admissible.v1" / "operations.withdrawal.executing.v1" / "operations.withdrawal.pending_approval.v1" / "operations.withdrawal.pending_compliance.v1" / "operations.withdrawal.approved.v1" / "operations.withdrawal.settled.v1" / "operations.withdrawal.failed.v1" / "operations.withdrawal.cancelled.v1" / "operations.conversion.requested.v1" / "operations.conversion.admissible.v1" / "operations.conversion.pending_approval.v1" / "operations.conversion.pending_compliance.v1" / "operations.conversion.approved.v1" / "operations.conversion.settled.v1" / "operations.conversion.failed.v1" / "operations.conversion.cancelled.v1" / "operations.external_settlement_conversion.pending_compliance.v1" / "operations.internal_transfer.requested.v1" / "operations.internal_transfer.admissible.v1" / "operations.internal_transfer.pending_approval.v1" / "operations.internal_transfer.pending_compliance.v1" / "operations.internal_transfer.approved.v1" / "operations.internal_transfer.settled.v1" / "operations.internal_transfer.failed.v1" / "operations.internal_transfer.cancelled.v1" / "operations.on_ramp.requested.v1" / "operations.on_ramp.admissible.v1" / "operations.on_ramp.pending_approval.v1" / "operations.on_ramp.pending_compliance.v1" / "operations.on_ramp.approved.v1" / "operations.on_ramp.settled.v1" / "operations.on_ramp.failed.v1" / "operations.on_ramp.cancelled.v1" / "operations.off_ramp.requested.v1" / "operations.off_ramp.admissible.v1" / "operations.off_ramp.pending_approval.v1" / "operations.off_ramp.pending_compliance.v1" / "operations.off_ramp.approved.v1" / "operations.off_ramp.settled.v1" / "operations.off_ramp.failed.v1" / "operations.off_ramp.cancelled.v1" / "operations.deposit.requested.v1" / "operations.deposit.admissible.v1" / "operations.deposit.pending_approval.v1" / "operations.deposit.pending_admission.v1" / "operations.deposit.pending_compliance.v1" / "operations.deposit.approved.v1" / "operations.deposit.settled.v1" / "operations.deposit.failed.v1" / "operations.deposit.cancelled.v1" / "rails.deposit.detected.v1" / "rails.dispatch.acknowledged.v1" / "rails.dispatch.rejected.v1" / "rails.settlement.confirmed.v1" / "kyc.verification.reviewed.v1" / "loan.originated.v1" / "loan.origination_failed.v1" / "loan.margin_called.v1" / "loan.margin_call_cleared.v1" / "loan.liquidation_halted.v1" / "loan.liquidated.v1" / "loan.repaid.v1" / "loan.extended.v1" / "loan.closed.v1" / "loan.force_closed.v1" / "loan.reconciliation_discrepancy.v1" / "tenant.enterprise.*.v1" / "tenant.*.v1" / "tenant.platform_operator.*.v1" / "tenant.master_account.*.v1" / "tenant.client.*.v1" / "tenant.client_account.*.v1" / "ledger.transaction.*.v1" / "ledger.*.v1" / "operations.withdrawal.*.v1" / "operations.*.v1" / "operations.conversion.*.v1" / "operations.external_settlement_conversion.*.v1" / "operations.internal_transfer.*.v1" / "operations.on_ramp.*.v1" / "operations.off_ramp.*.v1" / "operations.deposit.*.v1" / "rails.deposit.*.v1" / "rails.*.v1" / "rails.dispatch.*.v1" / "rails.settlement.*.v1" / "kyc.verification.*.v1" / "kyc.*.v1" / "loan.loan.*.v1" / "loan.*.v1" / "identity.human_actor.created.v1" / "identity.human_actor.pending_created.v1" / "identity.human_actor.activated.v1" / "identity.human_actor.suspended.v1" / "identity.human_actor.reactivated.v1" / "identity.human_actor.deactivated.v1" / "identity.human_actor.updated.v1" / "identity.human_actor.federation_bound.v1" / "identity.human_actor.*.v1" / "identity.human_actor.access_resend_requested.v1" / "identity.human_actor.recovery_requested.v1"[] | Yes | minItems: 1 |
| `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)$` |
| `kind` | "public" / "identity" / "command" | Yes | Which catalog classes the subscription admits: public → public events; identity → public and identity events; command → command events only. |
| `managed_by` | string or null | Yes | identity_provider_id of the IdP row that owns a core-managed subscription; null for tenant-created ones. |
| `resource` | "webhook_subscription" | Yes |  |
| `scope_ref` | string or string | Yes | Webhook subscriptions can be scoped only to an enterprise or client. |
| `signing` | "hmac" / "asymmetric" | Yes | hmac: v1 HMAC header plus the v2 Ed25519 header; asymmetric: v2 only, verified against the published JWKS. |
| `status` | "active" / "paused" / "deleted" | Yes |  |
| `updated_at` | string or string | Yes |  |
| `url` | string | Yes | format: uri |

Additional fields are not accepted.

##### application/json body.created_at

At least one alternative must match.

###### application/json body.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.created_at: alternative 2

Type: `string`. format: date-time

##### application/json body.event_types

Type: `"*" / "tenant.enterprise.admission_reviewed.v1" / "tenant.enterprise.admitted.v1" / "tenant.enterprise.activated.v1" / "tenant.enterprise.updated.v1" / "tenant.enterprise.suspended.v1" / "tenant.enterprise.reactivated.v1" / "tenant.enterprise.closed.v1" / "tenant.enterprise.terminated.v1" / "tenant.platform_operator.admitted.v1" / "tenant.platform_operator.restricted.v1" / "tenant.platform_operator.reactivated.v1" / "tenant.platform_operator.offboarded.v1" / "tenant.platform_operator.catalog_updated.v1" / "tenant.master_account.created.v1" / "tenant.master_account.suspended.v1" / "tenant.master_account.closed.v1" / "tenant.client.created.v1" / "tenant.client.updated.v1" / "tenant.client.suspended.v1" / "tenant.client.reactivated.v1" / "tenant.client.closed.v1" / "tenant.client_account.created.v1" / "tenant.client_account.suspended.v1" / "tenant.client_account.reactivated.v1" / "tenant.client_account.closed.v1" / "ledger.transaction.posted.v1" / "operations.withdrawal.requested.v1" / "operations.withdrawal.admissible.v1" / "operations.withdrawal.executing.v1" / "operations.withdrawal.pending_approval.v1" / "operations.withdrawal.pending_compliance.v1" / "operations.withdrawal.approved.v1" / "operations.withdrawal.settled.v1" / "operations.withdrawal.failed.v1" / "operations.withdrawal.cancelled.v1" / "operations.conversion.requested.v1" / "operations.conversion.admissible.v1" / "operations.conversion.pending_approval.v1" / "operations.conversion.pending_compliance.v1" / "operations.conversion.approved.v1" / "operations.conversion.settled.v1" / "operations.conversion.failed.v1" / "operations.conversion.cancelled.v1" / "operations.external_settlement_conversion.pending_compliance.v1" / "operations.internal_transfer.requested.v1" / "operations.internal_transfer.admissible.v1" / "operations.internal_transfer.pending_approval.v1" / "operations.internal_transfer.pending_compliance.v1" / "operations.internal_transfer.approved.v1" / "operations.internal_transfer.settled.v1" / "operations.internal_transfer.failed.v1" / "operations.internal_transfer.cancelled.v1" / "operations.on_ramp.requested.v1" / "operations.on_ramp.admissible.v1" / "operations.on_ramp.pending_approval.v1" / "operations.on_ramp.pending_compliance.v1" / "operations.on_ramp.approved.v1" / "operations.on_ramp.settled.v1" / "operations.on_ramp.failed.v1" / "operations.on_ramp.cancelled.v1" / "operations.off_ramp.requested.v1" / "operations.off_ramp.admissible.v1" / "operations.off_ramp.pending_approval.v1" / "operations.off_ramp.pending_compliance.v1" / "operations.off_ramp.approved.v1" / "operations.off_ramp.settled.v1" / "operations.off_ramp.failed.v1" / "operations.off_ramp.cancelled.v1" / "operations.deposit.requested.v1" / "operations.deposit.admissible.v1" / "operations.deposit.pending_approval.v1" / "operations.deposit.pending_admission.v1" / "operations.deposit.pending_compliance.v1" / "operations.deposit.approved.v1" / "operations.deposit.settled.v1" / "operations.deposit.failed.v1" / "operations.deposit.cancelled.v1" / "rails.deposit.detected.v1" / "rails.dispatch.acknowledged.v1" / "rails.dispatch.rejected.v1" / "rails.settlement.confirmed.v1" / "kyc.verification.reviewed.v1" / "loan.originated.v1" / "loan.origination_failed.v1" / "loan.margin_called.v1" / "loan.margin_call_cleared.v1" / "loan.liquidation_halted.v1" / "loan.liquidated.v1" / "loan.repaid.v1" / "loan.extended.v1" / "loan.closed.v1" / "loan.force_closed.v1" / "loan.reconciliation_discrepancy.v1" / "tenant.enterprise.*.v1" / "tenant.*.v1" / "tenant.platform_operator.*.v1" / "tenant.master_account.*.v1" / "tenant.client.*.v1" / "tenant.client_account.*.v1" / "ledger.transaction.*.v1" / "ledger.*.v1" / "operations.withdrawal.*.v1" / "operations.*.v1" / "operations.conversion.*.v1" / "operations.external_settlement_conversion.*.v1" / "operations.internal_transfer.*.v1" / "operations.on_ramp.*.v1" / "operations.off_ramp.*.v1" / "operations.deposit.*.v1" / "rails.deposit.*.v1" / "rails.*.v1" / "rails.dispatch.*.v1" / "rails.settlement.*.v1" / "kyc.verification.*.v1" / "kyc.*.v1" / "loan.loan.*.v1" / "loan.*.v1" / "identity.human_actor.created.v1" / "identity.human_actor.pending_created.v1" / "identity.human_actor.activated.v1" / "identity.human_actor.suspended.v1" / "identity.human_actor.reactivated.v1" / "identity.human_actor.deactivated.v1" / "identity.human_actor.updated.v1" / "identity.human_actor.federation_bound.v1" / "identity.human_actor.*.v1" / "identity.human_actor.access_resend_requested.v1" / "identity.human_actor.recovery_requested.v1"[]`. minItems: 1

###### application/json body.event_types item

Type: `"*" / "tenant.enterprise.admission_reviewed.v1" / "tenant.enterprise.admitted.v1" / "tenant.enterprise.activated.v1" / "tenant.enterprise.updated.v1" / "tenant.enterprise.suspended.v1" / "tenant.enterprise.reactivated.v1" / "tenant.enterprise.closed.v1" / "tenant.enterprise.terminated.v1" / "tenant.platform_operator.admitted.v1" / "tenant.platform_operator.restricted.v1" / "tenant.platform_operator.reactivated.v1" / "tenant.platform_operator.offboarded.v1" / "tenant.platform_operator.catalog_updated.v1" / "tenant.master_account.created.v1" / "tenant.master_account.suspended.v1" / "tenant.master_account.closed.v1" / "tenant.client.created.v1" / "tenant.client.updated.v1" / "tenant.client.suspended.v1" / "tenant.client.reactivated.v1" / "tenant.client.closed.v1" / "tenant.client_account.created.v1" / "tenant.client_account.suspended.v1" / "tenant.client_account.reactivated.v1" / "tenant.client_account.closed.v1" / "ledger.transaction.posted.v1" / "operations.withdrawal.requested.v1" / "operations.withdrawal.admissible.v1" / "operations.withdrawal.executing.v1" / "operations.withdrawal.pending_approval.v1" / "operations.withdrawal.pending_compliance.v1" / "operations.withdrawal.approved.v1" / "operations.withdrawal.settled.v1" / "operations.withdrawal.failed.v1" / "operations.withdrawal.cancelled.v1" / "operations.conversion.requested.v1" / "operations.conversion.admissible.v1" / "operations.conversion.pending_approval.v1" / "operations.conversion.pending_compliance.v1" / "operations.conversion.approved.v1" / "operations.conversion.settled.v1" / "operations.conversion.failed.v1" / "operations.conversion.cancelled.v1" / "operations.external_settlement_conversion.pending_compliance.v1" / "operations.internal_transfer.requested.v1" / "operations.internal_transfer.admissible.v1" / "operations.internal_transfer.pending_approval.v1" / "operations.internal_transfer.pending_compliance.v1" / "operations.internal_transfer.approved.v1" / "operations.internal_transfer.settled.v1" / "operations.internal_transfer.failed.v1" / "operations.internal_transfer.cancelled.v1" / "operations.on_ramp.requested.v1" / "operations.on_ramp.admissible.v1" / "operations.on_ramp.pending_approval.v1" / "operations.on_ramp.pending_compliance.v1" / "operations.on_ramp.approved.v1" / "operations.on_ramp.settled.v1" / "operations.on_ramp.failed.v1" / "operations.on_ramp.cancelled.v1" / "operations.off_ramp.requested.v1" / "operations.off_ramp.admissible.v1" / "operations.off_ramp.pending_approval.v1" / "operations.off_ramp.pending_compliance.v1" / "operations.off_ramp.approved.v1" / "operations.off_ramp.settled.v1" / "operations.off_ramp.failed.v1" / "operations.off_ramp.cancelled.v1" / "operations.deposit.requested.v1" / "operations.deposit.admissible.v1" / "operations.deposit.pending_approval.v1" / "operations.deposit.pending_admission.v1" / "operations.deposit.pending_compliance.v1" / "operations.deposit.approved.v1" / "operations.deposit.settled.v1" / "operations.deposit.failed.v1" / "operations.deposit.cancelled.v1" / "rails.deposit.detected.v1" / "rails.dispatch.acknowledged.v1" / "rails.dispatch.rejected.v1" / "rails.settlement.confirmed.v1" / "kyc.verification.reviewed.v1" / "loan.originated.v1" / "loan.origination_failed.v1" / "loan.margin_called.v1" / "loan.margin_call_cleared.v1" / "loan.liquidation_halted.v1" / "loan.liquidated.v1" / "loan.repaid.v1" / "loan.extended.v1" / "loan.closed.v1" / "loan.force_closed.v1" / "loan.reconciliation_discrepancy.v1" / "tenant.enterprise.*.v1" / "tenant.*.v1" / "tenant.platform_operator.*.v1" / "tenant.master_account.*.v1" / "tenant.client.*.v1" / "tenant.client_account.*.v1" / "ledger.transaction.*.v1" / "ledger.*.v1" / "operations.withdrawal.*.v1" / "operations.*.v1" / "operations.conversion.*.v1" / "operations.external_settlement_conversion.*.v1" / "operations.internal_transfer.*.v1" / "operations.on_ramp.*.v1" / "operations.off_ramp.*.v1" / "operations.deposit.*.v1" / "rails.deposit.*.v1" / "rails.*.v1" / "rails.dispatch.*.v1" / "rails.settlement.*.v1" / "kyc.verification.*.v1" / "kyc.*.v1" / "loan.loan.*.v1" / "loan.*.v1" / "identity.human_actor.created.v1" / "identity.human_actor.pending_created.v1" / "identity.human_actor.activated.v1" / "identity.human_actor.suspended.v1" / "identity.human_actor.reactivated.v1" / "identity.human_actor.deactivated.v1" / "identity.human_actor.updated.v1" / "identity.human_actor.federation_bound.v1" / "identity.human_actor.*.v1" / "identity.human_actor.access_resend_requested.v1" / "identity.human_actor.recovery_requested.v1"`. 

##### application/json body.managed_by

identity_provider_id of the IdP row that owns a core-managed subscription; null for tenant-created ones.

At least one alternative must match.

###### application/json body.managed_by: alternative 1

Type: `string`. 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)$`

###### application/json body.managed_by: alternative 2

Type: `null`. 

##### application/json body.scope_ref

Webhook subscriptions can be scoped only to an enterprise or client.

At least one alternative must match.

###### application/json body.scope_ref: alternative 1

Type: `string`. pattern: `^(enterprises)\/([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})$`

###### application/json body.scope_ref: alternative 2

Type: `string`. pattern: `^(clients)\/([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})$`

##### application/json body.updated_at

At least one alternative must match.

###### application/json body.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.updated_at: alternative 2

Type: `string`. format: date-time


### webhook-subscriptions-update 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.


### webhook-subscriptions-update Response 401 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.


### webhook-subscriptions-update Response 403 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-update-response-401-schema).


### webhook-subscriptions-update Response 404 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-update-response-401-schema).


### webhook-subscriptions-update Response 409 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-update-response-401-schema).


### webhook-subscriptions-update Response 412 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-update-response-401-schema).


### webhook-subscriptions-update Response 500 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-update-response-401-schema).


### webhook-subscriptions-update Response 502 schema

Content type: `application/json`.

See [response 400 schema](#webhook-subscriptions-update-response-400-schema).


### webhook-subscriptions-update Response 503 schema

Content type: `application/json`.

See [response 400 schema](#webhook-subscriptions-update-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "created_at": "2026-05-01T10:00:00Z",
    "etag": "2026-05-01T10:00:00Z",
    "event_types": [
      "operations.withdrawal.settled.v1"
    ],
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "kind": "public",
    "managed_by": null,
    "resource": "webhook_subscription",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "signing": "hmac",
    "status": "paused",
    "updated_at": "2026-05-01T10:00:00Z",
    "url": "https://example.com/webhooks/updated"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `412` — If-Match check failed; the resource has changed since the cached etag.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /webhook-subscriptions/{subscription_id}/delete

**Delete webhook subscription**

Marks the subscription `deleted` and returns its resource snapshot. Deletion is terminal: later edits or lifecycle changes return 409 with reason `webhook_subscription_not_active` when the supplied If-Match is current. Requires the current If-Match entity tag. Platform-managed subscriptions cannot be changed through this route.

**Required capability:** `webhooks.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `subscription_id` `string` (path) *(required)*
- `If-Match` `string` (header) *(required)* — Weak entity tag from a prior GET. Mismatch causes the request to fail with 412 Precondition Failed.
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

### webhook-subscriptions-delete Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `created_at` | string or string | Yes |  |
| `etag` | string | Yes | minLength: 1 |
| `event_types` | "*" / "tenant.enterprise.admission_reviewed.v1" / "tenant.enterprise.admitted.v1" / "tenant.enterprise.activated.v1" / "tenant.enterprise.updated.v1" / "tenant.enterprise.suspended.v1" / "tenant.enterprise.reactivated.v1" / "tenant.enterprise.closed.v1" / "tenant.enterprise.terminated.v1" / "tenant.platform_operator.admitted.v1" / "tenant.platform_operator.restricted.v1" / "tenant.platform_operator.reactivated.v1" / "tenant.platform_operator.offboarded.v1" / "tenant.platform_operator.catalog_updated.v1" / "tenant.master_account.created.v1" / "tenant.master_account.suspended.v1" / "tenant.master_account.closed.v1" / "tenant.client.created.v1" / "tenant.client.updated.v1" / "tenant.client.suspended.v1" / "tenant.client.reactivated.v1" / "tenant.client.closed.v1" / "tenant.client_account.created.v1" / "tenant.client_account.suspended.v1" / "tenant.client_account.reactivated.v1" / "tenant.client_account.closed.v1" / "ledger.transaction.posted.v1" / "operations.withdrawal.requested.v1" / "operations.withdrawal.admissible.v1" / "operations.withdrawal.executing.v1" / "operations.withdrawal.pending_approval.v1" / "operations.withdrawal.pending_compliance.v1" / "operations.withdrawal.approved.v1" / "operations.withdrawal.settled.v1" / "operations.withdrawal.failed.v1" / "operations.withdrawal.cancelled.v1" / "operations.conversion.requested.v1" / "operations.conversion.admissible.v1" / "operations.conversion.pending_approval.v1" / "operations.conversion.pending_compliance.v1" / "operations.conversion.approved.v1" / "operations.conversion.settled.v1" / "operations.conversion.failed.v1" / "operations.conversion.cancelled.v1" / "operations.external_settlement_conversion.pending_compliance.v1" / "operations.internal_transfer.requested.v1" / "operations.internal_transfer.admissible.v1" / "operations.internal_transfer.pending_approval.v1" / "operations.internal_transfer.pending_compliance.v1" / "operations.internal_transfer.approved.v1" / "operations.internal_transfer.settled.v1" / "operations.internal_transfer.failed.v1" / "operations.internal_transfer.cancelled.v1" / "operations.on_ramp.requested.v1" / "operations.on_ramp.admissible.v1" / "operations.on_ramp.pending_approval.v1" / "operations.on_ramp.pending_compliance.v1" / "operations.on_ramp.approved.v1" / "operations.on_ramp.settled.v1" / "operations.on_ramp.failed.v1" / "operations.on_ramp.cancelled.v1" / "operations.off_ramp.requested.v1" / "operations.off_ramp.admissible.v1" / "operations.off_ramp.pending_approval.v1" / "operations.off_ramp.pending_compliance.v1" / "operations.off_ramp.approved.v1" / "operations.off_ramp.settled.v1" / "operations.off_ramp.failed.v1" / "operations.off_ramp.cancelled.v1" / "operations.deposit.requested.v1" / "operations.deposit.admissible.v1" / "operations.deposit.pending_approval.v1" / "operations.deposit.pending_admission.v1" / "operations.deposit.pending_compliance.v1" / "operations.deposit.approved.v1" / "operations.deposit.settled.v1" / "operations.deposit.failed.v1" / "operations.deposit.cancelled.v1" / "rails.deposit.detected.v1" / "rails.dispatch.acknowledged.v1" / "rails.dispatch.rejected.v1" / "rails.settlement.confirmed.v1" / "kyc.verification.reviewed.v1" / "loan.originated.v1" / "loan.origination_failed.v1" / "loan.margin_called.v1" / "loan.margin_call_cleared.v1" / "loan.liquidation_halted.v1" / "loan.liquidated.v1" / "loan.repaid.v1" / "loan.extended.v1" / "loan.closed.v1" / "loan.force_closed.v1" / "loan.reconciliation_discrepancy.v1" / "tenant.enterprise.*.v1" / "tenant.*.v1" / "tenant.platform_operator.*.v1" / "tenant.master_account.*.v1" / "tenant.client.*.v1" / "tenant.client_account.*.v1" / "ledger.transaction.*.v1" / "ledger.*.v1" / "operations.withdrawal.*.v1" / "operations.*.v1" / "operations.conversion.*.v1" / "operations.external_settlement_conversion.*.v1" / "operations.internal_transfer.*.v1" / "operations.on_ramp.*.v1" / "operations.off_ramp.*.v1" / "operations.deposit.*.v1" / "rails.deposit.*.v1" / "rails.*.v1" / "rails.dispatch.*.v1" / "rails.settlement.*.v1" / "kyc.verification.*.v1" / "kyc.*.v1" / "loan.loan.*.v1" / "loan.*.v1" / "identity.human_actor.created.v1" / "identity.human_actor.pending_created.v1" / "identity.human_actor.activated.v1" / "identity.human_actor.suspended.v1" / "identity.human_actor.reactivated.v1" / "identity.human_actor.deactivated.v1" / "identity.human_actor.updated.v1" / "identity.human_actor.federation_bound.v1" / "identity.human_actor.*.v1" / "identity.human_actor.access_resend_requested.v1" / "identity.human_actor.recovery_requested.v1"[] | Yes | minItems: 1 |
| `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)$` |
| `kind` | "public" / "identity" / "command" | Yes | Which catalog classes the subscription admits: public → public events; identity → public and identity events; command → command events only. |
| `managed_by` | string or null | Yes | identity_provider_id of the IdP row that owns a core-managed subscription; null for tenant-created ones. |
| `resource` | "webhook_subscription" | Yes |  |
| `scope_ref` | string or string | Yes | Webhook subscriptions can be scoped only to an enterprise or client. |
| `signing` | "hmac" / "asymmetric" | Yes | hmac: v1 HMAC header plus the v2 Ed25519 header; asymmetric: v2 only, verified against the published JWKS. |
| `status` | "active" / "paused" / "deleted" | Yes |  |
| `updated_at` | string or string | Yes |  |
| `url` | string | Yes | format: uri |

Additional fields are not accepted.

##### application/json body.created_at

At least one alternative must match.

###### application/json body.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.created_at: alternative 2

Type: `string`. format: date-time

##### application/json body.event_types

Type: `"*" / "tenant.enterprise.admission_reviewed.v1" / "tenant.enterprise.admitted.v1" / "tenant.enterprise.activated.v1" / "tenant.enterprise.updated.v1" / "tenant.enterprise.suspended.v1" / "tenant.enterprise.reactivated.v1" / "tenant.enterprise.closed.v1" / "tenant.enterprise.terminated.v1" / "tenant.platform_operator.admitted.v1" / "tenant.platform_operator.restricted.v1" / "tenant.platform_operator.reactivated.v1" / "tenant.platform_operator.offboarded.v1" / "tenant.platform_operator.catalog_updated.v1" / "tenant.master_account.created.v1" / "tenant.master_account.suspended.v1" / "tenant.master_account.closed.v1" / "tenant.client.created.v1" / "tenant.client.updated.v1" / "tenant.client.suspended.v1" / "tenant.client.reactivated.v1" / "tenant.client.closed.v1" / "tenant.client_account.created.v1" / "tenant.client_account.suspended.v1" / "tenant.client_account.reactivated.v1" / "tenant.client_account.closed.v1" / "ledger.transaction.posted.v1" / "operations.withdrawal.requested.v1" / "operations.withdrawal.admissible.v1" / "operations.withdrawal.executing.v1" / "operations.withdrawal.pending_approval.v1" / "operations.withdrawal.pending_compliance.v1" / "operations.withdrawal.approved.v1" / "operations.withdrawal.settled.v1" / "operations.withdrawal.failed.v1" / "operations.withdrawal.cancelled.v1" / "operations.conversion.requested.v1" / "operations.conversion.admissible.v1" / "operations.conversion.pending_approval.v1" / "operations.conversion.pending_compliance.v1" / "operations.conversion.approved.v1" / "operations.conversion.settled.v1" / "operations.conversion.failed.v1" / "operations.conversion.cancelled.v1" / "operations.external_settlement_conversion.pending_compliance.v1" / "operations.internal_transfer.requested.v1" / "operations.internal_transfer.admissible.v1" / "operations.internal_transfer.pending_approval.v1" / "operations.internal_transfer.pending_compliance.v1" / "operations.internal_transfer.approved.v1" / "operations.internal_transfer.settled.v1" / "operations.internal_transfer.failed.v1" / "operations.internal_transfer.cancelled.v1" / "operations.on_ramp.requested.v1" / "operations.on_ramp.admissible.v1" / "operations.on_ramp.pending_approval.v1" / "operations.on_ramp.pending_compliance.v1" / "operations.on_ramp.approved.v1" / "operations.on_ramp.settled.v1" / "operations.on_ramp.failed.v1" / "operations.on_ramp.cancelled.v1" / "operations.off_ramp.requested.v1" / "operations.off_ramp.admissible.v1" / "operations.off_ramp.pending_approval.v1" / "operations.off_ramp.pending_compliance.v1" / "operations.off_ramp.approved.v1" / "operations.off_ramp.settled.v1" / "operations.off_ramp.failed.v1" / "operations.off_ramp.cancelled.v1" / "operations.deposit.requested.v1" / "operations.deposit.admissible.v1" / "operations.deposit.pending_approval.v1" / "operations.deposit.pending_admission.v1" / "operations.deposit.pending_compliance.v1" / "operations.deposit.approved.v1" / "operations.deposit.settled.v1" / "operations.deposit.failed.v1" / "operations.deposit.cancelled.v1" / "rails.deposit.detected.v1" / "rails.dispatch.acknowledged.v1" / "rails.dispatch.rejected.v1" / "rails.settlement.confirmed.v1" / "kyc.verification.reviewed.v1" / "loan.originated.v1" / "loan.origination_failed.v1" / "loan.margin_called.v1" / "loan.margin_call_cleared.v1" / "loan.liquidation_halted.v1" / "loan.liquidated.v1" / "loan.repaid.v1" / "loan.extended.v1" / "loan.closed.v1" / "loan.force_closed.v1" / "loan.reconciliation_discrepancy.v1" / "tenant.enterprise.*.v1" / "tenant.*.v1" / "tenant.platform_operator.*.v1" / "tenant.master_account.*.v1" / "tenant.client.*.v1" / "tenant.client_account.*.v1" / "ledger.transaction.*.v1" / "ledger.*.v1" / "operations.withdrawal.*.v1" / "operations.*.v1" / "operations.conversion.*.v1" / "operations.external_settlement_conversion.*.v1" / "operations.internal_transfer.*.v1" / "operations.on_ramp.*.v1" / "operations.off_ramp.*.v1" / "operations.deposit.*.v1" / "rails.deposit.*.v1" / "rails.*.v1" / "rails.dispatch.*.v1" / "rails.settlement.*.v1" / "kyc.verification.*.v1" / "kyc.*.v1" / "loan.loan.*.v1" / "loan.*.v1" / "identity.human_actor.created.v1" / "identity.human_actor.pending_created.v1" / "identity.human_actor.activated.v1" / "identity.human_actor.suspended.v1" / "identity.human_actor.reactivated.v1" / "identity.human_actor.deactivated.v1" / "identity.human_actor.updated.v1" / "identity.human_actor.federation_bound.v1" / "identity.human_actor.*.v1" / "identity.human_actor.access_resend_requested.v1" / "identity.human_actor.recovery_requested.v1"[]`. minItems: 1

###### application/json body.event_types item

Type: `"*" / "tenant.enterprise.admission_reviewed.v1" / "tenant.enterprise.admitted.v1" / "tenant.enterprise.activated.v1" / "tenant.enterprise.updated.v1" / "tenant.enterprise.suspended.v1" / "tenant.enterprise.reactivated.v1" / "tenant.enterprise.closed.v1" / "tenant.enterprise.terminated.v1" / "tenant.platform_operator.admitted.v1" / "tenant.platform_operator.restricted.v1" / "tenant.platform_operator.reactivated.v1" / "tenant.platform_operator.offboarded.v1" / "tenant.platform_operator.catalog_updated.v1" / "tenant.master_account.created.v1" / "tenant.master_account.suspended.v1" / "tenant.master_account.closed.v1" / "tenant.client.created.v1" / "tenant.client.updated.v1" / "tenant.client.suspended.v1" / "tenant.client.reactivated.v1" / "tenant.client.closed.v1" / "tenant.client_account.created.v1" / "tenant.client_account.suspended.v1" / "tenant.client_account.reactivated.v1" / "tenant.client_account.closed.v1" / "ledger.transaction.posted.v1" / "operations.withdrawal.requested.v1" / "operations.withdrawal.admissible.v1" / "operations.withdrawal.executing.v1" / "operations.withdrawal.pending_approval.v1" / "operations.withdrawal.pending_compliance.v1" / "operations.withdrawal.approved.v1" / "operations.withdrawal.settled.v1" / "operations.withdrawal.failed.v1" / "operations.withdrawal.cancelled.v1" / "operations.conversion.requested.v1" / "operations.conversion.admissible.v1" / "operations.conversion.pending_approval.v1" / "operations.conversion.pending_compliance.v1" / "operations.conversion.approved.v1" / "operations.conversion.settled.v1" / "operations.conversion.failed.v1" / "operations.conversion.cancelled.v1" / "operations.external_settlement_conversion.pending_compliance.v1" / "operations.internal_transfer.requested.v1" / "operations.internal_transfer.admissible.v1" / "operations.internal_transfer.pending_approval.v1" / "operations.internal_transfer.pending_compliance.v1" / "operations.internal_transfer.approved.v1" / "operations.internal_transfer.settled.v1" / "operations.internal_transfer.failed.v1" / "operations.internal_transfer.cancelled.v1" / "operations.on_ramp.requested.v1" / "operations.on_ramp.admissible.v1" / "operations.on_ramp.pending_approval.v1" / "operations.on_ramp.pending_compliance.v1" / "operations.on_ramp.approved.v1" / "operations.on_ramp.settled.v1" / "operations.on_ramp.failed.v1" / "operations.on_ramp.cancelled.v1" / "operations.off_ramp.requested.v1" / "operations.off_ramp.admissible.v1" / "operations.off_ramp.pending_approval.v1" / "operations.off_ramp.pending_compliance.v1" / "operations.off_ramp.approved.v1" / "operations.off_ramp.settled.v1" / "operations.off_ramp.failed.v1" / "operations.off_ramp.cancelled.v1" / "operations.deposit.requested.v1" / "operations.deposit.admissible.v1" / "operations.deposit.pending_approval.v1" / "operations.deposit.pending_admission.v1" / "operations.deposit.pending_compliance.v1" / "operations.deposit.approved.v1" / "operations.deposit.settled.v1" / "operations.deposit.failed.v1" / "operations.deposit.cancelled.v1" / "rails.deposit.detected.v1" / "rails.dispatch.acknowledged.v1" / "rails.dispatch.rejected.v1" / "rails.settlement.confirmed.v1" / "kyc.verification.reviewed.v1" / "loan.originated.v1" / "loan.origination_failed.v1" / "loan.margin_called.v1" / "loan.margin_call_cleared.v1" / "loan.liquidation_halted.v1" / "loan.liquidated.v1" / "loan.repaid.v1" / "loan.extended.v1" / "loan.closed.v1" / "loan.force_closed.v1" / "loan.reconciliation_discrepancy.v1" / "tenant.enterprise.*.v1" / "tenant.*.v1" / "tenant.platform_operator.*.v1" / "tenant.master_account.*.v1" / "tenant.client.*.v1" / "tenant.client_account.*.v1" / "ledger.transaction.*.v1" / "ledger.*.v1" / "operations.withdrawal.*.v1" / "operations.*.v1" / "operations.conversion.*.v1" / "operations.external_settlement_conversion.*.v1" / "operations.internal_transfer.*.v1" / "operations.on_ramp.*.v1" / "operations.off_ramp.*.v1" / "operations.deposit.*.v1" / "rails.deposit.*.v1" / "rails.*.v1" / "rails.dispatch.*.v1" / "rails.settlement.*.v1" / "kyc.verification.*.v1" / "kyc.*.v1" / "loan.loan.*.v1" / "loan.*.v1" / "identity.human_actor.created.v1" / "identity.human_actor.pending_created.v1" / "identity.human_actor.activated.v1" / "identity.human_actor.suspended.v1" / "identity.human_actor.reactivated.v1" / "identity.human_actor.deactivated.v1" / "identity.human_actor.updated.v1" / "identity.human_actor.federation_bound.v1" / "identity.human_actor.*.v1" / "identity.human_actor.access_resend_requested.v1" / "identity.human_actor.recovery_requested.v1"`. 

##### application/json body.managed_by

identity_provider_id of the IdP row that owns a core-managed subscription; null for tenant-created ones.

At least one alternative must match.

###### application/json body.managed_by: alternative 1

Type: `string`. 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)$`

###### application/json body.managed_by: alternative 2

Type: `null`. 

##### application/json body.scope_ref

Webhook subscriptions can be scoped only to an enterprise or client.

At least one alternative must match.

###### application/json body.scope_ref: alternative 1

Type: `string`. pattern: `^(enterprises)\/([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})$`

###### application/json body.scope_ref: alternative 2

Type: `string`. pattern: `^(clients)\/([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})$`

##### application/json body.updated_at

At least one alternative must match.

###### application/json body.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.updated_at: alternative 2

Type: `string`. format: date-time


### webhook-subscriptions-delete 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.


### webhook-subscriptions-delete Response 401 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.


### webhook-subscriptions-delete Response 403 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-delete-response-401-schema).


### webhook-subscriptions-delete Response 404 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-delete-response-401-schema).


### webhook-subscriptions-delete Response 409 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-delete-response-401-schema).


### webhook-subscriptions-delete Response 412 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-delete-response-401-schema).


### webhook-subscriptions-delete Response 500 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-delete-response-401-schema).


### webhook-subscriptions-delete Response 502 schema

Content type: `application/json`.

See [response 400 schema](#webhook-subscriptions-delete-response-400-schema).


### webhook-subscriptions-delete Response 503 schema

Content type: `application/json`.

See [response 400 schema](#webhook-subscriptions-delete-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "created_at": "2026-05-01T10:00:00Z",
    "etag": "2026-05-01T10:00:00Z",
    "event_types": [
      "operations.withdrawal.settled.v1"
    ],
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "kind": "public",
    "managed_by": null,
    "resource": "webhook_subscription",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "signing": "hmac",
    "status": "deleted",
    "updated_at": "2026-05-01T10:00:00Z",
    "url": "https://example.com/webhooks"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `412` — If-Match check failed; the resource has changed since the cached etag.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /webhook-subscriptions/{subscription_id}/deliveries

**List webhook deliveries**

**Required capability:** `webhooks.read`

**Authentication:** Bearer token required.

**Parameters:**

- `subscription_id` `string` (path) *(required)*
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.
- `status` `string` (query)
- `event_id` `string` (query)

### webhook-subscriptions-deliveries Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `attempt_count` | integer | Yes | minimum: 0; maximum: 9007199254740991 |
| `attempts` | object[] | Yes |  |
| `created_at` | string or string | Yes |  |
| `event_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)$` |
| `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)$` |
| `last_attempt_at` | string or string or null | Yes |  |
| `next_retry_at` | string or string or null | Yes |  |
| `resource` | "webhook_delivery" | Yes |  |
| `status` | "pending" / "delivered" / "failed" / "retrying" / "dlq" | Yes |  |
| `subscription_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.

###### application/json body.items item.attempts

Type: `object[]`. 

###### application/json body.items item.attempts item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `attempt_number` | integer | Yes | maximum: 9007199254740991; exclusiveMinimum: 0 |
| `attempted_at` | string or string | Yes |  |
| `delivery_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)$` |
| `duration_ms` | integer | Yes | minimum: 0; maximum: 9007199254740991 |
| `http_status_code` | integer or null | Yes |  |
| `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)$` |
| `resource` | "delivery_attempt" | Yes |  |
| `response_body` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.attempts item.attempted_at

At least one alternative must match.

###### application/json body.items item.attempts item.attempted_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.attempts item.attempted_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.attempts item.http_status_code

At least one alternative must match.

###### application/json body.items item.attempts item.http_status_code: alternative 1

Type: `integer`. minimum: 100; maximum: 599

###### application/json body.items item.attempts item.http_status_code: alternative 2

Type: `null`. 

###### application/json body.items item.attempts item.response_body

At least one alternative must match.

###### application/json body.items item.attempts item.response_body: alternative 1

Type: `string`. 

###### application/json body.items item.attempts item.response_body: alternative 2

Type: `null`. 

###### application/json body.items item.created_at

At least one alternative must match.

###### application/json body.items item.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.created_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.last_attempt_at

At least one alternative must match.

###### application/json body.items item.last_attempt_at: alternative 1

At least one alternative must match.

###### application/json body.items item.last_attempt_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.last_attempt_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.last_attempt_at: alternative 2

Type: `null`. 

###### application/json body.items item.next_retry_at

At least one alternative must match.

###### application/json body.items item.next_retry_at: alternative 1

At least one alternative must match.

###### application/json body.items item.next_retry_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.next_retry_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.next_retry_at: alternative 2

Type: `null`. 

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. 

###### application/json body.next_page_token: alternative 2

Type: `null`.


### webhook-subscriptions-deliveries 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.


### webhook-subscriptions-deliveries Response 401 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.


### webhook-subscriptions-deliveries Response 403 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-deliveries-response-401-schema).


### webhook-subscriptions-deliveries Response 404 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-deliveries-response-401-schema).


### webhook-subscriptions-deliveries Response 500 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-deliveries-response-401-schema).


### webhook-subscriptions-deliveries Response 502 schema

Content type: `application/json`.

See [response 400 schema](#webhook-subscriptions-deliveries-response-400-schema).


### webhook-subscriptions-deliveries Response 503 schema

Content type: `application/json`.

See [response 400 schema](#webhook-subscriptions-deliveries-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "attempt_count": 1,
        "attempts": [
          {
            "attempt_number": 1,
            "attempted_at": "2026-05-01T10:00:00Z",
            "delivery_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
            "duration_ms": 142,
            "http_status_code": 200,
            "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
            "resource": "delivery_attempt",
            "response_body": "ok"
          }
        ],
        "created_at": "2026-05-01T10:00:00Z",
        "event_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "last_attempt_at": "2026-05-01T10:00:00Z",
        "next_retry_at": null,
        "resource": "webhook_delivery",
        "status": "delivered",
        "subscription_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /webhook-subscriptions/{subscription_id}/deliveries/{delivery_id}

**Get webhook delivery**

**Required capability:** `webhooks.read`

**Authentication:** Bearer token required.

**Parameters:**

- `subscription_id` `string` (path) *(required)*
- `delivery_id` `string` (path) *(required)*

### webhook-subscriptions-deliveries-get Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `attempt_count` | integer | Yes | minimum: 0; maximum: 9007199254740991 |
| `attempts` | object[] | Yes |  |
| `created_at` | string or string | Yes |  |
| `event_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)$` |
| `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)$` |
| `last_attempt_at` | string or string or null | Yes |  |
| `next_retry_at` | string or string or null | Yes |  |
| `resource` | "webhook_delivery" | Yes |  |
| `status` | "pending" / "delivered" / "failed" / "retrying" / "dlq" | Yes |  |
| `subscription_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.

##### application/json body.attempts

Type: `object[]`. 

###### application/json body.attempts item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `attempt_number` | integer | Yes | maximum: 9007199254740991; exclusiveMinimum: 0 |
| `attempted_at` | string or string | Yes |  |
| `delivery_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)$` |
| `duration_ms` | integer | Yes | minimum: 0; maximum: 9007199254740991 |
| `http_status_code` | integer or null | Yes |  |
| `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)$` |
| `resource` | "delivery_attempt" | Yes |  |
| `response_body` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.attempts item.attempted_at

At least one alternative must match.

###### application/json body.attempts item.attempted_at: alternative 1

Type: `string`. 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))$`

###### application/json body.attempts item.attempted_at: alternative 2

Type: `string`. format: date-time

###### application/json body.attempts item.http_status_code

At least one alternative must match.

###### application/json body.attempts item.http_status_code: alternative 1

Type: `integer`. minimum: 100; maximum: 599

###### application/json body.attempts item.http_status_code: alternative 2

Type: `null`. 

###### application/json body.attempts item.response_body

At least one alternative must match.

###### application/json body.attempts item.response_body: alternative 1

Type: `string`. 

###### application/json body.attempts item.response_body: alternative 2

Type: `null`. 

##### application/json body.created_at

At least one alternative must match.

###### application/json body.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.created_at: alternative 2

Type: `string`. format: date-time

##### application/json body.last_attempt_at

At least one alternative must match.

###### application/json body.last_attempt_at: alternative 1

At least one alternative must match.

###### application/json body.last_attempt_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.last_attempt_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.last_attempt_at: alternative 2

Type: `null`. 

##### application/json body.next_retry_at

At least one alternative must match.

###### application/json body.next_retry_at: alternative 1

At least one alternative must match.

###### application/json body.next_retry_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.next_retry_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.next_retry_at: alternative 2

Type: `null`.


### webhook-subscriptions-deliveries-get 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.


### webhook-subscriptions-deliveries-get Response 401 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.


### webhook-subscriptions-deliveries-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-deliveries-get-response-401-schema).


### webhook-subscriptions-deliveries-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-deliveries-get-response-401-schema).


### webhook-subscriptions-deliveries-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-deliveries-get-response-401-schema).


### webhook-subscriptions-deliveries-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#webhook-subscriptions-deliveries-get-response-400-schema).


### webhook-subscriptions-deliveries-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#webhook-subscriptions-deliveries-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "attempt_count": 1,
    "attempts": [
      {
        "attempt_number": 1,
        "attempted_at": "2026-05-01T10:00:00Z",
        "delivery_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "duration_ms": 142,
        "http_status_code": 200,
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "resource": "delivery_attempt",
        "response_body": "ok"
      }
    ],
    "created_at": "2026-05-01T10:00:00Z",
    "event_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "last_attempt_at": "2026-05-01T10:00:00Z",
    "next_retry_at": null,
    "resource": "webhook_delivery",
    "status": "delivered",
    "subscription_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /webhook-subscriptions/{subscription_id}/deliveries/{delivery_id}/redeliver

**Redeliver webhook delivery**

Schedules another attempt for an existing delivery that has not been delivered successfully. An already delivered row returns 409 with reason `webhook_delivery_already_delivered`; use event replay when an event must be delivered again after success. The subscription must be active when redelivery is scheduled, with one exception: a platform-managed subscription paused by the platform holds its deliveries, so the redelivery is accepted and held until the platform resumes it. A subscription you paused, or a deleted one, returns 409 with reason `webhook_subscription_not_active` without changing the delivery. A subsequent pause of your own before the worker sends can still prevent delivery. Re-enable first, then use event replay to recover missed events. Track the returned delivery_id with the ordinary delivery read.

**Required capability:** `webhooks.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `subscription_id` `string` (path) *(required)*
- `delivery_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

### webhook-subscriptions-redeliver Response 202 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `accepted` | true | Yes |  |
| `delivery_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.


### webhook-subscriptions-redeliver 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.


### webhook-subscriptions-redeliver Response 401 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.


### webhook-subscriptions-redeliver Response 403 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-redeliver-response-401-schema).


### webhook-subscriptions-redeliver Response 404 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-redeliver-response-401-schema).


### webhook-subscriptions-redeliver Response 409 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-redeliver-response-401-schema).


### webhook-subscriptions-redeliver Response 500 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-redeliver-response-401-schema).


### webhook-subscriptions-redeliver Response 502 schema

Content type: `application/json`.

See [response 400 schema](#webhook-subscriptions-redeliver-response-400-schema).


### webhook-subscriptions-redeliver Response 503 schema

Content type: `application/json`.

See [response 400 schema](#webhook-subscriptions-redeliver-response-400-schema).


**Responses:**

- `202` — Request accepted for asynchronous processing. Follow the resource identifiers returned by this operation to observe progress.

  ```json
  {
    "accepted": true,
    "delivery_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /webhook-subscriptions/{subscription_id}/disable

**Disable webhook subscription**

Sets status to `paused`. Tenant subscriptions do not buffer events while paused: events published during the pause are not delivered and pending deliveries fail without a send attempt. After re-enabling, use event replay to recover events. Requires the current If-Match entity tag. Platform-managed subscriptions cannot be changed through this route.

**Required capability:** `webhooks.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `subscription_id` `string` (path) *(required)*
- `If-Match` `string` (header) *(required)* — Weak entity tag from a prior GET. Mismatch causes the request to fail with 412 Precondition Failed.
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

### webhook-subscriptions-disable Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `created_at` | string or string | Yes |  |
| `etag` | string | Yes | minLength: 1 |
| `event_types` | "*" / "tenant.enterprise.admission_reviewed.v1" / "tenant.enterprise.admitted.v1" / "tenant.enterprise.activated.v1" / "tenant.enterprise.updated.v1" / "tenant.enterprise.suspended.v1" / "tenant.enterprise.reactivated.v1" / "tenant.enterprise.closed.v1" / "tenant.enterprise.terminated.v1" / "tenant.platform_operator.admitted.v1" / "tenant.platform_operator.restricted.v1" / "tenant.platform_operator.reactivated.v1" / "tenant.platform_operator.offboarded.v1" / "tenant.platform_operator.catalog_updated.v1" / "tenant.master_account.created.v1" / "tenant.master_account.suspended.v1" / "tenant.master_account.closed.v1" / "tenant.client.created.v1" / "tenant.client.updated.v1" / "tenant.client.suspended.v1" / "tenant.client.reactivated.v1" / "tenant.client.closed.v1" / "tenant.client_account.created.v1" / "tenant.client_account.suspended.v1" / "tenant.client_account.reactivated.v1" / "tenant.client_account.closed.v1" / "ledger.transaction.posted.v1" / "operations.withdrawal.requested.v1" / "operations.withdrawal.admissible.v1" / "operations.withdrawal.executing.v1" / "operations.withdrawal.pending_approval.v1" / "operations.withdrawal.pending_compliance.v1" / "operations.withdrawal.approved.v1" / "operations.withdrawal.settled.v1" / "operations.withdrawal.failed.v1" / "operations.withdrawal.cancelled.v1" / "operations.conversion.requested.v1" / "operations.conversion.admissible.v1" / "operations.conversion.pending_approval.v1" / "operations.conversion.pending_compliance.v1" / "operations.conversion.approved.v1" / "operations.conversion.settled.v1" / "operations.conversion.failed.v1" / "operations.conversion.cancelled.v1" / "operations.external_settlement_conversion.pending_compliance.v1" / "operations.internal_transfer.requested.v1" / "operations.internal_transfer.admissible.v1" / "operations.internal_transfer.pending_approval.v1" / "operations.internal_transfer.pending_compliance.v1" / "operations.internal_transfer.approved.v1" / "operations.internal_transfer.settled.v1" / "operations.internal_transfer.failed.v1" / "operations.internal_transfer.cancelled.v1" / "operations.on_ramp.requested.v1" / "operations.on_ramp.admissible.v1" / "operations.on_ramp.pending_approval.v1" / "operations.on_ramp.pending_compliance.v1" / "operations.on_ramp.approved.v1" / "operations.on_ramp.settled.v1" / "operations.on_ramp.failed.v1" / "operations.on_ramp.cancelled.v1" / "operations.off_ramp.requested.v1" / "operations.off_ramp.admissible.v1" / "operations.off_ramp.pending_approval.v1" / "operations.off_ramp.pending_compliance.v1" / "operations.off_ramp.approved.v1" / "operations.off_ramp.settled.v1" / "operations.off_ramp.failed.v1" / "operations.off_ramp.cancelled.v1" / "operations.deposit.requested.v1" / "operations.deposit.admissible.v1" / "operations.deposit.pending_approval.v1" / "operations.deposit.pending_admission.v1" / "operations.deposit.pending_compliance.v1" / "operations.deposit.approved.v1" / "operations.deposit.settled.v1" / "operations.deposit.failed.v1" / "operations.deposit.cancelled.v1" / "rails.deposit.detected.v1" / "rails.dispatch.acknowledged.v1" / "rails.dispatch.rejected.v1" / "rails.settlement.confirmed.v1" / "kyc.verification.reviewed.v1" / "loan.originated.v1" / "loan.origination_failed.v1" / "loan.margin_called.v1" / "loan.margin_call_cleared.v1" / "loan.liquidation_halted.v1" / "loan.liquidated.v1" / "loan.repaid.v1" / "loan.extended.v1" / "loan.closed.v1" / "loan.force_closed.v1" / "loan.reconciliation_discrepancy.v1" / "tenant.enterprise.*.v1" / "tenant.*.v1" / "tenant.platform_operator.*.v1" / "tenant.master_account.*.v1" / "tenant.client.*.v1" / "tenant.client_account.*.v1" / "ledger.transaction.*.v1" / "ledger.*.v1" / "operations.withdrawal.*.v1" / "operations.*.v1" / "operations.conversion.*.v1" / "operations.external_settlement_conversion.*.v1" / "operations.internal_transfer.*.v1" / "operations.on_ramp.*.v1" / "operations.off_ramp.*.v1" / "operations.deposit.*.v1" / "rails.deposit.*.v1" / "rails.*.v1" / "rails.dispatch.*.v1" / "rails.settlement.*.v1" / "kyc.verification.*.v1" / "kyc.*.v1" / "loan.loan.*.v1" / "loan.*.v1" / "identity.human_actor.created.v1" / "identity.human_actor.pending_created.v1" / "identity.human_actor.activated.v1" / "identity.human_actor.suspended.v1" / "identity.human_actor.reactivated.v1" / "identity.human_actor.deactivated.v1" / "identity.human_actor.updated.v1" / "identity.human_actor.federation_bound.v1" / "identity.human_actor.*.v1" / "identity.human_actor.access_resend_requested.v1" / "identity.human_actor.recovery_requested.v1"[] | Yes | minItems: 1 |
| `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)$` |
| `kind` | "public" / "identity" / "command" | Yes | Which catalog classes the subscription admits: public → public events; identity → public and identity events; command → command events only. |
| `managed_by` | string or null | Yes | identity_provider_id of the IdP row that owns a core-managed subscription; null for tenant-created ones. |
| `resource` | "webhook_subscription" | Yes |  |
| `scope_ref` | string or string | Yes | Webhook subscriptions can be scoped only to an enterprise or client. |
| `signing` | "hmac" / "asymmetric" | Yes | hmac: v1 HMAC header plus the v2 Ed25519 header; asymmetric: v2 only, verified against the published JWKS. |
| `status` | "active" / "paused" / "deleted" | Yes |  |
| `updated_at` | string or string | Yes |  |
| `url` | string | Yes | format: uri |

Additional fields are not accepted.

##### application/json body.created_at

At least one alternative must match.

###### application/json body.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.created_at: alternative 2

Type: `string`. format: date-time

##### application/json body.event_types

Type: `"*" / "tenant.enterprise.admission_reviewed.v1" / "tenant.enterprise.admitted.v1" / "tenant.enterprise.activated.v1" / "tenant.enterprise.updated.v1" / "tenant.enterprise.suspended.v1" / "tenant.enterprise.reactivated.v1" / "tenant.enterprise.closed.v1" / "tenant.enterprise.terminated.v1" / "tenant.platform_operator.admitted.v1" / "tenant.platform_operator.restricted.v1" / "tenant.platform_operator.reactivated.v1" / "tenant.platform_operator.offboarded.v1" / "tenant.platform_operator.catalog_updated.v1" / "tenant.master_account.created.v1" / "tenant.master_account.suspended.v1" / "tenant.master_account.closed.v1" / "tenant.client.created.v1" / "tenant.client.updated.v1" / "tenant.client.suspended.v1" / "tenant.client.reactivated.v1" / "tenant.client.closed.v1" / "tenant.client_account.created.v1" / "tenant.client_account.suspended.v1" / "tenant.client_account.reactivated.v1" / "tenant.client_account.closed.v1" / "ledger.transaction.posted.v1" / "operations.withdrawal.requested.v1" / "operations.withdrawal.admissible.v1" / "operations.withdrawal.executing.v1" / "operations.withdrawal.pending_approval.v1" / "operations.withdrawal.pending_compliance.v1" / "operations.withdrawal.approved.v1" / "operations.withdrawal.settled.v1" / "operations.withdrawal.failed.v1" / "operations.withdrawal.cancelled.v1" / "operations.conversion.requested.v1" / "operations.conversion.admissible.v1" / "operations.conversion.pending_approval.v1" / "operations.conversion.pending_compliance.v1" / "operations.conversion.approved.v1" / "operations.conversion.settled.v1" / "operations.conversion.failed.v1" / "operations.conversion.cancelled.v1" / "operations.external_settlement_conversion.pending_compliance.v1" / "operations.internal_transfer.requested.v1" / "operations.internal_transfer.admissible.v1" / "operations.internal_transfer.pending_approval.v1" / "operations.internal_transfer.pending_compliance.v1" / "operations.internal_transfer.approved.v1" / "operations.internal_transfer.settled.v1" / "operations.internal_transfer.failed.v1" / "operations.internal_transfer.cancelled.v1" / "operations.on_ramp.requested.v1" / "operations.on_ramp.admissible.v1" / "operations.on_ramp.pending_approval.v1" / "operations.on_ramp.pending_compliance.v1" / "operations.on_ramp.approved.v1" / "operations.on_ramp.settled.v1" / "operations.on_ramp.failed.v1" / "operations.on_ramp.cancelled.v1" / "operations.off_ramp.requested.v1" / "operations.off_ramp.admissible.v1" / "operations.off_ramp.pending_approval.v1" / "operations.off_ramp.pending_compliance.v1" / "operations.off_ramp.approved.v1" / "operations.off_ramp.settled.v1" / "operations.off_ramp.failed.v1" / "operations.off_ramp.cancelled.v1" / "operations.deposit.requested.v1" / "operations.deposit.admissible.v1" / "operations.deposit.pending_approval.v1" / "operations.deposit.pending_admission.v1" / "operations.deposit.pending_compliance.v1" / "operations.deposit.approved.v1" / "operations.deposit.settled.v1" / "operations.deposit.failed.v1" / "operations.deposit.cancelled.v1" / "rails.deposit.detected.v1" / "rails.dispatch.acknowledged.v1" / "rails.dispatch.rejected.v1" / "rails.settlement.confirmed.v1" / "kyc.verification.reviewed.v1" / "loan.originated.v1" / "loan.origination_failed.v1" / "loan.margin_called.v1" / "loan.margin_call_cleared.v1" / "loan.liquidation_halted.v1" / "loan.liquidated.v1" / "loan.repaid.v1" / "loan.extended.v1" / "loan.closed.v1" / "loan.force_closed.v1" / "loan.reconciliation_discrepancy.v1" / "tenant.enterprise.*.v1" / "tenant.*.v1" / "tenant.platform_operator.*.v1" / "tenant.master_account.*.v1" / "tenant.client.*.v1" / "tenant.client_account.*.v1" / "ledger.transaction.*.v1" / "ledger.*.v1" / "operations.withdrawal.*.v1" / "operations.*.v1" / "operations.conversion.*.v1" / "operations.external_settlement_conversion.*.v1" / "operations.internal_transfer.*.v1" / "operations.on_ramp.*.v1" / "operations.off_ramp.*.v1" / "operations.deposit.*.v1" / "rails.deposit.*.v1" / "rails.*.v1" / "rails.dispatch.*.v1" / "rails.settlement.*.v1" / "kyc.verification.*.v1" / "kyc.*.v1" / "loan.loan.*.v1" / "loan.*.v1" / "identity.human_actor.created.v1" / "identity.human_actor.pending_created.v1" / "identity.human_actor.activated.v1" / "identity.human_actor.suspended.v1" / "identity.human_actor.reactivated.v1" / "identity.human_actor.deactivated.v1" / "identity.human_actor.updated.v1" / "identity.human_actor.federation_bound.v1" / "identity.human_actor.*.v1" / "identity.human_actor.access_resend_requested.v1" / "identity.human_actor.recovery_requested.v1"[]`. minItems: 1

###### application/json body.event_types item

Type: `"*" / "tenant.enterprise.admission_reviewed.v1" / "tenant.enterprise.admitted.v1" / "tenant.enterprise.activated.v1" / "tenant.enterprise.updated.v1" / "tenant.enterprise.suspended.v1" / "tenant.enterprise.reactivated.v1" / "tenant.enterprise.closed.v1" / "tenant.enterprise.terminated.v1" / "tenant.platform_operator.admitted.v1" / "tenant.platform_operator.restricted.v1" / "tenant.platform_operator.reactivated.v1" / "tenant.platform_operator.offboarded.v1" / "tenant.platform_operator.catalog_updated.v1" / "tenant.master_account.created.v1" / "tenant.master_account.suspended.v1" / "tenant.master_account.closed.v1" / "tenant.client.created.v1" / "tenant.client.updated.v1" / "tenant.client.suspended.v1" / "tenant.client.reactivated.v1" / "tenant.client.closed.v1" / "tenant.client_account.created.v1" / "tenant.client_account.suspended.v1" / "tenant.client_account.reactivated.v1" / "tenant.client_account.closed.v1" / "ledger.transaction.posted.v1" / "operations.withdrawal.requested.v1" / "operations.withdrawal.admissible.v1" / "operations.withdrawal.executing.v1" / "operations.withdrawal.pending_approval.v1" / "operations.withdrawal.pending_compliance.v1" / "operations.withdrawal.approved.v1" / "operations.withdrawal.settled.v1" / "operations.withdrawal.failed.v1" / "operations.withdrawal.cancelled.v1" / "operations.conversion.requested.v1" / "operations.conversion.admissible.v1" / "operations.conversion.pending_approval.v1" / "operations.conversion.pending_compliance.v1" / "operations.conversion.approved.v1" / "operations.conversion.settled.v1" / "operations.conversion.failed.v1" / "operations.conversion.cancelled.v1" / "operations.external_settlement_conversion.pending_compliance.v1" / "operations.internal_transfer.requested.v1" / "operations.internal_transfer.admissible.v1" / "operations.internal_transfer.pending_approval.v1" / "operations.internal_transfer.pending_compliance.v1" / "operations.internal_transfer.approved.v1" / "operations.internal_transfer.settled.v1" / "operations.internal_transfer.failed.v1" / "operations.internal_transfer.cancelled.v1" / "operations.on_ramp.requested.v1" / "operations.on_ramp.admissible.v1" / "operations.on_ramp.pending_approval.v1" / "operations.on_ramp.pending_compliance.v1" / "operations.on_ramp.approved.v1" / "operations.on_ramp.settled.v1" / "operations.on_ramp.failed.v1" / "operations.on_ramp.cancelled.v1" / "operations.off_ramp.requested.v1" / "operations.off_ramp.admissible.v1" / "operations.off_ramp.pending_approval.v1" / "operations.off_ramp.pending_compliance.v1" / "operations.off_ramp.approved.v1" / "operations.off_ramp.settled.v1" / "operations.off_ramp.failed.v1" / "operations.off_ramp.cancelled.v1" / "operations.deposit.requested.v1" / "operations.deposit.admissible.v1" / "operations.deposit.pending_approval.v1" / "operations.deposit.pending_admission.v1" / "operations.deposit.pending_compliance.v1" / "operations.deposit.approved.v1" / "operations.deposit.settled.v1" / "operations.deposit.failed.v1" / "operations.deposit.cancelled.v1" / "rails.deposit.detected.v1" / "rails.dispatch.acknowledged.v1" / "rails.dispatch.rejected.v1" / "rails.settlement.confirmed.v1" / "kyc.verification.reviewed.v1" / "loan.originated.v1" / "loan.origination_failed.v1" / "loan.margin_called.v1" / "loan.margin_call_cleared.v1" / "loan.liquidation_halted.v1" / "loan.liquidated.v1" / "loan.repaid.v1" / "loan.extended.v1" / "loan.closed.v1" / "loan.force_closed.v1" / "loan.reconciliation_discrepancy.v1" / "tenant.enterprise.*.v1" / "tenant.*.v1" / "tenant.platform_operator.*.v1" / "tenant.master_account.*.v1" / "tenant.client.*.v1" / "tenant.client_account.*.v1" / "ledger.transaction.*.v1" / "ledger.*.v1" / "operations.withdrawal.*.v1" / "operations.*.v1" / "operations.conversion.*.v1" / "operations.external_settlement_conversion.*.v1" / "operations.internal_transfer.*.v1" / "operations.on_ramp.*.v1" / "operations.off_ramp.*.v1" / "operations.deposit.*.v1" / "rails.deposit.*.v1" / "rails.*.v1" / "rails.dispatch.*.v1" / "rails.settlement.*.v1" / "kyc.verification.*.v1" / "kyc.*.v1" / "loan.loan.*.v1" / "loan.*.v1" / "identity.human_actor.created.v1" / "identity.human_actor.pending_created.v1" / "identity.human_actor.activated.v1" / "identity.human_actor.suspended.v1" / "identity.human_actor.reactivated.v1" / "identity.human_actor.deactivated.v1" / "identity.human_actor.updated.v1" / "identity.human_actor.federation_bound.v1" / "identity.human_actor.*.v1" / "identity.human_actor.access_resend_requested.v1" / "identity.human_actor.recovery_requested.v1"`. 

##### application/json body.managed_by

identity_provider_id of the IdP row that owns a core-managed subscription; null for tenant-created ones.

At least one alternative must match.

###### application/json body.managed_by: alternative 1

Type: `string`. 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)$`

###### application/json body.managed_by: alternative 2

Type: `null`. 

##### application/json body.scope_ref

Webhook subscriptions can be scoped only to an enterprise or client.

At least one alternative must match.

###### application/json body.scope_ref: alternative 1

Type: `string`. pattern: `^(enterprises)\/([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})$`

###### application/json body.scope_ref: alternative 2

Type: `string`. pattern: `^(clients)\/([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})$`

##### application/json body.updated_at

At least one alternative must match.

###### application/json body.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.updated_at: alternative 2

Type: `string`. format: date-time


### webhook-subscriptions-disable 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.


### webhook-subscriptions-disable Response 401 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.


### webhook-subscriptions-disable Response 403 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-disable-response-401-schema).


### webhook-subscriptions-disable Response 404 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-disable-response-401-schema).


### webhook-subscriptions-disable Response 409 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-disable-response-401-schema).


### webhook-subscriptions-disable Response 412 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-disable-response-401-schema).


### webhook-subscriptions-disable Response 500 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-disable-response-401-schema).


### webhook-subscriptions-disable Response 502 schema

Content type: `application/json`.

See [response 400 schema](#webhook-subscriptions-disable-response-400-schema).


### webhook-subscriptions-disable Response 503 schema

Content type: `application/json`.

See [response 400 schema](#webhook-subscriptions-disable-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "created_at": "2026-05-01T10:00:00Z",
    "etag": "2026-05-01T10:00:00Z",
    "event_types": [
      "operations.withdrawal.settled.v1"
    ],
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "kind": "public",
    "managed_by": null,
    "resource": "webhook_subscription",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "signing": "hmac",
    "status": "paused",
    "updated_at": "2026-05-01T10:00:00Z",
    "url": "https://example.com/webhooks"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `412` — If-Match check failed; the resource has changed since the cached etag.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /webhook-subscriptions/{subscription_id}/enable

**Enable webhook subscription**

Activates a paused tenant-created subscription and requires the current If-Match entity tag. A deleted subscription cannot be reactivated and returns 409 with reason `webhook_subscription_not_active`. Enabling an identity event stream additionally requires users.read covering the subscription scope. Platform-managed subscriptions cannot be changed through this route.

**Required capability:** `webhooks.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `subscription_id` `string` (path) *(required)*
- `If-Match` `string` (header) *(required)* — Weak entity tag from a prior GET. Mismatch causes the request to fail with 412 Precondition Failed.
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

### webhook-subscriptions-enable Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `created_at` | string or string | Yes |  |
| `etag` | string | Yes | minLength: 1 |
| `event_types` | "*" / "tenant.enterprise.admission_reviewed.v1" / "tenant.enterprise.admitted.v1" / "tenant.enterprise.activated.v1" / "tenant.enterprise.updated.v1" / "tenant.enterprise.suspended.v1" / "tenant.enterprise.reactivated.v1" / "tenant.enterprise.closed.v1" / "tenant.enterprise.terminated.v1" / "tenant.platform_operator.admitted.v1" / "tenant.platform_operator.restricted.v1" / "tenant.platform_operator.reactivated.v1" / "tenant.platform_operator.offboarded.v1" / "tenant.platform_operator.catalog_updated.v1" / "tenant.master_account.created.v1" / "tenant.master_account.suspended.v1" / "tenant.master_account.closed.v1" / "tenant.client.created.v1" / "tenant.client.updated.v1" / "tenant.client.suspended.v1" / "tenant.client.reactivated.v1" / "tenant.client.closed.v1" / "tenant.client_account.created.v1" / "tenant.client_account.suspended.v1" / "tenant.client_account.reactivated.v1" / "tenant.client_account.closed.v1" / "ledger.transaction.posted.v1" / "operations.withdrawal.requested.v1" / "operations.withdrawal.admissible.v1" / "operations.withdrawal.executing.v1" / "operations.withdrawal.pending_approval.v1" / "operations.withdrawal.pending_compliance.v1" / "operations.withdrawal.approved.v1" / "operations.withdrawal.settled.v1" / "operations.withdrawal.failed.v1" / "operations.withdrawal.cancelled.v1" / "operations.conversion.requested.v1" / "operations.conversion.admissible.v1" / "operations.conversion.pending_approval.v1" / "operations.conversion.pending_compliance.v1" / "operations.conversion.approved.v1" / "operations.conversion.settled.v1" / "operations.conversion.failed.v1" / "operations.conversion.cancelled.v1" / "operations.external_settlement_conversion.pending_compliance.v1" / "operations.internal_transfer.requested.v1" / "operations.internal_transfer.admissible.v1" / "operations.internal_transfer.pending_approval.v1" / "operations.internal_transfer.pending_compliance.v1" / "operations.internal_transfer.approved.v1" / "operations.internal_transfer.settled.v1" / "operations.internal_transfer.failed.v1" / "operations.internal_transfer.cancelled.v1" / "operations.on_ramp.requested.v1" / "operations.on_ramp.admissible.v1" / "operations.on_ramp.pending_approval.v1" / "operations.on_ramp.pending_compliance.v1" / "operations.on_ramp.approved.v1" / "operations.on_ramp.settled.v1" / "operations.on_ramp.failed.v1" / "operations.on_ramp.cancelled.v1" / "operations.off_ramp.requested.v1" / "operations.off_ramp.admissible.v1" / "operations.off_ramp.pending_approval.v1" / "operations.off_ramp.pending_compliance.v1" / "operations.off_ramp.approved.v1" / "operations.off_ramp.settled.v1" / "operations.off_ramp.failed.v1" / "operations.off_ramp.cancelled.v1" / "operations.deposit.requested.v1" / "operations.deposit.admissible.v1" / "operations.deposit.pending_approval.v1" / "operations.deposit.pending_admission.v1" / "operations.deposit.pending_compliance.v1" / "operations.deposit.approved.v1" / "operations.deposit.settled.v1" / "operations.deposit.failed.v1" / "operations.deposit.cancelled.v1" / "rails.deposit.detected.v1" / "rails.dispatch.acknowledged.v1" / "rails.dispatch.rejected.v1" / "rails.settlement.confirmed.v1" / "kyc.verification.reviewed.v1" / "loan.originated.v1" / "loan.origination_failed.v1" / "loan.margin_called.v1" / "loan.margin_call_cleared.v1" / "loan.liquidation_halted.v1" / "loan.liquidated.v1" / "loan.repaid.v1" / "loan.extended.v1" / "loan.closed.v1" / "loan.force_closed.v1" / "loan.reconciliation_discrepancy.v1" / "tenant.enterprise.*.v1" / "tenant.*.v1" / "tenant.platform_operator.*.v1" / "tenant.master_account.*.v1" / "tenant.client.*.v1" / "tenant.client_account.*.v1" / "ledger.transaction.*.v1" / "ledger.*.v1" / "operations.withdrawal.*.v1" / "operations.*.v1" / "operations.conversion.*.v1" / "operations.external_settlement_conversion.*.v1" / "operations.internal_transfer.*.v1" / "operations.on_ramp.*.v1" / "operations.off_ramp.*.v1" / "operations.deposit.*.v1" / "rails.deposit.*.v1" / "rails.*.v1" / "rails.dispatch.*.v1" / "rails.settlement.*.v1" / "kyc.verification.*.v1" / "kyc.*.v1" / "loan.loan.*.v1" / "loan.*.v1" / "identity.human_actor.created.v1" / "identity.human_actor.pending_created.v1" / "identity.human_actor.activated.v1" / "identity.human_actor.suspended.v1" / "identity.human_actor.reactivated.v1" / "identity.human_actor.deactivated.v1" / "identity.human_actor.updated.v1" / "identity.human_actor.federation_bound.v1" / "identity.human_actor.*.v1" / "identity.human_actor.access_resend_requested.v1" / "identity.human_actor.recovery_requested.v1"[] | Yes | minItems: 1 |
| `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)$` |
| `kind` | "public" / "identity" / "command" | Yes | Which catalog classes the subscription admits: public → public events; identity → public and identity events; command → command events only. |
| `managed_by` | string or null | Yes | identity_provider_id of the IdP row that owns a core-managed subscription; null for tenant-created ones. |
| `resource` | "webhook_subscription" | Yes |  |
| `scope_ref` | string or string | Yes | Webhook subscriptions can be scoped only to an enterprise or client. |
| `signing` | "hmac" / "asymmetric" | Yes | hmac: v1 HMAC header plus the v2 Ed25519 header; asymmetric: v2 only, verified against the published JWKS. |
| `status` | "active" / "paused" / "deleted" | Yes |  |
| `updated_at` | string or string | Yes |  |
| `url` | string | Yes | format: uri |

Additional fields are not accepted.

##### application/json body.created_at

At least one alternative must match.

###### application/json body.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.created_at: alternative 2

Type: `string`. format: date-time

##### application/json body.event_types

Type: `"*" / "tenant.enterprise.admission_reviewed.v1" / "tenant.enterprise.admitted.v1" / "tenant.enterprise.activated.v1" / "tenant.enterprise.updated.v1" / "tenant.enterprise.suspended.v1" / "tenant.enterprise.reactivated.v1" / "tenant.enterprise.closed.v1" / "tenant.enterprise.terminated.v1" / "tenant.platform_operator.admitted.v1" / "tenant.platform_operator.restricted.v1" / "tenant.platform_operator.reactivated.v1" / "tenant.platform_operator.offboarded.v1" / "tenant.platform_operator.catalog_updated.v1" / "tenant.master_account.created.v1" / "tenant.master_account.suspended.v1" / "tenant.master_account.closed.v1" / "tenant.client.created.v1" / "tenant.client.updated.v1" / "tenant.client.suspended.v1" / "tenant.client.reactivated.v1" / "tenant.client.closed.v1" / "tenant.client_account.created.v1" / "tenant.client_account.suspended.v1" / "tenant.client_account.reactivated.v1" / "tenant.client_account.closed.v1" / "ledger.transaction.posted.v1" / "operations.withdrawal.requested.v1" / "operations.withdrawal.admissible.v1" / "operations.withdrawal.executing.v1" / "operations.withdrawal.pending_approval.v1" / "operations.withdrawal.pending_compliance.v1" / "operations.withdrawal.approved.v1" / "operations.withdrawal.settled.v1" / "operations.withdrawal.failed.v1" / "operations.withdrawal.cancelled.v1" / "operations.conversion.requested.v1" / "operations.conversion.admissible.v1" / "operations.conversion.pending_approval.v1" / "operations.conversion.pending_compliance.v1" / "operations.conversion.approved.v1" / "operations.conversion.settled.v1" / "operations.conversion.failed.v1" / "operations.conversion.cancelled.v1" / "operations.external_settlement_conversion.pending_compliance.v1" / "operations.internal_transfer.requested.v1" / "operations.internal_transfer.admissible.v1" / "operations.internal_transfer.pending_approval.v1" / "operations.internal_transfer.pending_compliance.v1" / "operations.internal_transfer.approved.v1" / "operations.internal_transfer.settled.v1" / "operations.internal_transfer.failed.v1" / "operations.internal_transfer.cancelled.v1" / "operations.on_ramp.requested.v1" / "operations.on_ramp.admissible.v1" / "operations.on_ramp.pending_approval.v1" / "operations.on_ramp.pending_compliance.v1" / "operations.on_ramp.approved.v1" / "operations.on_ramp.settled.v1" / "operations.on_ramp.failed.v1" / "operations.on_ramp.cancelled.v1" / "operations.off_ramp.requested.v1" / "operations.off_ramp.admissible.v1" / "operations.off_ramp.pending_approval.v1" / "operations.off_ramp.pending_compliance.v1" / "operations.off_ramp.approved.v1" / "operations.off_ramp.settled.v1" / "operations.off_ramp.failed.v1" / "operations.off_ramp.cancelled.v1" / "operations.deposit.requested.v1" / "operations.deposit.admissible.v1" / "operations.deposit.pending_approval.v1" / "operations.deposit.pending_admission.v1" / "operations.deposit.pending_compliance.v1" / "operations.deposit.approved.v1" / "operations.deposit.settled.v1" / "operations.deposit.failed.v1" / "operations.deposit.cancelled.v1" / "rails.deposit.detected.v1" / "rails.dispatch.acknowledged.v1" / "rails.dispatch.rejected.v1" / "rails.settlement.confirmed.v1" / "kyc.verification.reviewed.v1" / "loan.originated.v1" / "loan.origination_failed.v1" / "loan.margin_called.v1" / "loan.margin_call_cleared.v1" / "loan.liquidation_halted.v1" / "loan.liquidated.v1" / "loan.repaid.v1" / "loan.extended.v1" / "loan.closed.v1" / "loan.force_closed.v1" / "loan.reconciliation_discrepancy.v1" / "tenant.enterprise.*.v1" / "tenant.*.v1" / "tenant.platform_operator.*.v1" / "tenant.master_account.*.v1" / "tenant.client.*.v1" / "tenant.client_account.*.v1" / "ledger.transaction.*.v1" / "ledger.*.v1" / "operations.withdrawal.*.v1" / "operations.*.v1" / "operations.conversion.*.v1" / "operations.external_settlement_conversion.*.v1" / "operations.internal_transfer.*.v1" / "operations.on_ramp.*.v1" / "operations.off_ramp.*.v1" / "operations.deposit.*.v1" / "rails.deposit.*.v1" / "rails.*.v1" / "rails.dispatch.*.v1" / "rails.settlement.*.v1" / "kyc.verification.*.v1" / "kyc.*.v1" / "loan.loan.*.v1" / "loan.*.v1" / "identity.human_actor.created.v1" / "identity.human_actor.pending_created.v1" / "identity.human_actor.activated.v1" / "identity.human_actor.suspended.v1" / "identity.human_actor.reactivated.v1" / "identity.human_actor.deactivated.v1" / "identity.human_actor.updated.v1" / "identity.human_actor.federation_bound.v1" / "identity.human_actor.*.v1" / "identity.human_actor.access_resend_requested.v1" / "identity.human_actor.recovery_requested.v1"[]`. minItems: 1

###### application/json body.event_types item

Type: `"*" / "tenant.enterprise.admission_reviewed.v1" / "tenant.enterprise.admitted.v1" / "tenant.enterprise.activated.v1" / "tenant.enterprise.updated.v1" / "tenant.enterprise.suspended.v1" / "tenant.enterprise.reactivated.v1" / "tenant.enterprise.closed.v1" / "tenant.enterprise.terminated.v1" / "tenant.platform_operator.admitted.v1" / "tenant.platform_operator.restricted.v1" / "tenant.platform_operator.reactivated.v1" / "tenant.platform_operator.offboarded.v1" / "tenant.platform_operator.catalog_updated.v1" / "tenant.master_account.created.v1" / "tenant.master_account.suspended.v1" / "tenant.master_account.closed.v1" / "tenant.client.created.v1" / "tenant.client.updated.v1" / "tenant.client.suspended.v1" / "tenant.client.reactivated.v1" / "tenant.client.closed.v1" / "tenant.client_account.created.v1" / "tenant.client_account.suspended.v1" / "tenant.client_account.reactivated.v1" / "tenant.client_account.closed.v1" / "ledger.transaction.posted.v1" / "operations.withdrawal.requested.v1" / "operations.withdrawal.admissible.v1" / "operations.withdrawal.executing.v1" / "operations.withdrawal.pending_approval.v1" / "operations.withdrawal.pending_compliance.v1" / "operations.withdrawal.approved.v1" / "operations.withdrawal.settled.v1" / "operations.withdrawal.failed.v1" / "operations.withdrawal.cancelled.v1" / "operations.conversion.requested.v1" / "operations.conversion.admissible.v1" / "operations.conversion.pending_approval.v1" / "operations.conversion.pending_compliance.v1" / "operations.conversion.approved.v1" / "operations.conversion.settled.v1" / "operations.conversion.failed.v1" / "operations.conversion.cancelled.v1" / "operations.external_settlement_conversion.pending_compliance.v1" / "operations.internal_transfer.requested.v1" / "operations.internal_transfer.admissible.v1" / "operations.internal_transfer.pending_approval.v1" / "operations.internal_transfer.pending_compliance.v1" / "operations.internal_transfer.approved.v1" / "operations.internal_transfer.settled.v1" / "operations.internal_transfer.failed.v1" / "operations.internal_transfer.cancelled.v1" / "operations.on_ramp.requested.v1" / "operations.on_ramp.admissible.v1" / "operations.on_ramp.pending_approval.v1" / "operations.on_ramp.pending_compliance.v1" / "operations.on_ramp.approved.v1" / "operations.on_ramp.settled.v1" / "operations.on_ramp.failed.v1" / "operations.on_ramp.cancelled.v1" / "operations.off_ramp.requested.v1" / "operations.off_ramp.admissible.v1" / "operations.off_ramp.pending_approval.v1" / "operations.off_ramp.pending_compliance.v1" / "operations.off_ramp.approved.v1" / "operations.off_ramp.settled.v1" / "operations.off_ramp.failed.v1" / "operations.off_ramp.cancelled.v1" / "operations.deposit.requested.v1" / "operations.deposit.admissible.v1" / "operations.deposit.pending_approval.v1" / "operations.deposit.pending_admission.v1" / "operations.deposit.pending_compliance.v1" / "operations.deposit.approved.v1" / "operations.deposit.settled.v1" / "operations.deposit.failed.v1" / "operations.deposit.cancelled.v1" / "rails.deposit.detected.v1" / "rails.dispatch.acknowledged.v1" / "rails.dispatch.rejected.v1" / "rails.settlement.confirmed.v1" / "kyc.verification.reviewed.v1" / "loan.originated.v1" / "loan.origination_failed.v1" / "loan.margin_called.v1" / "loan.margin_call_cleared.v1" / "loan.liquidation_halted.v1" / "loan.liquidated.v1" / "loan.repaid.v1" / "loan.extended.v1" / "loan.closed.v1" / "loan.force_closed.v1" / "loan.reconciliation_discrepancy.v1" / "tenant.enterprise.*.v1" / "tenant.*.v1" / "tenant.platform_operator.*.v1" / "tenant.master_account.*.v1" / "tenant.client.*.v1" / "tenant.client_account.*.v1" / "ledger.transaction.*.v1" / "ledger.*.v1" / "operations.withdrawal.*.v1" / "operations.*.v1" / "operations.conversion.*.v1" / "operations.external_settlement_conversion.*.v1" / "operations.internal_transfer.*.v1" / "operations.on_ramp.*.v1" / "operations.off_ramp.*.v1" / "operations.deposit.*.v1" / "rails.deposit.*.v1" / "rails.*.v1" / "rails.dispatch.*.v1" / "rails.settlement.*.v1" / "kyc.verification.*.v1" / "kyc.*.v1" / "loan.loan.*.v1" / "loan.*.v1" / "identity.human_actor.created.v1" / "identity.human_actor.pending_created.v1" / "identity.human_actor.activated.v1" / "identity.human_actor.suspended.v1" / "identity.human_actor.reactivated.v1" / "identity.human_actor.deactivated.v1" / "identity.human_actor.updated.v1" / "identity.human_actor.federation_bound.v1" / "identity.human_actor.*.v1" / "identity.human_actor.access_resend_requested.v1" / "identity.human_actor.recovery_requested.v1"`. 

##### application/json body.managed_by

identity_provider_id of the IdP row that owns a core-managed subscription; null for tenant-created ones.

At least one alternative must match.

###### application/json body.managed_by: alternative 1

Type: `string`. 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)$`

###### application/json body.managed_by: alternative 2

Type: `null`. 

##### application/json body.scope_ref

Webhook subscriptions can be scoped only to an enterprise or client.

At least one alternative must match.

###### application/json body.scope_ref: alternative 1

Type: `string`. pattern: `^(enterprises)\/([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})$`

###### application/json body.scope_ref: alternative 2

Type: `string`. pattern: `^(clients)\/([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})$`

##### application/json body.updated_at

At least one alternative must match.

###### application/json body.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.updated_at: alternative 2

Type: `string`. format: date-time


### webhook-subscriptions-enable 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.


### webhook-subscriptions-enable Response 401 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.


### webhook-subscriptions-enable Response 403 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-enable-response-401-schema).


### webhook-subscriptions-enable Response 404 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-enable-response-401-schema).


### webhook-subscriptions-enable Response 409 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-enable-response-401-schema).


### webhook-subscriptions-enable Response 412 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-enable-response-401-schema).


### webhook-subscriptions-enable Response 500 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-enable-response-401-schema).


### webhook-subscriptions-enable Response 502 schema

Content type: `application/json`.

See [response 400 schema](#webhook-subscriptions-enable-response-400-schema).


### webhook-subscriptions-enable Response 503 schema

Content type: `application/json`.

See [response 400 schema](#webhook-subscriptions-enable-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "created_at": "2026-05-01T10:00:00Z",
    "etag": "2026-05-01T10:00:00Z",
    "event_types": [
      "operations.withdrawal.settled.v1"
    ],
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "kind": "public",
    "managed_by": null,
    "resource": "webhook_subscription",
    "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "signing": "hmac",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z",
    "url": "https://example.com/webhooks"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `412` — If-Match check failed; the resource has changed since the cached etag.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /webhook-subscriptions/{subscription_id}/test

**Send webhook test delivery**

Sends a synthetic test event to an active tenant-managed subscription and returns the delivery snapshot, including the first attempt. Failed attempts follow the ordinary retry and dead-letter flow. A paused or deleted subscription returns 409 with reason `webhook_subscription_not_active`; a platform-managed subscription returns 409 with reason `subscription_managed`.

**Required capability:** `webhooks.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `subscription_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

### webhook-subscriptions-test Response 202 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `accepted` | true | Yes |  |
| `delivery` | object | Yes | No additional fields |

Additional fields are not accepted.

##### application/json body.delivery

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `attempt_count` | integer | Yes | minimum: 0; maximum: 9007199254740991 |
| `attempts` | object[] | Yes |  |
| `created_at` | string or string | Yes |  |
| `event_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)$` |
| `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)$` |
| `last_attempt_at` | string or string or null | Yes |  |
| `next_retry_at` | string or string or null | Yes |  |
| `resource` | "webhook_delivery" | Yes |  |
| `status` | "pending" / "delivered" / "failed" / "retrying" / "dlq" | Yes |  |
| `subscription_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.

###### application/json body.delivery.attempts

Type: `object[]`. 

###### application/json body.delivery.attempts item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `attempt_number` | integer | Yes | maximum: 9007199254740991; exclusiveMinimum: 0 |
| `attempted_at` | string or string | Yes |  |
| `delivery_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)$` |
| `duration_ms` | integer | Yes | minimum: 0; maximum: 9007199254740991 |
| `http_status_code` | integer or null | Yes |  |
| `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)$` |
| `resource` | "delivery_attempt" | Yes |  |
| `response_body` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.delivery.attempts item.attempted_at

At least one alternative must match.

###### application/json body.delivery.attempts item.attempted_at: alternative 1

Type: `string`. 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))$`

###### application/json body.delivery.attempts item.attempted_at: alternative 2

Type: `string`. format: date-time

###### application/json body.delivery.attempts item.http_status_code

At least one alternative must match.

###### application/json body.delivery.attempts item.http_status_code: alternative 1

Type: `integer`. minimum: 100; maximum: 599

###### application/json body.delivery.attempts item.http_status_code: alternative 2

Type: `null`. 

###### application/json body.delivery.attempts item.response_body

At least one alternative must match.

###### application/json body.delivery.attempts item.response_body: alternative 1

Type: `string`. 

###### application/json body.delivery.attempts item.response_body: alternative 2

Type: `null`. 

###### application/json body.delivery.created_at

At least one alternative must match.

###### application/json body.delivery.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.delivery.created_at: alternative 2

Type: `string`. format: date-time

###### application/json body.delivery.last_attempt_at

At least one alternative must match.

###### application/json body.delivery.last_attempt_at: alternative 1

At least one alternative must match.

###### application/json body.delivery.last_attempt_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.delivery.last_attempt_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.delivery.last_attempt_at: alternative 2

Type: `null`. 

###### application/json body.delivery.next_retry_at

At least one alternative must match.

###### application/json body.delivery.next_retry_at: alternative 1

At least one alternative must match.

###### application/json body.delivery.next_retry_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.delivery.next_retry_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.delivery.next_retry_at: alternative 2

Type: `null`.


### webhook-subscriptions-test 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.


### webhook-subscriptions-test Response 401 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.


### webhook-subscriptions-test Response 403 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-test-response-401-schema).


### webhook-subscriptions-test Response 404 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-test-response-401-schema).


### webhook-subscriptions-test Response 409 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-test-response-401-schema).


### webhook-subscriptions-test Response 500 schema

Content type: `application/json`.

See [response 401 schema](#webhook-subscriptions-test-response-401-schema).


### webhook-subscriptions-test Response 502 schema

Content type: `application/json`.

See [response 400 schema](#webhook-subscriptions-test-response-400-schema).


### webhook-subscriptions-test Response 503 schema

Content type: `application/json`.

See [response 400 schema](#webhook-subscriptions-test-response-400-schema).


**Responses:**

- `202` — Request accepted for asynchronous processing. Follow the resource identifiers returned by this operation to observe progress.

  ```json
  {
    "accepted": true,
    "delivery": {
      "attempt_count": 1,
      "attempts": [
        {
          "attempt_number": 1,
          "attempted_at": "2026-05-01T10:00:00Z",
          "delivery_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
          "duration_ms": 142,
          "http_status_code": 200,
          "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
          "resource": "delivery_attempt",
          "response_body": "ok"
        }
      ],
      "created_at": "2026-05-01T10:00:00Z",
      "event_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "last_attempt_at": "2026-05-01T10:00:00Z",
      "next_retry_at": null,
      "resource": "webhook_delivery",
      "status": "delivered",
      "subscription_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
    }
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Events

### GET /events

**List events**

Lists tenant-visible platform events. If omitted, `scope_ref` is derived from the authenticated enterprise or client context.

**Required capability:** `events.read`

**Authentication:** Bearer token required.

**Parameters:**

- `scope_ref` `string` (query)
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.
- `from_date` `string` (query)
- `to_date` `string` (query)
- `actor_id` `string` (query)
- `aggregate_type` `string` (query)
- `aggregate_id` `string` (query)
- `event_type` `string` (query)
- `event_type_pattern` `string` (query)
- `trace_id` `string` (query)

### events-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `aggregate` | object | Yes | No additional fields |
| `data` | object | Yes |  |
| `event_type` | string | Yes | minLength: 1 |
| `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)$` |
| `metadata` | object or null | Yes |  |
| `occurred_at` | string or string | Yes |  |
| `partition_key` | string | Yes | minLength: 1 |
| `published_at` | string or string | Yes |  |
| `resource` | "event" | Yes |  |
| `schema_version` | integer | Yes | maximum: 9007199254740991; exclusiveMinimum: 0 |
| `scope_ref` | string or null | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `trace_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.

###### application/json body.items item.aggregate

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `type` | string | Yes | minLength: 1 |
| `id` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.items item.metadata

At least one alternative must match.

###### application/json body.items item.metadata: alternative 1

Type: `object`. 

###### application/json body.items item.metadata: alternative 2

Type: `null`. 

###### application/json body.items item.occurred_at

At least one alternative must match.

###### application/json body.items item.occurred_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.occurred_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.published_at

At least one alternative must match.

###### application/json body.items item.published_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.published_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.scope_ref

At least one alternative must match.

###### application/json body.items item.scope_ref: alternative 1

Type: `string`. pattern: `^(enterprises|clients|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})$`

###### application/json body.items item.scope_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.actor

At least one alternative must match.

###### application/json body.items item.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.approved_by

At least one alternative must match.

###### application/json body.items item.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.items item.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.items item.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.federation

At least one alternative must match.

###### application/json body.items item.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body.items item.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.subject

At least one alternative must match.

###### application/json body.items item.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.subject: alternative 2

Type: `null`. 

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. 

###### application/json body.next_page_token: alternative 2

Type: `null`.


### events-list 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.


### events-list Response 401 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.


### events-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#events-list-response-401-schema).


### events-list Response 404 schema

Content type: `application/json`.

See [response 401 schema](#events-list-response-401-schema).


### events-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#events-list-response-401-schema).


### events-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#events-list-response-400-schema).


### events-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#events-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "aggregate": {
          "type": "withdrawal",
          "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
        },
        "data": {
          "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
          "failure_reason": null,
          "family": "withdrawal",
          "fee_summary": {
            "components": [
              {
                "amount": {
                  "currency": "USDC",
                  "value": "1.00"
                },
                "kind": "network_fee"
              }
            ],
            "total": {
              "currency": "USDC",
              "value": "1.00"
            }
          },
          "fill_rate": null,
          "occurred_at": "2026-05-01T10:00:00Z",
          "operation_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
          "principal_amount": {
            "currency": "USDC",
            "value": "250.00"
          },
          "scope_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
          "status": "settled"
        },
        "event_type": "operations.withdrawal.settled.v1",
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "metadata": null,
        "occurred_at": "2026-05-01T10:00:00Z",
        "partition_key": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "published_at": "2026-05-01T10:00:00Z",
        "resource": "event",
        "schema_version": 1,
        "scope_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "subject_attribution": {
          "actor": null,
          "approved_by": null,
          "authenticated_principal": {
            "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
            "kind": "user",
            "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
          },
          "enterprise_binding": {
            "tenant_type": "enterprise",
            "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
          },
          "federation": null,
          "identity_source": "platform-managed",
          "initiated_by": null,
          "subject": {
            "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
            "kind": "user",
            "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
          }
        },
        "trace_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /events/{event_id}

**Get event**

**Required capability:** `events.read`

**Authentication:** Bearer token required.

**Parameters:**

- `event_id` `string` (path) *(required)*

### events-get Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `aggregate` | object | Yes | No additional fields |
| `data` | object | Yes |  |
| `event_type` | string | Yes | minLength: 1 |
| `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)$` |
| `metadata` | object or null | Yes |  |
| `occurred_at` | string or string | Yes |  |
| `partition_key` | string | Yes | minLength: 1 |
| `published_at` | string or string | Yes |  |
| `resource` | "event" | Yes |  |
| `schema_version` | integer | Yes | maximum: 9007199254740991; exclusiveMinimum: 0 |
| `scope_ref` | string or null | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `trace_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.

##### application/json body.aggregate

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `type` | string | Yes | minLength: 1 |
| `id` | string | Yes | minLength: 1 |

Additional fields are not accepted.

##### application/json body.metadata

At least one alternative must match.

###### application/json body.metadata: alternative 1

Type: `object`. 

###### application/json body.metadata: alternative 2

Type: `null`. 

##### application/json body.occurred_at

At least one alternative must match.

###### application/json body.occurred_at: alternative 1

Type: `string`. 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))$`

###### application/json body.occurred_at: alternative 2

Type: `string`. format: date-time

##### application/json body.published_at

At least one alternative must match.

###### application/json body.published_at: alternative 1

Type: `string`. 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))$`

###### application/json body.published_at: alternative 2

Type: `string`. format: date-time

##### application/json body.scope_ref

At least one alternative must match.

###### application/json body.scope_ref: alternative 1

Type: `string`. pattern: `^(enterprises|clients|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})$`

###### application/json body.scope_ref: alternative 2

Type: `null`. 

##### application/json body.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.federation

At least one alternative must match.

###### application/json body.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject: alternative 2

Type: `null`.


### events-get 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.


### events-get Response 401 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.


### events-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#events-get-response-401-schema).


### events-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#events-get-response-401-schema).


### events-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#events-get-response-401-schema).


### events-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#events-get-response-400-schema).


### events-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#events-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "aggregate": {
      "type": "withdrawal",
      "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
    },
    "data": {
      "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "failure_reason": null,
      "family": "withdrawal",
      "fee_summary": {
        "components": [
          {
            "amount": {
              "currency": "USDC",
              "value": "1.00"
            },
            "kind": "network_fee"
          }
        ],
        "total": {
          "currency": "USDC",
          "value": "1.00"
        }
      },
      "fill_rate": null,
      "occurred_at": "2026-05-01T10:00:00Z",
      "operation_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "principal_amount": {
        "currency": "USDC",
        "value": "250.00"
      },
      "scope_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "status": "settled"
    },
    "event_type": "operations.withdrawal.settled.v1",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "metadata": null,
    "occurred_at": "2026-05-01T10:00:00Z",
    "partition_key": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "published_at": "2026-05-01T10:00:00Z",
    "resource": "event",
    "schema_version": 1,
    "scope_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "subject_attribution": {
      "actor": null,
      "approved_by": null,
      "authenticated_principal": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "enterprise_binding": {
        "tenant_type": "enterprise",
        "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "federation": null,
      "identity_source": "platform-managed",
      "initiated_by": null,
      "subject": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      }
    },
    "trace_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /events/{event_id}/replay

**Replay event to webhook subscriptions**

Schedules webhook deliveries for a stored event. Omit `subscription_ids` to use matching subscriptions; tenant-paused subscriptions are excluded, while deliveries for paused platform-managed subscriptions are held until reactivation. An existing pending or retrying series is reused; a terminal series can produce a new delivery. Unknown, inactive or out-of-scope explicit `subscription_ids` are ignored; compare the returned `targeted_subscription_ids` with the requested list. A named target that cannot receive the event class returns 400 invalid_request with data.reason=event_type_not_subscribable; for public events, a tenant-created target can be selected even when its ordinary event filter does not match. `targeted_subscription_ids` is null when no explicit list was supplied.

**Required capability:** `events.read`, `webhooks.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `event_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `subscription_ids` | string[] | No |  |

Additional fields are not accepted.

#### Request body schema.subscription_ids

Type: `string[]`. 

##### Request body schema.subscription_ids item

Type: `string`. 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)$`

**Request example:**

```json
{
  "subscription_ids": [
    "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
  ]
}
```

### events-replay Response 202 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `accepted` | true | Yes |  |
| `replayed_event_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)$` |
| `targeted_subscription_ids` | string[] or null | Yes |  |

Additional fields are not accepted.

##### application/json body.targeted_subscription_ids

At least one alternative must match.

###### application/json body.targeted_subscription_ids: alternative 1

Type: `string[]`. 

###### application/json body.targeted_subscription_ids: alternative 1 item

Type: `string`. 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)$`

###### application/json body.targeted_subscription_ids: alternative 2

Type: `null`.


### events-replay 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.


### events-replay Response 401 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.


### events-replay Response 403 schema

Content type: `application/json`.

See [response 401 schema](#events-replay-response-401-schema).


### events-replay Response 404 schema

Content type: `application/json`.

See [response 401 schema](#events-replay-response-401-schema).


### events-replay Response 409 schema

Content type: `application/json`.

See [response 401 schema](#events-replay-response-401-schema).


### events-replay Response 500 schema

Content type: `application/json`.

See [response 401 schema](#events-replay-response-401-schema).


### events-replay Response 502 schema

Content type: `application/json`.

See [response 400 schema](#events-replay-response-400-schema).


### events-replay Response 503 schema

Content type: `application/json`.

See [response 400 schema](#events-replay-response-400-schema).


**Responses:**

- `202` — Request accepted for asynchronous processing. Follow the resource identifiers returned by this operation to observe progress.

  ```json
  {
    "accepted": true,
    "replayed_event_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "targeted_subscription_ids": [
      "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
    ]
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /events/types

**List webhook event types**

Returns the canonical public webhook event catalog accepted by event filters and webhook subscriptions.

**Required capability:** `events.read`

**Authentication:** Bearer token required.

### events-types Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `domain` | string | Yes | minLength: 1 |
| `event_type` | "tenant.enterprise.admission_reviewed.v1" / "tenant.enterprise.admitted.v1" / "tenant.enterprise.activated.v1" / "tenant.enterprise.updated.v1" / "tenant.enterprise.suspended.v1" / "tenant.enterprise.reactivated.v1" / "tenant.enterprise.closed.v1" / "tenant.enterprise.terminated.v1" / "tenant.platform_operator.admitted.v1" / "tenant.platform_operator.restricted.v1" / "tenant.platform_operator.reactivated.v1" / "tenant.platform_operator.offboarded.v1" / "tenant.platform_operator.catalog_updated.v1" / "tenant.master_account.created.v1" / "tenant.master_account.suspended.v1" / "tenant.master_account.closed.v1" / "tenant.client.created.v1" / "tenant.client.updated.v1" / "tenant.client.suspended.v1" / "tenant.client.reactivated.v1" / "tenant.client.closed.v1" / "tenant.client_account.created.v1" / "tenant.client_account.suspended.v1" / "tenant.client_account.reactivated.v1" / "tenant.client_account.closed.v1" / "ledger.transaction.posted.v1" / "operations.withdrawal.requested.v1" / "operations.withdrawal.admissible.v1" / "operations.withdrawal.executing.v1" / "operations.withdrawal.pending_approval.v1" / "operations.withdrawal.pending_compliance.v1" / "operations.withdrawal.approved.v1" / "operations.withdrawal.settled.v1" / "operations.withdrawal.failed.v1" / "operations.withdrawal.cancelled.v1" / "operations.conversion.requested.v1" / "operations.conversion.admissible.v1" / "operations.conversion.pending_approval.v1" / "operations.conversion.pending_compliance.v1" / "operations.conversion.approved.v1" / "operations.conversion.settled.v1" / "operations.conversion.failed.v1" / "operations.conversion.cancelled.v1" / "operations.external_settlement_conversion.pending_compliance.v1" / "operations.internal_transfer.requested.v1" / "operations.internal_transfer.admissible.v1" / "operations.internal_transfer.pending_approval.v1" / "operations.internal_transfer.pending_compliance.v1" / "operations.internal_transfer.approved.v1" / "operations.internal_transfer.settled.v1" / "operations.internal_transfer.failed.v1" / "operations.internal_transfer.cancelled.v1" / "operations.on_ramp.requested.v1" / "operations.on_ramp.admissible.v1" / "operations.on_ramp.pending_approval.v1" / "operations.on_ramp.pending_compliance.v1" / "operations.on_ramp.approved.v1" / "operations.on_ramp.settled.v1" / "operations.on_ramp.failed.v1" / "operations.on_ramp.cancelled.v1" / "operations.off_ramp.requested.v1" / "operations.off_ramp.admissible.v1" / "operations.off_ramp.pending_approval.v1" / "operations.off_ramp.pending_compliance.v1" / "operations.off_ramp.approved.v1" / "operations.off_ramp.settled.v1" / "operations.off_ramp.failed.v1" / "operations.off_ramp.cancelled.v1" / "operations.deposit.requested.v1" / "operations.deposit.admissible.v1" / "operations.deposit.pending_approval.v1" / "operations.deposit.pending_admission.v1" / "operations.deposit.pending_compliance.v1" / "operations.deposit.approved.v1" / "operations.deposit.settled.v1" / "operations.deposit.failed.v1" / "operations.deposit.cancelled.v1" / "rails.deposit.detected.v1" / "rails.dispatch.acknowledged.v1" / "rails.dispatch.rejected.v1" / "rails.settlement.confirmed.v1" / "kyc.verification.reviewed.v1" / "loan.originated.v1" / "loan.origination_failed.v1" / "loan.margin_called.v1" / "loan.margin_call_cleared.v1" / "loan.liquidation_halted.v1" / "loan.liquidated.v1" / "loan.repaid.v1" / "loan.extended.v1" / "loan.closed.v1" / "loan.force_closed.v1" / "loan.reconciliation_discrepancy.v1" | Yes |  |
| `resource` | string | Yes | minLength: 1 |
| `schema_version` | 1 | Yes |  |
| `source_package` | string | Yes | minLength: 1 |
| `verb` | string | Yes | minLength: 1 |

Additional fields are not accepted.


### events-types 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.


### events-types Response 401 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.


### events-types Response 403 schema

Content type: `application/json`.

See [response 401 schema](#events-types-response-401-schema).


### events-types Response 500 schema

Content type: `application/json`.

See [response 401 schema](#events-types-response-401-schema).


### events-types Response 502 schema

Content type: `application/json`.

See [response 400 schema](#events-types-response-400-schema).


### events-types Response 503 schema

Content type: `application/json`.

See [response 400 schema](#events-types-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "domain": "operations",
        "event_type": "operations.withdrawal.settled.v1",
        "resource": "withdrawal",
        "schema_version": 1,
        "source_package": "@yh/operation-flow-contracts",
        "verb": "settled"
      }
    ]
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Withdrawals

### GET /withdrawals

**List withdrawals**

**Required capability:** `withdrawals.read`

**Authentication:** Bearer token required.

**Parameters:**

- `account_ref` `string` (query)
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### withdrawals-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| 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})$` |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `created_at` | string or string | Yes |  |
| `destination_id` | string or null | Yes |  |
| `dispatch_attempt_id` | string or null | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "withdrawal" | Yes |  |
| `family_flow_id` | string or null | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fee_transaction_ids` | string[] or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `hold_id` | string or null | Yes |  |
| `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)$` |
| `leg_attempt_id` | string or null | Yes |  |
| `network` | string or null | Yes |  |
| `principal_amount` | object | Yes | No additional fields |
| `principal_transaction_id` | string or null | Yes |  |
| `rail` | string or null | Yes |  |
| `rail_class` | "fiat" / "crypto" or null | Yes |  |
| `release_transaction_id` | string or null | Yes |  |
| `settled_at` | string or string or null | Yes |  |
| `settlement_evidence` | object or object or null | Yes |  |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `updated_at` | string or string | Yes |  |
| `withdrawal_attempt_id` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.approval_ref

At least one alternative must match.

###### application/json body.items item.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body.items item.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body.items item.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body.items item.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body.items item.approval_ref: alternative 2

Type: `null`. 

###### application/json body.items item.compliance_assessment_ref

At least one alternative must match.

###### application/json body.items item.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body.items item.compliance_assessment_ref: alternative 2

Type: `null`. 

###### application/json body.items item.created_at

At least one alternative must match.

###### application/json body.items item.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.created_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.destination_id

At least one alternative must match.

###### application/json body.items item.destination_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item.destination_id: alternative 2

Type: `null`. 

###### application/json body.items item.dispatch_attempt_id

At least one alternative must match.

###### application/json body.items item.dispatch_attempt_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item.dispatch_attempt_id: alternative 2

Type: `null`. 

###### application/json body.items item.failure_reason

At least one alternative must match.

###### application/json body.items item.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.items item.failure_reason: alternative 2

Type: `null`. 

###### application/json body.items item.family_flow_id

At least one alternative must match.

###### application/json body.items item.family_flow_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item.family_flow_id: alternative 2

Type: `null`. 

###### application/json body.items item.fee_summary

At least one alternative must match.

###### application/json body.items item.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.items item.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body.items item.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.fee_summary: alternative 1.components item.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.

###### application/json body.items item.fee_summary: alternative 1.total

| 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.

###### application/json body.items item.fee_summary: alternative 2

Type: `null`. 

###### application/json body.items item.fee_transaction_ids

At least one alternative must match.

###### application/json body.items item.fee_transaction_ids: alternative 1

Type: `string[]`. 

###### application/json body.items item.fee_transaction_ids: alternative 1 item

Type: `string`. 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)$`

###### application/json body.items item.fee_transaction_ids: alternative 2

Type: `null`. 

###### application/json body.items item.fill_rate

At least one alternative must match.

###### application/json body.items item.fill_rate: alternative 1

Type: `string`. 

###### application/json body.items item.fill_rate: alternative 2

Type: `null`. 

###### application/json body.items item.hold_id

At least one alternative must match.

###### application/json body.items item.hold_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item.hold_id: alternative 2

Type: `null`. 

###### application/json body.items item.leg_attempt_id

At least one alternative must match.

###### application/json body.items item.leg_attempt_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item.leg_attempt_id: alternative 2

Type: `null`. 

###### application/json body.items item.network

At least one alternative must match.

###### application/json body.items item.network: alternative 1

Type: `string`. minLength: 1

###### application/json body.items item.network: alternative 2

Type: `null`. 

###### application/json body.items item.principal_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.

###### application/json body.items item.principal_transaction_id

At least one alternative must match.

###### application/json body.items item.principal_transaction_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item.principal_transaction_id: alternative 2

Type: `null`. 

###### application/json body.items item.rail

At least one alternative must match.

###### application/json body.items item.rail: alternative 1

Type: `string`. minLength: 1

###### application/json body.items item.rail: alternative 2

Type: `null`. 

###### application/json body.items item.rail_class

At least one alternative must match.

###### application/json body.items item.rail_class: alternative 1

Type: `"fiat" / "crypto"`. 

###### application/json body.items item.rail_class: alternative 2

Type: `null`. 

###### application/json body.items item.release_transaction_id

At least one alternative must match.

###### application/json body.items item.release_transaction_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item.release_transaction_id: alternative 2

Type: `null`. 

###### application/json body.items item.settled_at

At least one alternative must match.

###### application/json body.items item.settled_at: alternative 1

At least one alternative must match.

###### application/json body.items item.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.settled_at: alternative 2

Type: `null`. 

###### application/json body.items item.settlement_evidence

At least one alternative must match.

###### application/json body.items item.settlement_evidence: alternative 1

Exactly one alternative must match.

###### application/json body.items item.settlement_evidence: alternative 1: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `block_number` | integer or null | Yes |  |
| `confirmations` | integer or null | Yes |  |
| `finalized_at` | string or string or null | Yes |  |
| `kind` | "blockchain_transaction" | Yes |  |
| `network` | string | Yes | minLength: 1 |
| `transaction_hash` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.items item.settlement_evidence: alternative 1: alternative 1.block_number

At least one alternative must match.

###### application/json body.items item.settlement_evidence: alternative 1: alternative 1.block_number: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### application/json body.items item.settlement_evidence: alternative 1: alternative 1.block_number: alternative 2

Type: `null`. 

###### application/json body.items item.settlement_evidence: alternative 1: alternative 1.confirmations

At least one alternative must match.

###### application/json body.items item.settlement_evidence: alternative 1: alternative 1.confirmations: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### application/json body.items item.settlement_evidence: alternative 1: alternative 1.confirmations: alternative 2

Type: `null`. 

###### application/json body.items item.settlement_evidence: alternative 1: alternative 1.finalized_at

At least one alternative must match.

###### application/json body.items item.settlement_evidence: alternative 1: alternative 1.finalized_at: alternative 1

At least one alternative must match.

###### application/json body.items item.settlement_evidence: alternative 1: alternative 1.finalized_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.settlement_evidence: alternative 1: alternative 1.finalized_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.settlement_evidence: alternative 1: alternative 1.finalized_at: alternative 2

Type: `null`. 

###### application/json body.items item.settlement_evidence: alternative 1: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `fiat_rail` | string | Yes | minLength: 1 |
| `kind` | "bank_transfer" | Yes |  |
| `rail_reference` | string or null | Yes |  |
| `settled_at` | string or string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.settlement_evidence: alternative 1: alternative 2.rail_reference

At least one alternative must match.

###### application/json body.items item.settlement_evidence: alternative 1: alternative 2.rail_reference: alternative 1

Type: `string`. minLength: 1

###### application/json body.items item.settlement_evidence: alternative 1: alternative 2.rail_reference: alternative 2

Type: `null`. 

###### application/json body.items item.settlement_evidence: alternative 1: alternative 2.settled_at

At least one alternative must match.

###### application/json body.items item.settlement_evidence: alternative 1: alternative 2.settled_at: alternative 1

At least one alternative must match.

###### application/json body.items item.settlement_evidence: alternative 1: alternative 2.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.settlement_evidence: alternative 1: alternative 2.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.settlement_evidence: alternative 1: alternative 2.settled_at: alternative 2

Type: `null`. 

###### application/json body.items item.settlement_evidence: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.actor

At least one alternative must match.

###### application/json body.items item.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.approved_by

At least one alternative must match.

###### application/json body.items item.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.items item.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.items item.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.federation

At least one alternative must match.

###### application/json body.items item.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body.items item.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.subject

At least one alternative must match.

###### application/json body.items item.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.subject: alternative 2

Type: `null`. 

###### application/json body.items item.updated_at

At least one alternative must match.

###### application/json body.items item.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.updated_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.withdrawal_attempt_id

At least one alternative must match.

###### application/json body.items item.withdrawal_attempt_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item.withdrawal_attempt_id: alternative 2

Type: `null`. 

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. 

###### application/json body.next_page_token: alternative 2

Type: `null`.


### withdrawals-list 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.


### withdrawals-list Response 401 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.


### withdrawals-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#withdrawals-list-response-401-schema).


### withdrawals-list Response 404 schema

Content type: `application/json`.

See [response 401 schema](#withdrawals-list-response-401-schema).


### withdrawals-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#withdrawals-list-response-401-schema).


### withdrawals-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#withdrawals-list-response-400-schema).


### withdrawals-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#withdrawals-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "approval_ref": null,
        "created_at": "2026-05-01T10:00:00Z",
        "destination_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "dispatch_attempt_id": null,
        "failure_reason": null,
        "family": "withdrawal",
        "family_flow_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "fee_summary": {
          "components": [
            {
              "amount": {
                "currency": "USDC",
                "value": "1.00"
              },
              "kind": "network_fee"
            }
          ],
          "total": {
            "currency": "USDC",
            "value": "1.00"
          }
        },
        "fee_transaction_ids": [],
        "fill_rate": null,
        "hold_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "leg_attempt_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "network": "ethereum",
        "principal_amount": {
          "currency": "USDC",
          "value": "250.00"
        },
        "principal_transaction_id": null,
        "rail": "ethereum",
        "rail_class": "crypto",
        "release_transaction_id": null,
        "settled_at": null,
        "settlement_evidence": null,
        "status": "executing",
        "subject_attribution": {
          "actor": null,
          "approved_by": null,
          "authenticated_principal": {
            "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
            "kind": "user",
            "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
          },
          "enterprise_binding": {
            "tenant_type": "enterprise",
            "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
          },
          "federation": null,
          "identity_source": "platform-managed",
          "initiated_by": null,
          "subject": {
            "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
            "kind": "user",
            "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
          }
        },
        "updated_at": "2026-05-01T10:00:00Z",
        "withdrawal_attempt_id": null
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /withdrawals

**Create withdrawal**

Creates a withdrawal operation. For crypto requests, bind either a stored withdrawal destination (`destination_id`) or a one-time inline `destination` (`{address, memo}` plus `network`) — exactly one crypto destination path must be present. For fiat requests, bind a stored fiat withdrawal destination by its `withdrawal_destination_id`, resolved within the supplied `account_ref` scope; the canonical bank routing and the authoritative owner topology are sourced from the stored destination, never from the request body. Both rails are subject to operation admission checks; fiat dispatch also depends on the availability and runtime readiness of the selected fiat rail. A fiat `amount` with more fractional digits than the catalog scale of its currency is refused with `400 invalid_request` and `data.reason = amount_scale_exceeded` before anything is held; trailing zeros do not count (`100.000` is `100`), and a currency the catalog has no scale for is not checked. Successful responses return the operation snapshot — for an immediately admitted withdrawal the response may carry `status = "executing"` once operation-flow has written that state. Idempotent on `Idempotency-Key` or `client_idempotency_key`. Human callers must obtain a step-up confirmation via `POST /action-tokens` and submit it in the `X-Action-Token` header; service principals are exempt.

**Required capability:** `withdrawals.create`

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.
- `X-Action-Token` `string` (header) — Single-use step-up confirmation token bound to the server-canonical command for this request. Required when the effective subject is a human user. Callers without a human subject skip only this confirmation check and still pass normal authentication and capability guards. Obtain the token through `POST /action-tokens`, then submit it with the guarded request. Structured commands are supported for withdrawal, conversion, and external-settlement conversion creation; the issue endpoint also accepts `command_digest`. Missing or invalid human-confirmation tokens produce `400` with `code` in {`action_token_required`, `action_token_rejected`}; an unreachable approval service produces `502 action_token_validation_failed`.

**Request body** (`application/json`):

### Request body schema

Exactly one alternative must match.

#### Request body schema: 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 |
| `client_idempotency_key` | string | No | minLength: 1 |
| `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" | Yes |  |

Additional fields are not accepted.

##### Request body schema: 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.destination

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `address` | string | Yes | minLength: 1; maxLength: 256 |
| `memo` | string or null | Yes |  |

Additional fields are not accepted.

###### Request body schema: alternative 1.destination.memo

At least one alternative must match.

###### Request body schema: alternative 1.destination.memo: alternative 1

Type: `string`. 

###### Request body schema: alternative 1.destination.memo: alternative 2

Type: `null`. 

#### Request body schema: 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 |
| `client_idempotency_key` | string | No | minLength: 1 |
| `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 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 example:**

```json
{
  "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "amount": {
    "currency": "EUR",
    "value": "100.00"
  },
  "rail": "fiat",
  "withdrawal_destination_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}
```

### withdrawals-create Response 202 schema

Content type: `application/json`.

#### application/json body

| 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})$` |
| `admission_hold_reason` | "CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED" or null | No |  |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `created_at` | string or string | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "deposit" / "withdrawal" / "conversion" / "external_settlement_conversion" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension" | Yes |  |
| `family_params` | object | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `principal_amount` | object | Yes | No additional fields |
| `settled_at` | string or string or null | Yes |  |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

##### application/json body.admission_hold_reason

At least one alternative must match.

###### application/json body.admission_hold_reason: alternative 1

Type: `"CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED"`. 

###### application/json body.admission_hold_reason: alternative 2

Type: `null`. 

##### application/json body.approval_ref

At least one alternative must match.

###### application/json body.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body.approval_ref: alternative 2

Type: `null`. 

##### application/json body.compliance_assessment_ref

At least one alternative must match.

###### application/json body.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body.compliance_assessment_ref: alternative 2

Type: `null`. 

##### application/json body.created_at

At least one alternative must match.

###### application/json body.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.created_at: alternative 2

Type: `string`. format: date-time

##### application/json body.failure_reason

At least one alternative must match.

###### application/json body.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.failure_reason: alternative 2

Type: `null`. 

##### application/json body.fee_summary

At least one alternative must match.

###### application/json body.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body.fee_summary: alternative 1.components item.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.

###### application/json body.fee_summary: alternative 1.total

| 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.

###### application/json body.fee_summary: alternative 2

Type: `null`. 

##### application/json body.fill_rate

At least one alternative must match.

###### application/json body.fill_rate: alternative 1

Type: `string`. 

###### application/json body.fill_rate: alternative 2

Type: `null`. 

##### application/json body.principal_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.

##### application/json body.settled_at

At least one alternative must match.

###### application/json body.settled_at: alternative 1

At least one alternative must match.

###### application/json body.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.settled_at: alternative 2

Type: `null`. 

##### application/json body.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.federation

At least one alternative must match.

###### application/json body.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject: alternative 2

Type: `null`. 

##### application/json body.updated_at

At least one alternative must match.

###### application/json body.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.updated_at: alternative 2

Type: `string`. format: date-time


### withdrawals-create 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 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.


### withdrawals-create Response 401 schema

Content type: `application/json`.

See [response 400 schema](#withdrawals-create-response-400-schema).


### withdrawals-create Response 403 schema

Content type: `application/json`.

See [response 400 schema](#withdrawals-create-response-400-schema).


### withdrawals-create Response 409 schema

Content type: `application/json`.

See [response 400 schema](#withdrawals-create-response-400-schema).


### withdrawals-create Response 422 schema

Content type: `application/json`.

See [response 400 schema](#withdrawals-create-response-400-schema).


### withdrawals-create Response 500 schema

Content type: `application/json`.

See [response 400 schema](#withdrawals-create-response-400-schema).


### withdrawals-create Response 502 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.


### withdrawals-create Response 503 schema

Content type: `application/json`.

See [response 502 schema](#withdrawals-create-response-502-schema).


**Responses:**

- `202` — Request accepted for asynchronous processing. Follow the resource identifiers returned by this operation to observe progress.

  ```json
  {
    "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "approval_ref": null,
    "created_at": "2026-05-01T10:00:00Z",
    "failure_reason": null,
    "family": "withdrawal",
    "family_params": {},
    "fee_summary": {
      "components": [
        {
          "amount": {
            "currency": "USDC",
            "value": "1.00"
          },
          "kind": "network_fee"
        }
      ],
      "total": {
        "currency": "USDC",
        "value": "1.00"
      }
    },
    "fill_rate": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "principal_amount": {
      "currency": "USDC",
      "value": "250.00"
    },
    "settled_at": null,
    "status": "executing",
    "subject_attribution": {
      "actor": null,
      "approved_by": null,
      "authenticated_principal": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "enterprise_binding": {
        "tenant_type": "enterprise",
        "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "federation": null,
      "identity_source": "platform-managed",
      "initiated_by": null,
      "subject": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      }
    },
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Step-up confirmation failed for a money-movement operation. `code` is one of: `action_token_required` (X-Action-Token header missing), `action_token_rejected` (token is unknown, expired, already consumed, or its server-canonical command binding does not match the current request). Obtain a fresh token via `POST /action-tokens` and retry. Structured issuance accepts `withdrawal.create`, `conversion.create`, and `external_settlement_conversion.create`. The issue endpoint also accepts `command_digest`. Human confirmation applies to the effective user subject; callers without a human subject skip this confirmation check.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `422` — The request cannot be processed under the resource or route contract. Depending on the endpoint, code can be not_admissible or unsupported_currency; inspect the documented code and data.reason.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /withdrawals/{withdrawal_id}

**Get withdrawal**

**Required capability:** `withdrawals.read`

**Authentication:** Bearer token required.

**Parameters:**

- `withdrawal_id` `string` (path) *(required)*

### withdrawals-get Response 200 schema

Content type: `application/json`.

#### application/json body

| 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})$` |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `created_at` | string or string | Yes |  |
| `destination_id` | string or null | Yes |  |
| `dispatch_attempt_id` | string or null | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "withdrawal" | Yes |  |
| `family_flow_id` | string or null | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fee_transaction_ids` | string[] or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `hold_id` | string or null | Yes |  |
| `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)$` |
| `leg_attempt_id` | string or null | Yes |  |
| `network` | string or null | Yes |  |
| `principal_amount` | object | Yes | No additional fields |
| `principal_transaction_id` | string or null | Yes |  |
| `rail` | string or null | Yes |  |
| `rail_class` | "fiat" / "crypto" or null | Yes |  |
| `release_transaction_id` | string or null | Yes |  |
| `settled_at` | string or string or null | Yes |  |
| `settlement_evidence` | object or object or null | Yes |  |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `updated_at` | string or string | Yes |  |
| `withdrawal_attempt_id` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.approval_ref

At least one alternative must match.

###### application/json body.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body.approval_ref: alternative 2

Type: `null`. 

##### application/json body.compliance_assessment_ref

At least one alternative must match.

###### application/json body.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body.compliance_assessment_ref: alternative 2

Type: `null`. 

##### application/json body.created_at

At least one alternative must match.

###### application/json body.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.created_at: alternative 2

Type: `string`. format: date-time

##### application/json body.destination_id

At least one alternative must match.

###### application/json body.destination_id: alternative 1

Type: `string`. 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)$`

###### application/json body.destination_id: alternative 2

Type: `null`. 

##### application/json body.dispatch_attempt_id

At least one alternative must match.

###### application/json body.dispatch_attempt_id: alternative 1

Type: `string`. 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)$`

###### application/json body.dispatch_attempt_id: alternative 2

Type: `null`. 

##### application/json body.failure_reason

At least one alternative must match.

###### application/json body.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.failure_reason: alternative 2

Type: `null`. 

##### application/json body.family_flow_id

At least one alternative must match.

###### application/json body.family_flow_id: alternative 1

Type: `string`. 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)$`

###### application/json body.family_flow_id: alternative 2

Type: `null`. 

##### application/json body.fee_summary

At least one alternative must match.

###### application/json body.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body.fee_summary: alternative 1.components item.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.

###### application/json body.fee_summary: alternative 1.total

| 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.

###### application/json body.fee_summary: alternative 2

Type: `null`. 

##### application/json body.fee_transaction_ids

At least one alternative must match.

###### application/json body.fee_transaction_ids: alternative 1

Type: `string[]`. 

###### application/json body.fee_transaction_ids: alternative 1 item

Type: `string`. 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)$`

###### application/json body.fee_transaction_ids: alternative 2

Type: `null`. 

##### application/json body.fill_rate

At least one alternative must match.

###### application/json body.fill_rate: alternative 1

Type: `string`. 

###### application/json body.fill_rate: alternative 2

Type: `null`. 

##### application/json body.hold_id

At least one alternative must match.

###### application/json body.hold_id: alternative 1

Type: `string`. 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)$`

###### application/json body.hold_id: alternative 2

Type: `null`. 

##### application/json body.leg_attempt_id

At least one alternative must match.

###### application/json body.leg_attempt_id: alternative 1

Type: `string`. 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)$`

###### application/json body.leg_attempt_id: alternative 2

Type: `null`. 

##### application/json body.network

At least one alternative must match.

###### application/json body.network: alternative 1

Type: `string`. minLength: 1

###### application/json body.network: alternative 2

Type: `null`. 

##### application/json body.principal_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.

##### application/json body.principal_transaction_id

At least one alternative must match.

###### application/json body.principal_transaction_id: alternative 1

Type: `string`. 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)$`

###### application/json body.principal_transaction_id: alternative 2

Type: `null`. 

##### application/json body.rail

At least one alternative must match.

###### application/json body.rail: alternative 1

Type: `string`. minLength: 1

###### application/json body.rail: alternative 2

Type: `null`. 

##### application/json body.rail_class

At least one alternative must match.

###### application/json body.rail_class: alternative 1

Type: `"fiat" / "crypto"`. 

###### application/json body.rail_class: alternative 2

Type: `null`. 

##### application/json body.release_transaction_id

At least one alternative must match.

###### application/json body.release_transaction_id: alternative 1

Type: `string`. 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)$`

###### application/json body.release_transaction_id: alternative 2

Type: `null`. 

##### application/json body.settled_at

At least one alternative must match.

###### application/json body.settled_at: alternative 1

At least one alternative must match.

###### application/json body.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.settled_at: alternative 2

Type: `null`. 

##### application/json body.settlement_evidence

At least one alternative must match.

###### application/json body.settlement_evidence: alternative 1

Exactly one alternative must match.

###### application/json body.settlement_evidence: alternative 1: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `block_number` | integer or null | Yes |  |
| `confirmations` | integer or null | Yes |  |
| `finalized_at` | string or string or null | Yes |  |
| `kind` | "blockchain_transaction" | Yes |  |
| `network` | string | Yes | minLength: 1 |
| `transaction_hash` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.settlement_evidence: alternative 1: alternative 1.block_number

At least one alternative must match.

###### application/json body.settlement_evidence: alternative 1: alternative 1.block_number: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### application/json body.settlement_evidence: alternative 1: alternative 1.block_number: alternative 2

Type: `null`. 

###### application/json body.settlement_evidence: alternative 1: alternative 1.confirmations

At least one alternative must match.

###### application/json body.settlement_evidence: alternative 1: alternative 1.confirmations: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### application/json body.settlement_evidence: alternative 1: alternative 1.confirmations: alternative 2

Type: `null`. 

###### application/json body.settlement_evidence: alternative 1: alternative 1.finalized_at

At least one alternative must match.

###### application/json body.settlement_evidence: alternative 1: alternative 1.finalized_at: alternative 1

At least one alternative must match.

###### application/json body.settlement_evidence: alternative 1: alternative 1.finalized_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.settlement_evidence: alternative 1: alternative 1.finalized_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.settlement_evidence: alternative 1: alternative 1.finalized_at: alternative 2

Type: `null`. 

###### application/json body.settlement_evidence: alternative 1: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `fiat_rail` | string | Yes | minLength: 1 |
| `kind` | "bank_transfer" | Yes |  |
| `rail_reference` | string or null | Yes |  |
| `settled_at` | string or string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.settlement_evidence: alternative 1: alternative 2.rail_reference

At least one alternative must match.

###### application/json body.settlement_evidence: alternative 1: alternative 2.rail_reference: alternative 1

Type: `string`. minLength: 1

###### application/json body.settlement_evidence: alternative 1: alternative 2.rail_reference: alternative 2

Type: `null`. 

###### application/json body.settlement_evidence: alternative 1: alternative 2.settled_at

At least one alternative must match.

###### application/json body.settlement_evidence: alternative 1: alternative 2.settled_at: alternative 1

At least one alternative must match.

###### application/json body.settlement_evidence: alternative 1: alternative 2.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.settlement_evidence: alternative 1: alternative 2.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.settlement_evidence: alternative 1: alternative 2.settled_at: alternative 2

Type: `null`. 

###### application/json body.settlement_evidence: alternative 2

Type: `null`. 

##### application/json body.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.federation

At least one alternative must match.

###### application/json body.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject: alternative 2

Type: `null`. 

##### application/json body.updated_at

At least one alternative must match.

###### application/json body.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.updated_at: alternative 2

Type: `string`. format: date-time

##### application/json body.withdrawal_attempt_id

At least one alternative must match.

###### application/json body.withdrawal_attempt_id: alternative 1

Type: `string`. 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)$`

###### application/json body.withdrawal_attempt_id: alternative 2

Type: `null`.


### withdrawals-get 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.


### withdrawals-get Response 401 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.


### withdrawals-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#withdrawals-get-response-401-schema).


### withdrawals-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#withdrawals-get-response-401-schema).


### withdrawals-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#withdrawals-get-response-401-schema).


### withdrawals-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#withdrawals-get-response-400-schema).


### withdrawals-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#withdrawals-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "approval_ref": null,
    "created_at": "2026-05-01T10:00:00Z",
    "destination_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "dispatch_attempt_id": null,
    "failure_reason": null,
    "family": "withdrawal",
    "family_flow_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "fee_summary": {
      "components": [
        {
          "amount": {
            "currency": "USDC",
            "value": "1.00"
          },
          "kind": "network_fee"
        }
      ],
      "total": {
        "currency": "USDC",
        "value": "1.00"
      }
    },
    "fee_transaction_ids": [],
    "fill_rate": null,
    "hold_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "leg_attempt_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "network": "ethereum",
    "principal_amount": {
      "currency": "USDC",
      "value": "250.00"
    },
    "principal_transaction_id": null,
    "rail": "ethereum",
    "rail_class": "crypto",
    "release_transaction_id": null,
    "settled_at": null,
    "settlement_evidence": null,
    "status": "executing",
    "subject_attribution": {
      "actor": null,
      "approved_by": null,
      "authenticated_principal": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "enterprise_binding": {
        "tenant_type": "enterprise",
        "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "federation": null,
      "identity_source": "platform-managed",
      "initiated_by": null,
      "subject": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      }
    },
    "updated_at": "2026-05-01T10:00:00Z",
    "withdrawal_attempt_id": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /withdrawals/{withdrawal_id}/cancel

**Cancel withdrawal**

Cancels a withdrawal while it is waiting for approval or compliance, before dispatch. Returns the refreshed operation with status `cancelled`. A withdrawal that has already started execution cannot be cancelled and returns `409 state_conflict` with `data.reason = operation_not_cancellable`.

**Required capability:** `withdrawals.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `withdrawal_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

### withdrawals-cancel Response 200 schema

Content type: `application/json`.

#### application/json body

| 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})$` |
| `admission_hold_reason` | "CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED" or null | No |  |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `created_at` | string or string | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "deposit" / "withdrawal" / "conversion" / "external_settlement_conversion" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension" | Yes |  |
| `family_params` | object | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `principal_amount` | object | Yes | No additional fields |
| `settled_at` | string or string or null | Yes |  |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

##### application/json body.admission_hold_reason

At least one alternative must match.

###### application/json body.admission_hold_reason: alternative 1

Type: `"CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED"`. 

###### application/json body.admission_hold_reason: alternative 2

Type: `null`. 

##### application/json body.approval_ref

At least one alternative must match.

###### application/json body.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body.approval_ref: alternative 2

Type: `null`. 

##### application/json body.compliance_assessment_ref

At least one alternative must match.

###### application/json body.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body.compliance_assessment_ref: alternative 2

Type: `null`. 

##### application/json body.created_at

At least one alternative must match.

###### application/json body.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.created_at: alternative 2

Type: `string`. format: date-time

##### application/json body.failure_reason

At least one alternative must match.

###### application/json body.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.failure_reason: alternative 2

Type: `null`. 

##### application/json body.fee_summary

At least one alternative must match.

###### application/json body.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body.fee_summary: alternative 1.components item.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.

###### application/json body.fee_summary: alternative 1.total

| 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.

###### application/json body.fee_summary: alternative 2

Type: `null`. 

##### application/json body.fill_rate

At least one alternative must match.

###### application/json body.fill_rate: alternative 1

Type: `string`. 

###### application/json body.fill_rate: alternative 2

Type: `null`. 

##### application/json body.principal_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.

##### application/json body.settled_at

At least one alternative must match.

###### application/json body.settled_at: alternative 1

At least one alternative must match.

###### application/json body.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.settled_at: alternative 2

Type: `null`. 

##### application/json body.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.federation

At least one alternative must match.

###### application/json body.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject: alternative 2

Type: `null`. 

##### application/json body.updated_at

At least one alternative must match.

###### application/json body.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.updated_at: alternative 2

Type: `string`. format: date-time


### withdrawals-cancel 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.


### withdrawals-cancel Response 401 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.


### withdrawals-cancel Response 403 schema

Content type: `application/json`.

See [response 401 schema](#withdrawals-cancel-response-401-schema).


### withdrawals-cancel Response 404 schema

Content type: `application/json`.

See [response 401 schema](#withdrawals-cancel-response-401-schema).


### withdrawals-cancel Response 409 schema

Content type: `application/json`.

See [response 401 schema](#withdrawals-cancel-response-401-schema).


### withdrawals-cancel Response 500 schema

Content type: `application/json`.

See [response 401 schema](#withdrawals-cancel-response-401-schema).


### withdrawals-cancel Response 502 schema

Content type: `application/json`.

See [response 400 schema](#withdrawals-cancel-response-400-schema).


### withdrawals-cancel Response 503 schema

Content type: `application/json`.

See [response 400 schema](#withdrawals-cancel-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "approval_ref": null,
    "created_at": "2026-05-01T10:00:00Z",
    "failure_reason": null,
    "family": "withdrawal",
    "family_params": {},
    "fee_summary": null,
    "fill_rate": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "principal_amount": {
      "currency": "USDC",
      "value": "250.00"
    },
    "settled_at": null,
    "status": "cancelled",
    "subject_attribution": {
      "actor": null,
      "approved_by": null,
      "authenticated_principal": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "enterprise_binding": {
        "tenant_type": "enterprise",
        "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "federation": null,
      "identity_source": "platform-managed",
      "initiated_by": null,
      "subject": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      }
    },
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Withdrawal Destinations

### GET /withdrawal-destinations

**List withdrawal destinations**

Lists withdrawal destinations for the selected rail. Crypto lists require `scope_ref` for the topology-scoped address book. Fiat lists require `account_ref`; the pooled fiat route owner is derived server-side and is not part of the request surface.

**Required capability:** `withdrawal_destinations.read`

**Authentication:** Bearer token required.

**Parameters:**

- `rail_class` `string` (query) *(required)*
- `scope_ref` `string` (query)
- `account_ref` `string` (query)
- `status` `string` (query)
- `asset` `string` (query)
- `currency` `string` (query)
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### withdrawal-destinations-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string or null | No |  |
| `created_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))$` |
| `crypto_routing` | object or null | No |  |
| `fiat_routing` | object or null | No |  |
| `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)$` |
| `label` | string or null | No |  |
| `rail_class` | "fiat" / "crypto" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|platform-operators\|clients)\/([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})$` |
| `status` | "active" / "disabled" / "retired" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

###### application/json body.items item.asset

At least one alternative must match.

###### application/json body.items item.asset: alternative 1

Currency code (ISO-4217 or on-chain ticker)

Type: `string`. pattern: `^[A-Z0-9]{1,16}$`

###### application/json body.items item.asset: alternative 2

Type: `null`. 

###### application/json body.items item.crypto_routing

At least one alternative must match.

###### application/json body.items item.crypto_routing: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `destination` | object | Yes | No additional fields |
| `label` | string or null | Yes |  |
| `network` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.items item.crypto_routing: alternative 1.destination

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `address` | string | Yes | minLength: 1; maxLength: 256 |
| `memo` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.crypto_routing: alternative 1.destination.memo

At least one alternative must match.

###### application/json body.items item.crypto_routing: alternative 1.destination.memo: alternative 1

Type: `string`. 

###### application/json body.items item.crypto_routing: alternative 1.destination.memo: alternative 2

Type: `null`. 

###### application/json body.items item.crypto_routing: alternative 1.label

At least one alternative must match.

###### application/json body.items item.crypto_routing: alternative 1.label: alternative 1

Type: `string`. 

###### application/json body.items item.crypto_routing: alternative 1.label: alternative 2

Type: `null`. 

###### application/json body.items item.crypto_routing: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `bank_coordinates` | object or object | Yes |  |
| `beneficiary_name` | string | Yes | minLength: 1; maxLength: 140 |
| `currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `fiat_rail` | "sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire" | Yes |  |
| `method` | "bank_transfer" | Yes |  |
| `reference_hint` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates

Exactly one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `iban` | string | Yes | minLength: 1; maxLength: 34 |
| `scheme` | "iban" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.region

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_name

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_name: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 1.bic

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 1.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 1.bic: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string | Yes | minLength: 1; maxLength: 64 |
| `account_type` | "checking" / "savings" or null | No | Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept. |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `routing_codes` | object[] | Yes | minItems: 1; maxItems: 16 |
| `scheme` | "local_account" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 2.account_type

Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept.

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 2.account_type: alternative 1

Type: `"checking" / "savings"`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 2.account_type: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.region

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_name

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_name: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 2.bic

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 2.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 2.bic: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 2.routing_codes

Type: `object[]`. minItems: 1; maxItems: 16

###### application/json body.items item.fiat_routing: alternative 1.bank_coordinates: alternative 2.routing_codes item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `type` | string | Yes | minLength: 1; maxLength: 64 |
| `value` | string | Yes | minLength: 1; maxLength: 64 |

Additional fields are not accepted.

###### application/json body.items item.fiat_routing: alternative 1.reference_hint

At least one alternative must match.

###### application/json body.items item.fiat_routing: alternative 1.reference_hint: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.items item.fiat_routing: alternative 1.reference_hint: alternative 2

Type: `null`. 

###### application/json body.items item.fiat_routing: alternative 2

Type: `null`. 

###### application/json body.items item.label

At least one alternative must match.

###### application/json body.items item.label: alternative 1

Type: `string`. 

###### application/json body.items item.label: alternative 2

Type: `null`. 

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. minLength: 1

###### application/json body.next_page_token: alternative 2

Type: `null`.


### withdrawal-destinations-list 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.


### withdrawal-destinations-list Response 401 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.


### withdrawal-destinations-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#withdrawal-destinations-list-response-401-schema).


### withdrawal-destinations-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#withdrawal-destinations-list-response-401-schema).


### withdrawal-destinations-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#withdrawal-destinations-list-response-400-schema).


### withdrawal-destinations-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#withdrawal-destinations-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "asset": "USDC",
        "created_at": "2026-05-01T10:00:00Z",
        "crypto_routing": {
          "asset": "USDC",
          "destination": {
            "address": "0xAbCd1234567890AbCd1234567890AbCd12345678",
            "memo": null
          },
          "label": "My ETH wallet",
          "network": "ethereum"
        },
        "fiat_routing": null,
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "label": "My ETH wallet",
        "rail_class": "crypto",
        "scope_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "status": "active",
        "updated_at": "2026-05-01T10:00:00Z"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /withdrawal-destinations

**Register withdrawal destination**

Registers a crypto withdrawal destination with typed `{asset, network, destination: {address, memo}, label}` routing and `scope_ref`. Fiat destination creation requires `account_ref` and canonical fiat rails routing `{fiat_rail, method, currency, beneficiary_name, bank_coordinates, reference_hint}`; the pooled fiat route owner is derived server-side. Supply `Idempotency-Key` for replay-safe creation; it takes precedence over body `idempotency_key`. Fiat creation requires a key in either location. Crypto creation generates a key when both are absent, so retrying without a caller-supplied key does not replay the original request.

**Required capability:** `withdrawal_destinations.create`

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

Exactly one alternative must match.

#### Request body schema: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `crypto_routing` | object | Yes | No additional fields |
| `idempotency_key` | string | No | minLength: 1 |
| `rail_class` | "crypto" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|platform-operators\|clients)\/([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})$` |

Additional fields are not accepted.

##### Request body schema: alternative 1.crypto_routing

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `destination` | object | Yes | No additional fields |
| `label` | string or null | No |  |
| `network` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### Request body schema: alternative 1.crypto_routing.destination

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `address` | string | Yes | minLength: 1; maxLength: 256 |
| `memo` | string or null | Yes |  |

Additional fields are not accepted.

###### Request body schema: alternative 1.crypto_routing.destination.memo

At least one alternative must match.

###### Request body schema: alternative 1.crypto_routing.destination.memo: alternative 1

Type: `string`. 

###### Request body schema: alternative 1.crypto_routing.destination.memo: alternative 2

Type: `null`. 

###### Request body schema: alternative 1.crypto_routing.label

At least one alternative must match.

###### Request body schema: alternative 1.crypto_routing.label: alternative 1

Type: `string`. 

###### Request body schema: alternative 1.crypto_routing.label: alternative 2

Type: `null`. 

#### Request body schema: 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})$` |
| `fiat_routing` | object | Yes | No additional fields |
| `idempotency_key` | string | No | minLength: 1 |
| `rail_class` | "fiat" | Yes |  |

Additional fields are not accepted.

##### Request body schema: alternative 2.fiat_routing

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `bank_coordinates` | object or object | Yes |  |
| `beneficiary_name` | string | Yes | minLength: 1; maxLength: 140 |
| `currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `fiat_rail` | "sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire" | Yes |  |
| `method` | "bank_transfer" | Yes |  |
| `reference_hint` | string or null | Yes |  |

Additional fields are not accepted.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates

Exactly one alternative must match.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `iban` | string | Yes | minLength: 1; maxLength: 34 |
| `scheme` | "iban" | Yes |  |

Additional fields are not accepted.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bank_address: alternative 1.postal_code

At least one alternative must match.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bank_address: alternative 1.region

At least one alternative must match.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bank_address: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bank_name

At least one alternative must match.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bank_name: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bic

At least one alternative must match.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bic: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string | Yes | minLength: 1; maxLength: 64 |
| `account_type` | "checking" / "savings" or null | No | Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept. |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `routing_codes` | object[] | Yes | minItems: 1; maxItems: 16 |
| `scheme` | "local_account" | Yes |  |

Additional fields are not accepted.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.account_type

Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept.

At least one alternative must match.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.account_type: alternative 1

Type: `"checking" / "savings"`. 

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.account_type: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bank_address: alternative 1.postal_code

At least one alternative must match.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bank_address: alternative 1.region

At least one alternative must match.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bank_address: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bank_name

At least one alternative must match.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bank_name: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bic

At least one alternative must match.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bic: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.routing_codes

Type: `object[]`. minItems: 1; maxItems: 16

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.routing_codes item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `type` | string | Yes | minLength: 1; maxLength: 64 |
| `value` | string | Yes | minLength: 1; maxLength: 64 |

Additional fields are not accepted.

###### Request body schema: alternative 2.fiat_routing.reference_hint

At least one alternative must match.

###### Request body schema: alternative 2.fiat_routing.reference_hint: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema: alternative 2.fiat_routing.reference_hint: alternative 2

Type: `null`.

**Request example:**

```json
{
  "crypto_routing": {
    "asset": "USDC",
    "destination": {
      "address": "0xAbCd1234567890AbCd1234567890AbCd12345678",
      "memo": null
    },
    "label": "My ETH wallet",
    "network": "ethereum"
  },
  "rail_class": "crypto",
  "scope_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}
```

### withdrawal-destinations-create Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string or null | No |  |
| `created_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))$` |
| `crypto_routing` | object or null | No |  |
| `fiat_routing` | object or null | No |  |
| `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)$` |
| `label` | string or null | No |  |
| `rail_class` | "fiat" / "crypto" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|platform-operators\|clients)\/([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})$` |
| `status` | "active" / "disabled" / "retired" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.asset

At least one alternative must match.

###### application/json body.asset: alternative 1

Currency code (ISO-4217 or on-chain ticker)

Type: `string`. pattern: `^[A-Z0-9]{1,16}$`

###### application/json body.asset: alternative 2

Type: `null`. 

##### application/json body.crypto_routing

At least one alternative must match.

###### application/json body.crypto_routing: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `destination` | object | Yes | No additional fields |
| `label` | string or null | Yes |  |
| `network` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.crypto_routing: alternative 1.destination

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `address` | string | Yes | minLength: 1; maxLength: 256 |
| `memo` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.crypto_routing: alternative 1.destination.memo

At least one alternative must match.

###### application/json body.crypto_routing: alternative 1.destination.memo: alternative 1

Type: `string`. 

###### application/json body.crypto_routing: alternative 1.destination.memo: alternative 2

Type: `null`. 

###### application/json body.crypto_routing: alternative 1.label

At least one alternative must match.

###### application/json body.crypto_routing: alternative 1.label: alternative 1

Type: `string`. 

###### application/json body.crypto_routing: alternative 1.label: alternative 2

Type: `null`. 

###### application/json body.crypto_routing: alternative 2

Type: `null`. 

##### application/json body.fiat_routing

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `bank_coordinates` | object or object | Yes |  |
| `beneficiary_name` | string | Yes | minLength: 1; maxLength: 140 |
| `currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `fiat_rail` | "sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire" | Yes |  |
| `method` | "bank_transfer" | Yes |  |
| `reference_hint` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_coordinates

Exactly one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `iban` | string | Yes | minLength: 1; maxLength: 34 |
| `scheme` | "iban" | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_name

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_name: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bic

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bic: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string | Yes | minLength: 1; maxLength: 64 |
| `account_type` | "checking" / "savings" or null | No | Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept. |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `routing_codes` | object[] | Yes | minItems: 1; maxItems: 16 |
| `scheme` | "local_account" | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.account_type

Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.account_type: alternative 1

Type: `"checking" / "savings"`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.account_type: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_name

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_name: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bic

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bic: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.routing_codes

Type: `object[]`. minItems: 1; maxItems: 16

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.routing_codes item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `type` | string | Yes | minLength: 1; maxLength: 64 |
| `value` | string | Yes | minLength: 1; maxLength: 64 |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.reference_hint

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.reference_hint: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.reference_hint: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 2

Type: `null`. 

##### application/json body.label

At least one alternative must match.

###### application/json body.label: alternative 1

Type: `string`. 

###### application/json body.label: alternative 2

Type: `null`.


### withdrawal-destinations-create 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.


### withdrawal-destinations-create Response 401 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.


### withdrawal-destinations-create Response 403 schema

Content type: `application/json`.

See [response 401 schema](#withdrawal-destinations-create-response-401-schema).


### withdrawal-destinations-create Response 409 schema

Content type: `application/json`.

See [response 401 schema](#withdrawal-destinations-create-response-401-schema).


### withdrawal-destinations-create Response 500 schema

Content type: `application/json`.

See [response 401 schema](#withdrawal-destinations-create-response-401-schema).


### withdrawal-destinations-create Response 502 schema

Content type: `application/json`.

See [response 400 schema](#withdrawal-destinations-create-response-400-schema).


### withdrawal-destinations-create Response 503 schema

Content type: `application/json`.

See [response 400 schema](#withdrawal-destinations-create-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "asset": "USDC",
    "created_at": "2026-05-01T10:00:00Z",
    "crypto_routing": {
      "asset": "USDC",
      "destination": {
        "address": "0xAbCd1234567890AbCd1234567890AbCd12345678",
        "memo": null
      },
      "label": "My ETH wallet",
      "network": "ethereum"
    },
    "fiat_routing": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "label": "My ETH wallet",
    "rail_class": "crypto",
    "scope_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /withdrawal-destinations/{destination_id}

**Get withdrawal destination**

Reads a withdrawal destination by id. The `rail_class` query parameter is required so edge can route directly to the selected backend. Fiat reads also require `account_ref` as the producer scope field; the pooled fiat route owner is derived server-side.

**Required capability:** `withdrawal_destinations.read`

**Authentication:** Bearer token required.

**Parameters:**

- `destination_id` `string` (path) *(required)*
- `rail_class` `string` (query) *(required)*
- `account_ref` `string` (query)

### withdrawal-destinations-get Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string or null | No |  |
| `created_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))$` |
| `crypto_routing` | object or null | No |  |
| `fiat_routing` | object or null | No |  |
| `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)$` |
| `label` | string or null | No |  |
| `rail_class` | "fiat" / "crypto" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|platform-operators\|clients)\/([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})$` |
| `status` | "active" / "disabled" / "retired" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.asset

At least one alternative must match.

###### application/json body.asset: alternative 1

Currency code (ISO-4217 or on-chain ticker)

Type: `string`. pattern: `^[A-Z0-9]{1,16}$`

###### application/json body.asset: alternative 2

Type: `null`. 

##### application/json body.crypto_routing

At least one alternative must match.

###### application/json body.crypto_routing: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `destination` | object | Yes | No additional fields |
| `label` | string or null | Yes |  |
| `network` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.crypto_routing: alternative 1.destination

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `address` | string | Yes | minLength: 1; maxLength: 256 |
| `memo` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.crypto_routing: alternative 1.destination.memo

At least one alternative must match.

###### application/json body.crypto_routing: alternative 1.destination.memo: alternative 1

Type: `string`. 

###### application/json body.crypto_routing: alternative 1.destination.memo: alternative 2

Type: `null`. 

###### application/json body.crypto_routing: alternative 1.label

At least one alternative must match.

###### application/json body.crypto_routing: alternative 1.label: alternative 1

Type: `string`. 

###### application/json body.crypto_routing: alternative 1.label: alternative 2

Type: `null`. 

###### application/json body.crypto_routing: alternative 2

Type: `null`. 

##### application/json body.fiat_routing

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `bank_coordinates` | object or object | Yes |  |
| `beneficiary_name` | string | Yes | minLength: 1; maxLength: 140 |
| `currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `fiat_rail` | "sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire" | Yes |  |
| `method` | "bank_transfer" | Yes |  |
| `reference_hint` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_coordinates

Exactly one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `iban` | string | Yes | minLength: 1; maxLength: 34 |
| `scheme` | "iban" | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_name

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_name: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bic

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bic: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string | Yes | minLength: 1; maxLength: 64 |
| `account_type` | "checking" / "savings" or null | No | Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept. |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `routing_codes` | object[] | Yes | minItems: 1; maxItems: 16 |
| `scheme` | "local_account" | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.account_type

Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.account_type: alternative 1

Type: `"checking" / "savings"`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.account_type: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_name

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_name: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bic

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bic: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.routing_codes

Type: `object[]`. minItems: 1; maxItems: 16

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.routing_codes item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `type` | string | Yes | minLength: 1; maxLength: 64 |
| `value` | string | Yes | minLength: 1; maxLength: 64 |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.reference_hint

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.reference_hint: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.reference_hint: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 2

Type: `null`. 

##### application/json body.label

At least one alternative must match.

###### application/json body.label: alternative 1

Type: `string`. 

###### application/json body.label: alternative 2

Type: `null`.


### withdrawal-destinations-get 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.


### withdrawal-destinations-get Response 401 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.


### withdrawal-destinations-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#withdrawal-destinations-get-response-401-schema).


### withdrawal-destinations-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#withdrawal-destinations-get-response-401-schema).


### withdrawal-destinations-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#withdrawal-destinations-get-response-401-schema).


### withdrawal-destinations-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#withdrawal-destinations-get-response-400-schema).


### withdrawal-destinations-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#withdrawal-destinations-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "asset": "USDC",
    "created_at": "2026-05-01T10:00:00Z",
    "crypto_routing": {
      "asset": "USDC",
      "destination": {
        "address": "0xAbCd1234567890AbCd1234567890AbCd12345678",
        "memo": null
      },
      "label": "My ETH wallet",
      "network": "ethereum"
    },
    "fiat_routing": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "label": "My ETH wallet",
    "rail_class": "crypto",
    "scope_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### PATCH /withdrawal-destinations/{destination_id}

**Update withdrawal destination**

Updates a crypto withdrawal destination with typed `{asset, network, destination: {address, memo}, label}` routing. Fiat updates require `account_ref` and canonical fiat rails routing `{fiat_rail, method, currency, beneficiary_name, bank_coordinates, reference_hint}`. Fiat updates require an idempotency key in the `Idempotency-Key` header or body `idempotency_key`; the header takes precedence. Crypto updates do not use an idempotency key. PATCH requests are not replayed by the edge idempotency interceptor; a fiat update uses the key in rails-router.

**Required capability:** `withdrawal_destinations.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `destination_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

Exactly one alternative must match.

#### Request body schema: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `crypto_routing` | object | Yes | No additional fields |
| `rail_class` | "crypto" | Yes |  |

Additional fields are not accepted.

##### Request body schema: alternative 1.crypto_routing

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `destination` | object | Yes | No additional fields |
| `label` | string or null | No |  |
| `network` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### Request body schema: alternative 1.crypto_routing.destination

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `address` | string | Yes | minLength: 1; maxLength: 256 |
| `memo` | string or null | Yes |  |

Additional fields are not accepted.

###### Request body schema: alternative 1.crypto_routing.destination.memo

At least one alternative must match.

###### Request body schema: alternative 1.crypto_routing.destination.memo: alternative 1

Type: `string`. 

###### Request body schema: alternative 1.crypto_routing.destination.memo: alternative 2

Type: `null`. 

###### Request body schema: alternative 1.crypto_routing.label

At least one alternative must match.

###### Request body schema: alternative 1.crypto_routing.label: alternative 1

Type: `string`. 

###### Request body schema: alternative 1.crypto_routing.label: alternative 2

Type: `null`. 

#### Request body schema: 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})$` |
| `fiat_routing` | object | Yes | No additional fields |
| `idempotency_key` | string | No | minLength: 1 |
| `rail_class` | "fiat" | Yes |  |

Additional fields are not accepted.

##### Request body schema: alternative 2.fiat_routing

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `bank_coordinates` | object or object | Yes |  |
| `beneficiary_name` | string | Yes | minLength: 1; maxLength: 140 |
| `currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `fiat_rail` | "sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire" | Yes |  |
| `method` | "bank_transfer" | Yes |  |
| `reference_hint` | string or null | Yes |  |

Additional fields are not accepted.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates

Exactly one alternative must match.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `iban` | string | Yes | minLength: 1; maxLength: 34 |
| `scheme` | "iban" | Yes |  |

Additional fields are not accepted.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bank_address: alternative 1.postal_code

At least one alternative must match.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bank_address: alternative 1.region

At least one alternative must match.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bank_address: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bank_name

At least one alternative must match.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bank_name: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bic

At least one alternative must match.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 1.bic: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string | Yes | minLength: 1; maxLength: 64 |
| `account_type` | "checking" / "savings" or null | No | Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept. |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `routing_codes` | object[] | Yes | minItems: 1; maxItems: 16 |
| `scheme` | "local_account" | Yes |  |

Additional fields are not accepted.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.account_type

Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept.

At least one alternative must match.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.account_type: alternative 1

Type: `"checking" / "savings"`. 

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.account_type: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bank_address: alternative 1.postal_code

At least one alternative must match.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bank_address: alternative 1.region

At least one alternative must match.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bank_address: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bank_name

At least one alternative must match.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bank_name: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bic

At least one alternative must match.

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.bic: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.routing_codes

Type: `object[]`. minItems: 1; maxItems: 16

###### Request body schema: alternative 2.fiat_routing.bank_coordinates: alternative 2.routing_codes item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `type` | string | Yes | minLength: 1; maxLength: 64 |
| `value` | string | Yes | minLength: 1; maxLength: 64 |

Additional fields are not accepted.

###### Request body schema: alternative 2.fiat_routing.reference_hint

At least one alternative must match.

###### Request body schema: alternative 2.fiat_routing.reference_hint: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema: alternative 2.fiat_routing.reference_hint: alternative 2

Type: `null`.

**Request example:**

```json
{
  "crypto_routing": {
    "asset": "USDC",
    "destination": {
      "address": "0xAbCd1234567890AbCd1234567890AbCd12345678",
      "memo": null
    },
    "label": "My Polygon wallet",
    "network": "polygon"
  },
  "rail_class": "crypto"
}
```

### withdrawal-destinations-update Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string or null | No |  |
| `created_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))$` |
| `crypto_routing` | object or null | No |  |
| `fiat_routing` | object or null | No |  |
| `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)$` |
| `label` | string or null | No |  |
| `rail_class` | "fiat" / "crypto" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|platform-operators\|clients)\/([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})$` |
| `status` | "active" / "disabled" / "retired" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.asset

At least one alternative must match.

###### application/json body.asset: alternative 1

Currency code (ISO-4217 or on-chain ticker)

Type: `string`. pattern: `^[A-Z0-9]{1,16}$`

###### application/json body.asset: alternative 2

Type: `null`. 

##### application/json body.crypto_routing

At least one alternative must match.

###### application/json body.crypto_routing: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `destination` | object | Yes | No additional fields |
| `label` | string or null | Yes |  |
| `network` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.crypto_routing: alternative 1.destination

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `address` | string | Yes | minLength: 1; maxLength: 256 |
| `memo` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.crypto_routing: alternative 1.destination.memo

At least one alternative must match.

###### application/json body.crypto_routing: alternative 1.destination.memo: alternative 1

Type: `string`. 

###### application/json body.crypto_routing: alternative 1.destination.memo: alternative 2

Type: `null`. 

###### application/json body.crypto_routing: alternative 1.label

At least one alternative must match.

###### application/json body.crypto_routing: alternative 1.label: alternative 1

Type: `string`. 

###### application/json body.crypto_routing: alternative 1.label: alternative 2

Type: `null`. 

###### application/json body.crypto_routing: alternative 2

Type: `null`. 

##### application/json body.fiat_routing

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `bank_coordinates` | object or object | Yes |  |
| `beneficiary_name` | string | Yes | minLength: 1; maxLength: 140 |
| `currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `fiat_rail` | "sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire" | Yes |  |
| `method` | "bank_transfer" | Yes |  |
| `reference_hint` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_coordinates

Exactly one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `iban` | string | Yes | minLength: 1; maxLength: 34 |
| `scheme` | "iban" | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_name

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_name: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bic

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bic: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string | Yes | minLength: 1; maxLength: 64 |
| `account_type` | "checking" / "savings" or null | No | Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept. |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `routing_codes` | object[] | Yes | minItems: 1; maxItems: 16 |
| `scheme` | "local_account" | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.account_type

Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.account_type: alternative 1

Type: `"checking" / "savings"`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.account_type: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_name

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_name: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bic

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bic: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.routing_codes

Type: `object[]`. minItems: 1; maxItems: 16

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.routing_codes item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `type` | string | Yes | minLength: 1; maxLength: 64 |
| `value` | string | Yes | minLength: 1; maxLength: 64 |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.reference_hint

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.reference_hint: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.reference_hint: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 2

Type: `null`. 

##### application/json body.label

At least one alternative must match.

###### application/json body.label: alternative 1

Type: `string`. 

###### application/json body.label: alternative 2

Type: `null`.


### withdrawal-destinations-update 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.


### withdrawal-destinations-update Response 401 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.


### withdrawal-destinations-update Response 403 schema

Content type: `application/json`.

See [response 401 schema](#withdrawal-destinations-update-response-401-schema).


### withdrawal-destinations-update Response 404 schema

Content type: `application/json`.

See [response 401 schema](#withdrawal-destinations-update-response-401-schema).


### withdrawal-destinations-update Response 409 schema

Content type: `application/json`.

See [response 401 schema](#withdrawal-destinations-update-response-401-schema).


### withdrawal-destinations-update Response 500 schema

Content type: `application/json`.

See [response 401 schema](#withdrawal-destinations-update-response-401-schema).


### withdrawal-destinations-update Response 502 schema

Content type: `application/json`.

See [response 400 schema](#withdrawal-destinations-update-response-400-schema).


### withdrawal-destinations-update Response 503 schema

Content type: `application/json`.

See [response 400 schema](#withdrawal-destinations-update-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "asset": "USDC",
    "created_at": "2026-05-01T10:00:00Z",
    "crypto_routing": {
      "asset": "USDC",
      "destination": {
        "address": "0xAbCd1234567890AbCd1234567890AbCd12345678",
        "memo": null
      },
      "label": "My ETH wallet",
      "network": "ethereum"
    },
    "fiat_routing": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "label": "My ETH wallet",
    "rail_class": "crypto",
    "scope_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /withdrawal-destinations/{destination_id}/disable

**Disable withdrawal destination**

Changes withdrawal destination state. The `rail_class` query parameter is required so edge can route directly to the selected backend. Fiat state changes also require `account_ref`. Fiat state changes require an idempotency key in the `Idempotency-Key` header or query `idempotency_key`; the header takes precedence. Crypto state changes do not use an idempotency key in the crypto path. With an Idempotency-Key header, the edge interceptor can replay the original POST response.

**Required capability:** `withdrawal_destinations.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `destination_id` `string` (path) *(required)*
- `rail_class` `string` (query) *(required)*
- `account_ref` `string` (query)
- `idempotency_key` `string` (query)
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

### withdrawal-destinations-disable Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string or null | No |  |
| `created_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))$` |
| `crypto_routing` | object or null | No |  |
| `fiat_routing` | object or null | No |  |
| `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)$` |
| `label` | string or null | No |  |
| `rail_class` | "fiat" / "crypto" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|platform-operators\|clients)\/([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})$` |
| `status` | "active" / "disabled" / "retired" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.asset

At least one alternative must match.

###### application/json body.asset: alternative 1

Currency code (ISO-4217 or on-chain ticker)

Type: `string`. pattern: `^[A-Z0-9]{1,16}$`

###### application/json body.asset: alternative 2

Type: `null`. 

##### application/json body.crypto_routing

At least one alternative must match.

###### application/json body.crypto_routing: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `destination` | object | Yes | No additional fields |
| `label` | string or null | Yes |  |
| `network` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.crypto_routing: alternative 1.destination

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `address` | string | Yes | minLength: 1; maxLength: 256 |
| `memo` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.crypto_routing: alternative 1.destination.memo

At least one alternative must match.

###### application/json body.crypto_routing: alternative 1.destination.memo: alternative 1

Type: `string`. 

###### application/json body.crypto_routing: alternative 1.destination.memo: alternative 2

Type: `null`. 

###### application/json body.crypto_routing: alternative 1.label

At least one alternative must match.

###### application/json body.crypto_routing: alternative 1.label: alternative 1

Type: `string`. 

###### application/json body.crypto_routing: alternative 1.label: alternative 2

Type: `null`. 

###### application/json body.crypto_routing: alternative 2

Type: `null`. 

##### application/json body.fiat_routing

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `bank_coordinates` | object or object | Yes |  |
| `beneficiary_name` | string | Yes | minLength: 1; maxLength: 140 |
| `currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `fiat_rail` | "sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire" | Yes |  |
| `method` | "bank_transfer" | Yes |  |
| `reference_hint` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_coordinates

Exactly one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `iban` | string | Yes | minLength: 1; maxLength: 34 |
| `scheme` | "iban" | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_name

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_name: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bic

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bic: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string | Yes | minLength: 1; maxLength: 64 |
| `account_type` | "checking" / "savings" or null | No | Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept. |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `routing_codes` | object[] | Yes | minItems: 1; maxItems: 16 |
| `scheme` | "local_account" | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.account_type

Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.account_type: alternative 1

Type: `"checking" / "savings"`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.account_type: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_name

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_name: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bic

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bic: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.routing_codes

Type: `object[]`. minItems: 1; maxItems: 16

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.routing_codes item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `type` | string | Yes | minLength: 1; maxLength: 64 |
| `value` | string | Yes | minLength: 1; maxLength: 64 |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.reference_hint

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.reference_hint: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.reference_hint: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 2

Type: `null`. 

##### application/json body.label

At least one alternative must match.

###### application/json body.label: alternative 1

Type: `string`. 

###### application/json body.label: alternative 2

Type: `null`.


### withdrawal-destinations-disable 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.


### withdrawal-destinations-disable Response 401 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.


### withdrawal-destinations-disable Response 403 schema

Content type: `application/json`.

See [response 401 schema](#withdrawal-destinations-disable-response-401-schema).


### withdrawal-destinations-disable Response 404 schema

Content type: `application/json`.

See [response 401 schema](#withdrawal-destinations-disable-response-401-schema).


### withdrawal-destinations-disable Response 409 schema

Content type: `application/json`.

See [response 401 schema](#withdrawal-destinations-disable-response-401-schema).


### withdrawal-destinations-disable Response 500 schema

Content type: `application/json`.

See [response 401 schema](#withdrawal-destinations-disable-response-401-schema).


### withdrawal-destinations-disable Response 502 schema

Content type: `application/json`.

See [response 400 schema](#withdrawal-destinations-disable-response-400-schema).


### withdrawal-destinations-disable Response 503 schema

Content type: `application/json`.

See [response 400 schema](#withdrawal-destinations-disable-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "asset": "USDC",
    "created_at": "2026-05-01T10:00:00Z",
    "crypto_routing": {
      "asset": "USDC",
      "destination": {
        "address": "0xAbCd1234567890AbCd1234567890AbCd12345678",
        "memo": null
      },
      "label": "My ETH wallet",
      "network": "ethereum"
    },
    "fiat_routing": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "label": "My ETH wallet",
    "rail_class": "crypto",
    "scope_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /withdrawal-destinations/{destination_id}/enable

**Enable withdrawal destination**

Changes withdrawal destination state. The `rail_class` query parameter is required so edge can route directly to the selected backend. Fiat state changes also require `account_ref`. Fiat state changes require an idempotency key in the `Idempotency-Key` header or query `idempotency_key`; the header takes precedence. Crypto state changes do not use an idempotency key in the crypto path. With an Idempotency-Key header, the edge interceptor can replay the original POST response.

**Required capability:** `withdrawal_destinations.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `destination_id` `string` (path) *(required)*
- `rail_class` `string` (query) *(required)*
- `account_ref` `string` (query)
- `idempotency_key` `string` (query)
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

### withdrawal-destinations-enable Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string or null | No |  |
| `created_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))$` |
| `crypto_routing` | object or null | No |  |
| `fiat_routing` | object or null | No |  |
| `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)$` |
| `label` | string or null | No |  |
| `rail_class` | "fiat" / "crypto" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|platform-operators\|clients)\/([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})$` |
| `status` | "active" / "disabled" / "retired" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.asset

At least one alternative must match.

###### application/json body.asset: alternative 1

Currency code (ISO-4217 or on-chain ticker)

Type: `string`. pattern: `^[A-Z0-9]{1,16}$`

###### application/json body.asset: alternative 2

Type: `null`. 

##### application/json body.crypto_routing

At least one alternative must match.

###### application/json body.crypto_routing: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `destination` | object | Yes | No additional fields |
| `label` | string or null | Yes |  |
| `network` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.crypto_routing: alternative 1.destination

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `address` | string | Yes | minLength: 1; maxLength: 256 |
| `memo` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.crypto_routing: alternative 1.destination.memo

At least one alternative must match.

###### application/json body.crypto_routing: alternative 1.destination.memo: alternative 1

Type: `string`. 

###### application/json body.crypto_routing: alternative 1.destination.memo: alternative 2

Type: `null`. 

###### application/json body.crypto_routing: alternative 1.label

At least one alternative must match.

###### application/json body.crypto_routing: alternative 1.label: alternative 1

Type: `string`. 

###### application/json body.crypto_routing: alternative 1.label: alternative 2

Type: `null`. 

###### application/json body.crypto_routing: alternative 2

Type: `null`. 

##### application/json body.fiat_routing

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `bank_coordinates` | object or object | Yes |  |
| `beneficiary_name` | string | Yes | minLength: 1; maxLength: 140 |
| `currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `fiat_rail` | "sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire" | Yes |  |
| `method` | "bank_transfer" | Yes |  |
| `reference_hint` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_coordinates

Exactly one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `iban` | string | Yes | minLength: 1; maxLength: 34 |
| `scheme` | "iban" | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_name

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_name: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bic

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bic: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string | Yes | minLength: 1; maxLength: 64 |
| `account_type` | "checking" / "savings" or null | No | Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept. |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `routing_codes` | object[] | Yes | minItems: 1; maxItems: 16 |
| `scheme` | "local_account" | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.account_type

Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.account_type: alternative 1

Type: `"checking" / "savings"`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.account_type: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_name

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_name: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bic

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bic: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.routing_codes

Type: `object[]`. minItems: 1; maxItems: 16

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.routing_codes item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `type` | string | Yes | minLength: 1; maxLength: 64 |
| `value` | string | Yes | minLength: 1; maxLength: 64 |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.reference_hint

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.reference_hint: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.reference_hint: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 2

Type: `null`. 

##### application/json body.label

At least one alternative must match.

###### application/json body.label: alternative 1

Type: `string`. 

###### application/json body.label: alternative 2

Type: `null`.


### withdrawal-destinations-enable 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.


### withdrawal-destinations-enable Response 401 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.


### withdrawal-destinations-enable Response 403 schema

Content type: `application/json`.

See [response 401 schema](#withdrawal-destinations-enable-response-401-schema).


### withdrawal-destinations-enable Response 404 schema

Content type: `application/json`.

See [response 401 schema](#withdrawal-destinations-enable-response-401-schema).


### withdrawal-destinations-enable Response 409 schema

Content type: `application/json`.

See [response 401 schema](#withdrawal-destinations-enable-response-401-schema).


### withdrawal-destinations-enable Response 500 schema

Content type: `application/json`.

See [response 401 schema](#withdrawal-destinations-enable-response-401-schema).


### withdrawal-destinations-enable Response 502 schema

Content type: `application/json`.

See [response 400 schema](#withdrawal-destinations-enable-response-400-schema).


### withdrawal-destinations-enable Response 503 schema

Content type: `application/json`.

See [response 400 schema](#withdrawal-destinations-enable-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "asset": "USDC",
    "created_at": "2026-05-01T10:00:00Z",
    "crypto_routing": {
      "asset": "USDC",
      "destination": {
        "address": "0xAbCd1234567890AbCd1234567890AbCd12345678",
        "memo": null
      },
      "label": "My ETH wallet",
      "network": "ethereum"
    },
    "fiat_routing": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "label": "My ETH wallet",
    "rail_class": "crypto",
    "scope_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /withdrawal-destinations/{destination_id}/retire

**Retire withdrawal destination**

Changes withdrawal destination state. The `rail_class` query parameter is required so edge can route directly to the selected backend. Fiat state changes also require `account_ref`. Fiat state changes require an idempotency key in the `Idempotency-Key` header or query `idempotency_key`; the header takes precedence. Crypto state changes do not use an idempotency key in the crypto path. With an Idempotency-Key header, the edge interceptor can replay the original POST response.

**Required capability:** `withdrawal_destinations.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `destination_id` `string` (path) *(required)*
- `rail_class` `string` (query) *(required)*
- `account_ref` `string` (query)
- `idempotency_key` `string` (query)
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

### withdrawal-destinations-retire Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string or null | No |  |
| `created_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))$` |
| `crypto_routing` | object or null | No |  |
| `fiat_routing` | object or null | No |  |
| `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)$` |
| `label` | string or null | No |  |
| `rail_class` | "fiat" / "crypto" | Yes |  |
| `scope_ref` | string | Yes | pattern: `^(enterprises\|platform-operators\|clients)\/([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})$` |
| `status` | "active" / "disabled" / "retired" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.asset

At least one alternative must match.

###### application/json body.asset: alternative 1

Currency code (ISO-4217 or on-chain ticker)

Type: `string`. pattern: `^[A-Z0-9]{1,16}$`

###### application/json body.asset: alternative 2

Type: `null`. 

##### application/json body.crypto_routing

At least one alternative must match.

###### application/json body.crypto_routing: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `destination` | object | Yes | No additional fields |
| `label` | string or null | Yes |  |
| `network` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.crypto_routing: alternative 1.destination

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `address` | string | Yes | minLength: 1; maxLength: 256 |
| `memo` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.crypto_routing: alternative 1.destination.memo

At least one alternative must match.

###### application/json body.crypto_routing: alternative 1.destination.memo: alternative 1

Type: `string`. 

###### application/json body.crypto_routing: alternative 1.destination.memo: alternative 2

Type: `null`. 

###### application/json body.crypto_routing: alternative 1.label

At least one alternative must match.

###### application/json body.crypto_routing: alternative 1.label: alternative 1

Type: `string`. 

###### application/json body.crypto_routing: alternative 1.label: alternative 2

Type: `null`. 

###### application/json body.crypto_routing: alternative 2

Type: `null`. 

##### application/json body.fiat_routing

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `bank_coordinates` | object or object | Yes |  |
| `beneficiary_name` | string | Yes | minLength: 1; maxLength: 140 |
| `currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `fiat_rail` | "sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire" | Yes |  |
| `method` | "bank_transfer" | Yes |  |
| `reference_hint` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_coordinates

Exactly one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `iban` | string | Yes | minLength: 1; maxLength: 34 |
| `scheme` | "iban" | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_name

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bank_name: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bic

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 1.bic: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string | Yes | minLength: 1; maxLength: 64 |
| `account_type` | "checking" / "savings" or null | No | Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept. |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `routing_codes` | object[] | Yes | minItems: 1; maxItems: 16 |
| `scheme` | "local_account" | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.account_type

Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.account_type: alternative 1

Type: `"checking" / "savings"`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.account_type: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_name

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bank_name: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bic

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.bic: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.routing_codes

Type: `object[]`. minItems: 1; maxItems: 16

###### application/json body.fiat_routing: alternative 1.bank_coordinates: alternative 2.routing_codes item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `type` | string | Yes | minLength: 1; maxLength: 64 |
| `value` | string | Yes | minLength: 1; maxLength: 64 |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.reference_hint

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.reference_hint: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.reference_hint: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 2

Type: `null`. 

##### application/json body.label

At least one alternative must match.

###### application/json body.label: alternative 1

Type: `string`. 

###### application/json body.label: alternative 2

Type: `null`.


### withdrawal-destinations-retire 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.


### withdrawal-destinations-retire Response 401 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.


### withdrawal-destinations-retire Response 403 schema

Content type: `application/json`.

See [response 401 schema](#withdrawal-destinations-retire-response-401-schema).


### withdrawal-destinations-retire Response 404 schema

Content type: `application/json`.

See [response 401 schema](#withdrawal-destinations-retire-response-401-schema).


### withdrawal-destinations-retire Response 409 schema

Content type: `application/json`.

See [response 401 schema](#withdrawal-destinations-retire-response-401-schema).


### withdrawal-destinations-retire Response 500 schema

Content type: `application/json`.

See [response 401 schema](#withdrawal-destinations-retire-response-401-schema).


### withdrawal-destinations-retire Response 502 schema

Content type: `application/json`.

See [response 400 schema](#withdrawal-destinations-retire-response-400-schema).


### withdrawal-destinations-retire Response 503 schema

Content type: `application/json`.

See [response 400 schema](#withdrawal-destinations-retire-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "asset": "USDC",
    "created_at": "2026-05-01T10:00:00Z",
    "crypto_routing": {
      "asset": "USDC",
      "destination": {
        "address": "0xAbCd1234567890AbCd1234567890AbCd12345678",
        "memo": null
      },
      "label": "My ETH wallet",
      "network": "ethereum"
    },
    "fiat_routing": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "label": "My ETH wallet",
    "rail_class": "crypto",
    "scope_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Internal Transfers

### GET /internal-transfers

**List internal transfers**

**Required capability:** `internal_transfers.read`

**Authentication:** Bearer token required.

**Parameters:**

- `account_ref` `string` (query)
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### internal-transfers-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object or object or object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object or object or object[]`. 

###### application/json body.items item

At least one alternative must match.

###### application/json body.items item: 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})$` |
| `applied_rate` | string or null | Yes |  |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `conversion_execution_id` | string or null | Yes |  |
| `created_at` | string or string | Yes |  |
| `failure_detail` | object or null | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "conversion" | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fee_transaction_ids` | string[] or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `ledger_posted_target_amount` | object or null | Yes |  |
| `leg_attempt_id` | string or null | Yes |  |
| `posted_at` | string or string or null | Yes |  |
| `principal_amount` | object | Yes | No additional fields |
| `principal_transaction_id` | string or null | Yes |  |
| `settled_at` | string or string or null | Yes |  |
| `source_gross_amount` | object or null | Yes |  |
| `source_principal_amount` | object or null | Yes |  |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `target_amount` | object or null | Yes |  |
| `target_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.applied_rate

At least one alternative must match.

###### application/json body.items item: alternative 1.applied_rate: alternative 1

DecimalString

Type: `string`. pattern: `^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$`

###### application/json body.items item: alternative 1.applied_rate: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.approval_ref

At least one alternative must match.

###### application/json body.items item: alternative 1.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body.items item: alternative 1.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 1.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 1.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body.items item: alternative 1.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body.items item: alternative 1.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.approval_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.compliance_assessment_ref

At least one alternative must match.

###### application/json body.items item: alternative 1.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body.items item: alternative 1.compliance_assessment_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.conversion_execution_id

At least one alternative must match.

###### application/json body.items item: alternative 1.conversion_execution_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item: alternative 1.conversion_execution_id: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.created_at

At least one alternative must match.

###### application/json body.items item: alternative 1.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 1.created_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 1.failure_detail

At least one alternative must match.

###### application/json body.items item: alternative 1.failure_detail: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `failed_at` | string or string or null | Yes |  |
| `reason_code` | string | Yes | pattern: `^[a-z0-9_.:-]+$`; minLength: 1; maxLength: 128 |
| `retryable` | boolean or null | Yes |  |
| `stage` | "pre_execution" / "execution" / "post_fill" / "ledger_posting" / "unknown" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.failure_detail: alternative 1.failed_at

At least one alternative must match.

###### application/json body.items item: alternative 1.failure_detail: alternative 1.failed_at: alternative 1

At least one alternative must match.

###### application/json body.items item: alternative 1.failure_detail: alternative 1.failed_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 1.failure_detail: alternative 1.failed_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 1.failure_detail: alternative 1.failed_at: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.failure_detail: alternative 1.retryable

At least one alternative must match.

###### application/json body.items item: alternative 1.failure_detail: alternative 1.retryable: alternative 1

Type: `boolean`. 

###### application/json body.items item: alternative 1.failure_detail: alternative 1.retryable: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.failure_detail: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.failure_reason

At least one alternative must match.

###### application/json body.items item: alternative 1.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.items item: alternative 1.failure_reason: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.fee_summary

At least one alternative must match.

###### application/json body.items item: alternative 1.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body.items item: alternative 1.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.fee_summary: alternative 1.components item.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.

###### application/json body.items item: alternative 1.fee_summary: alternative 1.total

| 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.

###### application/json body.items item: alternative 1.fee_summary: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.fee_transaction_ids

At least one alternative must match.

###### application/json body.items item: alternative 1.fee_transaction_ids: alternative 1

Type: `string[]`. 

###### application/json body.items item: alternative 1.fee_transaction_ids: alternative 1 item

Type: `string`. 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)$`

###### application/json body.items item: alternative 1.fee_transaction_ids: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.fill_rate

At least one alternative must match.

###### application/json body.items item: alternative 1.fill_rate: alternative 1

Type: `string`. 

###### application/json body.items item: alternative 1.fill_rate: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.ledger_posted_target_amount

At least one alternative must match.

###### application/json body.items item: alternative 1.ledger_posted_target_amount: alternative 1

| 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.

###### application/json body.items item: alternative 1.ledger_posted_target_amount: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.leg_attempt_id

At least one alternative must match.

###### application/json body.items item: alternative 1.leg_attempt_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item: alternative 1.leg_attempt_id: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.posted_at

At least one alternative must match.

###### application/json body.items item: alternative 1.posted_at: alternative 1

At least one alternative must match.

###### application/json body.items item: alternative 1.posted_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 1.posted_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 1.posted_at: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.principal_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.

###### application/json body.items item: alternative 1.principal_transaction_id

At least one alternative must match.

###### application/json body.items item: alternative 1.principal_transaction_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item: alternative 1.principal_transaction_id: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.settled_at

At least one alternative must match.

###### application/json body.items item: alternative 1.settled_at: alternative 1

At least one alternative must match.

###### application/json body.items item: alternative 1.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 1.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 1.settled_at: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.source_gross_amount

At least one alternative must match.

###### application/json body.items item: alternative 1.source_gross_amount: alternative 1

| 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.

###### application/json body.items item: alternative 1.source_gross_amount: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.source_principal_amount

At least one alternative must match.

###### application/json body.items item: alternative 1.source_principal_amount: alternative 1

| 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.

###### application/json body.items item: alternative 1.source_principal_amount: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.subject_attribution.actor

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 1.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution.approved_by

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 1.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 1.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 1.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution.federation

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 1.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution.subject

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 1.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution.subject: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.target_amount

At least one alternative must match.

###### application/json body.items item: alternative 1.target_amount: alternative 1

| 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.

###### application/json body.items item: alternative 1.target_amount: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.updated_at

At least one alternative must match.

###### application/json body.items item: alternative 1.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 1.updated_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: 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})$` |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `created_at` | string or string | Yes |  |
| `external_settlement_role` | "external_source_spend" / "external_target_disbursement" | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "external_settlement_conversion" | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `internal_settlement_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})$` |
| `principal_amount` | object | Yes | No additional fields |
| `settled_at` | string or string or null | Yes |  |
| `settlement_checked_at` | string or string | Yes |  |
| `settlement_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `target_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.approval_ref

At least one alternative must match.

###### application/json body.items item: alternative 2.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body.items item: alternative 2.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 2.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 2.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body.items item: alternative 2.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body.items item: alternative 2.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.approval_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.compliance_assessment_ref

At least one alternative must match.

###### application/json body.items item: alternative 2.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body.items item: alternative 2.compliance_assessment_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.created_at

At least one alternative must match.

###### application/json body.items item: alternative 2.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 2.created_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 2.failure_reason

At least one alternative must match.

###### application/json body.items item: alternative 2.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.items item: alternative 2.failure_reason: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.fee_summary

At least one alternative must match.

###### application/json body.items item: alternative 2.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body.items item: alternative 2.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.fee_summary: alternative 1.components item.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.

###### application/json body.items item: alternative 2.fee_summary: alternative 1.total

| 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.

###### application/json body.items item: alternative 2.fee_summary: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.fill_rate

At least one alternative must match.

###### application/json body.items item: alternative 2.fill_rate: alternative 1

Type: `string`. 

###### application/json body.items item: alternative 2.fill_rate: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.principal_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.

###### application/json body.items item: alternative 2.settled_at

At least one alternative must match.

###### application/json body.items item: alternative 2.settled_at: alternative 1

At least one alternative must match.

###### application/json body.items item: alternative 2.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 2.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 2.settled_at: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.settlement_checked_at

At least one alternative must match.

###### application/json body.items item: alternative 2.settlement_checked_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 2.settlement_checked_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 2.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.subject_attribution.actor

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 2.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.subject_attribution.approved_by

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 2.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 2.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 2.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.subject_attribution.federation

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 2.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.subject_attribution.subject

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 2.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.subject_attribution.subject: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.updated_at

At least one alternative must match.

###### application/json body.items item: alternative 2.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 2.updated_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 3

| 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})$` |
| `admission_hold_reason` | "CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED" or null | No |  |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `created_at` | string or string | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "deposit" / "withdrawal" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension" | Yes |  |
| `family_params` | object | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `principal_amount` | object | Yes | No additional fields |
| `settled_at` | string or string or null | Yes |  |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.admission_hold_reason

At least one alternative must match.

###### application/json body.items item: alternative 3.admission_hold_reason: alternative 1

Type: `"CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED"`. 

###### application/json body.items item: alternative 3.admission_hold_reason: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.approval_ref

At least one alternative must match.

###### application/json body.items item: alternative 3.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body.items item: alternative 3.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 3.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 3.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body.items item: alternative 3.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body.items item: alternative 3.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.approval_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.compliance_assessment_ref

At least one alternative must match.

###### application/json body.items item: alternative 3.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body.items item: alternative 3.compliance_assessment_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.created_at

At least one alternative must match.

###### application/json body.items item: alternative 3.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 3.created_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 3.failure_reason

At least one alternative must match.

###### application/json body.items item: alternative 3.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.items item: alternative 3.failure_reason: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.fee_summary

At least one alternative must match.

###### application/json body.items item: alternative 3.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body.items item: alternative 3.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.fee_summary: alternative 1.components item.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.

###### application/json body.items item: alternative 3.fee_summary: alternative 1.total

| 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.

###### application/json body.items item: alternative 3.fee_summary: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.fill_rate

At least one alternative must match.

###### application/json body.items item: alternative 3.fill_rate: alternative 1

Type: `string`. 

###### application/json body.items item: alternative 3.fill_rate: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.principal_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.

###### application/json body.items item: alternative 3.settled_at

At least one alternative must match.

###### application/json body.items item: alternative 3.settled_at: alternative 1

At least one alternative must match.

###### application/json body.items item: alternative 3.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 3.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 3.settled_at: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.subject_attribution.actor

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 3.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution.approved_by

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 3.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 3.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 3.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution.federation

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 3.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution.subject

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 3.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution.subject: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.updated_at

At least one alternative must match.

###### application/json body.items item: alternative 3.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 3.updated_at: alternative 2

Type: `string`. format: date-time

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. 

###### application/json body.next_page_token: alternative 2

Type: `null`.


### internal-transfers-list 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.


### internal-transfers-list Response 401 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.


### internal-transfers-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#internal-transfers-list-response-401-schema).


### internal-transfers-list Response 404 schema

Content type: `application/json`.

See [response 401 schema](#internal-transfers-list-response-401-schema).


### internal-transfers-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#internal-transfers-list-response-401-schema).


### internal-transfers-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#internal-transfers-list-response-400-schema).


### internal-transfers-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#internal-transfers-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "approval_ref": null,
        "created_at": "2026-05-01T10:00:00Z",
        "failure_reason": null,
        "family": "internal_transfer",
        "family_params": {
          "amount": {
            "currency": "USDC",
            "value": "250.00"
          },
          "source_ref": "master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
          "target_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
        },
        "fee_summary": {
          "components": [
            {
              "amount": {
                "currency": "USDC",
                "value": "1.00"
              },
              "kind": "platform_fee"
            }
          ],
          "total": {
            "currency": "USDC",
            "value": "1.00"
          }
        },
        "fill_rate": null,
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "principal_amount": {
          "currency": "USDC",
          "value": "250.00"
        },
        "settled_at": "2026-05-01T10:00:00Z",
        "status": "settled",
        "subject_attribution": {
          "actor": null,
          "approved_by": null,
          "authenticated_principal": {
            "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
            "kind": "user",
            "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
          },
          "enterprise_binding": {
            "tenant_type": "enterprise",
            "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
          },
          "federation": null,
          "identity_source": "platform-managed",
          "initiated_by": null,
          "subject": {
            "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
            "kind": "user",
            "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
          }
        },
        "updated_at": "2026-05-01T10:00:00Z"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /internal-transfers

**Create internal transfer**

Initiates an internal transfer between two accounts inside the same tenant. Supply `Idempotency-Key` or body `client_idempotency_key` for idempotent retries; the header takes precedence. If both are omitted, a fresh key is generated and retries create separate operations. `amount` is a positive monetary value such as `{"value":"250.00","currency":"USDC"}`. The source and target accounts must differ.

**Required capability:** `internal_transfers.create`

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `client_idempotency_key` | string | No | minLength: 1 |
| `source_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})$` |
| `target_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})$` |

Additional fields are not accepted.

#### Request body schema.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 example:**

```json
{
  "amount": {
    "currency": "USDC",
    "value": "250.00"
  },
  "source_ref": "master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "target_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}
```

### internal-transfers-create Response 202 schema

Content type: `application/json`.

#### application/json body

| 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})$` |
| `admission_hold_reason` | "CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED" or null | No |  |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `created_at` | string or string | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "deposit" / "withdrawal" / "conversion" / "external_settlement_conversion" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension" | Yes |  |
| `family_params` | object | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `principal_amount` | object | Yes | No additional fields |
| `settled_at` | string or string or null | Yes |  |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

##### application/json body.admission_hold_reason

At least one alternative must match.

###### application/json body.admission_hold_reason: alternative 1

Type: `"CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED"`. 

###### application/json body.admission_hold_reason: alternative 2

Type: `null`. 

##### application/json body.approval_ref

At least one alternative must match.

###### application/json body.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body.approval_ref: alternative 2

Type: `null`. 

##### application/json body.compliance_assessment_ref

At least one alternative must match.

###### application/json body.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body.compliance_assessment_ref: alternative 2

Type: `null`. 

##### application/json body.created_at

At least one alternative must match.

###### application/json body.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.created_at: alternative 2

Type: `string`. format: date-time

##### application/json body.failure_reason

At least one alternative must match.

###### application/json body.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.failure_reason: alternative 2

Type: `null`. 

##### application/json body.fee_summary

At least one alternative must match.

###### application/json body.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body.fee_summary: alternative 1.components item.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.

###### application/json body.fee_summary: alternative 1.total

| 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.

###### application/json body.fee_summary: alternative 2

Type: `null`. 

##### application/json body.fill_rate

At least one alternative must match.

###### application/json body.fill_rate: alternative 1

Type: `string`. 

###### application/json body.fill_rate: alternative 2

Type: `null`. 

##### application/json body.principal_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.

##### application/json body.settled_at

At least one alternative must match.

###### application/json body.settled_at: alternative 1

At least one alternative must match.

###### application/json body.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.settled_at: alternative 2

Type: `null`. 

##### application/json body.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.federation

At least one alternative must match.

###### application/json body.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject: alternative 2

Type: `null`. 

##### application/json body.updated_at

At least one alternative must match.

###### application/json body.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.updated_at: alternative 2

Type: `string`. format: date-time


### internal-transfers-create 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.


### internal-transfers-create Response 401 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.


### internal-transfers-create Response 403 schema

Content type: `application/json`.

See [response 401 schema](#internal-transfers-create-response-401-schema).


### internal-transfers-create Response 409 schema

Content type: `application/json`.

See [response 401 schema](#internal-transfers-create-response-401-schema).


### internal-transfers-create Response 422 schema

Content type: `application/json`.

See [response 401 schema](#internal-transfers-create-response-401-schema).


### internal-transfers-create Response 500 schema

Content type: `application/json`.

See [response 401 schema](#internal-transfers-create-response-401-schema).


### internal-transfers-create Response 502 schema

Content type: `application/json`.

See [response 400 schema](#internal-transfers-create-response-400-schema).


### internal-transfers-create Response 503 schema

Content type: `application/json`.

See [response 400 schema](#internal-transfers-create-response-400-schema).


**Responses:**

- `202` — Request accepted for asynchronous processing. Follow the resource identifiers returned by this operation to observe progress.

  ```json
  {
    "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "approval_ref": null,
    "created_at": "2026-05-01T10:00:00Z",
    "failure_reason": null,
    "family": "internal_transfer",
    "family_params": {
      "amount": {
        "currency": "USDC",
        "value": "250.00"
      },
      "source_ref": "master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "target_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
    },
    "fee_summary": null,
    "fill_rate": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "principal_amount": {
      "currency": "USDC",
      "value": "250.00"
    },
    "settled_at": null,
    "status": "admissible",
    "subject_attribution": {
      "actor": null,
      "approved_by": null,
      "authenticated_principal": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "enterprise_binding": {
        "tenant_type": "enterprise",
        "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "federation": null,
      "identity_source": "platform-managed",
      "initiated_by": null,
      "subject": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      }
    },
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `422` — The request cannot be processed under the resource or route contract. Depending on the endpoint, code can be not_admissible or unsupported_currency; inspect the documented code and data.reason.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /internal-transfers/{internal_transfer_id}

**Get internal transfer**

**Required capability:** `internal_transfers.read`

**Authentication:** Bearer token required.

**Parameters:**

- `internal_transfer_id` `string` (path) *(required)*

### internal-transfers-get Response 200 schema

Content type: `application/json`.

#### application/json body

At least one alternative must match.

##### application/json body: 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})$` |
| `applied_rate` | string or null | Yes |  |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `conversion_execution_id` | string or null | Yes |  |
| `created_at` | string or string | Yes |  |
| `failure_detail` | object or null | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "conversion" | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fee_transaction_ids` | string[] or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `ledger_posted_target_amount` | object or null | Yes |  |
| `leg_attempt_id` | string or null | Yes |  |
| `posted_at` | string or string or null | Yes |  |
| `principal_amount` | object | Yes | No additional fields |
| `principal_transaction_id` | string or null | Yes |  |
| `settled_at` | string or string or null | Yes |  |
| `source_gross_amount` | object or null | Yes |  |
| `source_principal_amount` | object or null | Yes |  |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `target_amount` | object or null | Yes |  |
| `target_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 1.applied_rate

At least one alternative must match.

###### application/json body: alternative 1.applied_rate: alternative 1

DecimalString

Type: `string`. pattern: `^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$`

###### application/json body: alternative 1.applied_rate: alternative 2

Type: `null`. 

###### application/json body: alternative 1.approval_ref

At least one alternative must match.

###### application/json body: alternative 1.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 1.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body: alternative 1.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 1.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 1.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body: alternative 1.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body: alternative 1.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body: alternative 1.approval_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 1.compliance_assessment_ref

At least one alternative must match.

###### application/json body: alternative 1.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body: alternative 1.compliance_assessment_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 1.conversion_execution_id

At least one alternative must match.

###### application/json body: alternative 1.conversion_execution_id: alternative 1

Type: `string`. 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)$`

###### application/json body: alternative 1.conversion_execution_id: alternative 2

Type: `null`. 

###### application/json body: alternative 1.created_at

At least one alternative must match.

###### application/json body: alternative 1.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 1.created_at: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 1.failure_detail

At least one alternative must match.

###### application/json body: alternative 1.failure_detail: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `failed_at` | string or string or null | Yes |  |
| `reason_code` | string | Yes | pattern: `^[a-z0-9_.:-]+$`; minLength: 1; maxLength: 128 |
| `retryable` | boolean or null | Yes |  |
| `stage` | "pre_execution" / "execution" / "post_fill" / "ledger_posting" / "unknown" | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 1.failure_detail: alternative 1.failed_at

At least one alternative must match.

###### application/json body: alternative 1.failure_detail: alternative 1.failed_at: alternative 1

At least one alternative must match.

###### application/json body: alternative 1.failure_detail: alternative 1.failed_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 1.failure_detail: alternative 1.failed_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 1.failure_detail: alternative 1.failed_at: alternative 2

Type: `null`. 

###### application/json body: alternative 1.failure_detail: alternative 1.retryable

At least one alternative must match.

###### application/json body: alternative 1.failure_detail: alternative 1.retryable: alternative 1

Type: `boolean`. 

###### application/json body: alternative 1.failure_detail: alternative 1.retryable: alternative 2

Type: `null`. 

###### application/json body: alternative 1.failure_detail: alternative 2

Type: `null`. 

###### application/json body: alternative 1.failure_reason

At least one alternative must match.

###### application/json body: alternative 1.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body: alternative 1.failure_reason: alternative 2

Type: `null`. 

###### application/json body: alternative 1.fee_summary

At least one alternative must match.

###### application/json body: alternative 1.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body: alternative 1.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body: alternative 1.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 1.fee_summary: alternative 1.components item.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.

###### application/json body: alternative 1.fee_summary: alternative 1.total

| 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.

###### application/json body: alternative 1.fee_summary: alternative 2

Type: `null`. 

###### application/json body: alternative 1.fee_transaction_ids

At least one alternative must match.

###### application/json body: alternative 1.fee_transaction_ids: alternative 1

Type: `string[]`. 

###### application/json body: alternative 1.fee_transaction_ids: alternative 1 item

Type: `string`. 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)$`

###### application/json body: alternative 1.fee_transaction_ids: alternative 2

Type: `null`. 

###### application/json body: alternative 1.fill_rate

At least one alternative must match.

###### application/json body: alternative 1.fill_rate: alternative 1

Type: `string`. 

###### application/json body: alternative 1.fill_rate: alternative 2

Type: `null`. 

###### application/json body: alternative 1.ledger_posted_target_amount

At least one alternative must match.

###### application/json body: alternative 1.ledger_posted_target_amount: alternative 1

| 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.

###### application/json body: alternative 1.ledger_posted_target_amount: alternative 2

Type: `null`. 

###### application/json body: alternative 1.leg_attempt_id

At least one alternative must match.

###### application/json body: alternative 1.leg_attempt_id: alternative 1

Type: `string`. 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)$`

###### application/json body: alternative 1.leg_attempt_id: alternative 2

Type: `null`. 

###### application/json body: alternative 1.posted_at

At least one alternative must match.

###### application/json body: alternative 1.posted_at: alternative 1

At least one alternative must match.

###### application/json body: alternative 1.posted_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 1.posted_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 1.posted_at: alternative 2

Type: `null`. 

###### application/json body: alternative 1.principal_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.

###### application/json body: alternative 1.principal_transaction_id

At least one alternative must match.

###### application/json body: alternative 1.principal_transaction_id: alternative 1

Type: `string`. 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)$`

###### application/json body: alternative 1.principal_transaction_id: alternative 2

Type: `null`. 

###### application/json body: alternative 1.settled_at

At least one alternative must match.

###### application/json body: alternative 1.settled_at: alternative 1

At least one alternative must match.

###### application/json body: alternative 1.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 1.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 1.settled_at: alternative 2

Type: `null`. 

###### application/json body: alternative 1.source_gross_amount

At least one alternative must match.

###### application/json body: alternative 1.source_gross_amount: alternative 1

| 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.

###### application/json body: alternative 1.source_gross_amount: alternative 2

Type: `null`. 

###### application/json body: alternative 1.source_principal_amount

At least one alternative must match.

###### application/json body: alternative 1.source_principal_amount: alternative 1

| 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.

###### application/json body: alternative 1.source_principal_amount: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 1.subject_attribution.actor

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 1.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 1.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution.approved_by

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 1.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 1.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 1.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 1.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 1.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 1.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution.federation

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body: alternative 1.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 1.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 1.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution.subject

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 1.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 1.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution.subject: alternative 2

Type: `null`. 

###### application/json body: alternative 1.target_amount

At least one alternative must match.

###### application/json body: alternative 1.target_amount: alternative 1

| 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.

###### application/json body: alternative 1.target_amount: alternative 2

Type: `null`. 

###### application/json body: alternative 1.updated_at

At least one alternative must match.

###### application/json body: alternative 1.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 1.updated_at: alternative 2

Type: `string`. format: date-time

##### application/json body: 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})$` |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `created_at` | string or string | Yes |  |
| `external_settlement_role` | "external_source_spend" / "external_target_disbursement" | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "external_settlement_conversion" | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `internal_settlement_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})$` |
| `principal_amount` | object | Yes | No additional fields |
| `settled_at` | string or string or null | Yes |  |
| `settlement_checked_at` | string or string | Yes |  |
| `settlement_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `target_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 2.approval_ref

At least one alternative must match.

###### application/json body: alternative 2.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 2.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body: alternative 2.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 2.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 2.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body: alternative 2.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body: alternative 2.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body: alternative 2.approval_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 2.compliance_assessment_ref

At least one alternative must match.

###### application/json body: alternative 2.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body: alternative 2.compliance_assessment_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 2.created_at

At least one alternative must match.

###### application/json body: alternative 2.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 2.created_at: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 2.failure_reason

At least one alternative must match.

###### application/json body: alternative 2.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body: alternative 2.failure_reason: alternative 2

Type: `null`. 

###### application/json body: alternative 2.fee_summary

At least one alternative must match.

###### application/json body: alternative 2.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body: alternative 2.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body: alternative 2.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 2.fee_summary: alternative 1.components item.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.

###### application/json body: alternative 2.fee_summary: alternative 1.total

| 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.

###### application/json body: alternative 2.fee_summary: alternative 2

Type: `null`. 

###### application/json body: alternative 2.fill_rate

At least one alternative must match.

###### application/json body: alternative 2.fill_rate: alternative 1

Type: `string`. 

###### application/json body: alternative 2.fill_rate: alternative 2

Type: `null`. 

###### application/json body: alternative 2.principal_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.

###### application/json body: alternative 2.settled_at

At least one alternative must match.

###### application/json body: alternative 2.settled_at: alternative 1

At least one alternative must match.

###### application/json body: alternative 2.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 2.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 2.settled_at: alternative 2

Type: `null`. 

###### application/json body: alternative 2.settlement_checked_at

At least one alternative must match.

###### application/json body: alternative 2.settlement_checked_at: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 2.settlement_checked_at: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 2.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 2.subject_attribution.actor

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 2.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 2.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 2.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body: alternative 2.subject_attribution.approved_by

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 2.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 2.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 2.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body: alternative 2.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 2.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 2.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 2.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 2.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 2.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 2.subject_attribution.federation

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body: alternative 2.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body: alternative 2.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 2.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 2.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 2.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body: alternative 2.subject_attribution.subject

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 2.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 2.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 2.subject_attribution.subject: alternative 2

Type: `null`. 

###### application/json body: alternative 2.updated_at

At least one alternative must match.

###### application/json body: alternative 2.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 2.updated_at: alternative 2

Type: `string`. format: date-time

##### application/json body: alternative 3

| 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})$` |
| `admission_hold_reason` | "CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED" or null | No |  |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `created_at` | string or string | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "deposit" / "withdrawal" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension" | Yes |  |
| `family_params` | object | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `principal_amount` | object | Yes | No additional fields |
| `settled_at` | string or string or null | Yes |  |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 3.admission_hold_reason

At least one alternative must match.

###### application/json body: alternative 3.admission_hold_reason: alternative 1

Type: `"CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED"`. 

###### application/json body: alternative 3.admission_hold_reason: alternative 2

Type: `null`. 

###### application/json body: alternative 3.approval_ref

At least one alternative must match.

###### application/json body: alternative 3.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 3.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body: alternative 3.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 3.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 3.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body: alternative 3.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body: alternative 3.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body: alternative 3.approval_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 3.compliance_assessment_ref

At least one alternative must match.

###### application/json body: alternative 3.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body: alternative 3.compliance_assessment_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 3.created_at

At least one alternative must match.

###### application/json body: alternative 3.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 3.created_at: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 3.failure_reason

At least one alternative must match.

###### application/json body: alternative 3.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body: alternative 3.failure_reason: alternative 2

Type: `null`. 

###### application/json body: alternative 3.fee_summary

At least one alternative must match.

###### application/json body: alternative 3.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body: alternative 3.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body: alternative 3.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 3.fee_summary: alternative 1.components item.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.

###### application/json body: alternative 3.fee_summary: alternative 1.total

| 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.

###### application/json body: alternative 3.fee_summary: alternative 2

Type: `null`. 

###### application/json body: alternative 3.fill_rate

At least one alternative must match.

###### application/json body: alternative 3.fill_rate: alternative 1

Type: `string`. 

###### application/json body: alternative 3.fill_rate: alternative 2

Type: `null`. 

###### application/json body: alternative 3.principal_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.

###### application/json body: alternative 3.settled_at

At least one alternative must match.

###### application/json body: alternative 3.settled_at: alternative 1

At least one alternative must match.

###### application/json body: alternative 3.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 3.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 3.settled_at: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 3.subject_attribution.actor

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 3.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 3.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution.approved_by

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 3.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 3.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 3.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 3.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 3.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 3.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution.federation

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body: alternative 3.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 3.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 3.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution.subject

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 3.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 3.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution.subject: alternative 2

Type: `null`. 

###### application/json body: alternative 3.updated_at

At least one alternative must match.

###### application/json body: alternative 3.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 3.updated_at: alternative 2

Type: `string`. format: date-time


### internal-transfers-get 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.


### internal-transfers-get Response 401 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.


### internal-transfers-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#internal-transfers-get-response-401-schema).


### internal-transfers-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#internal-transfers-get-response-401-schema).


### internal-transfers-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#internal-transfers-get-response-401-schema).


### internal-transfers-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#internal-transfers-get-response-400-schema).


### internal-transfers-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#internal-transfers-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "approval_ref": null,
    "created_at": "2026-05-01T10:00:00Z",
    "failure_reason": null,
    "family": "internal_transfer",
    "family_params": {
      "amount": {
        "currency": "USDC",
        "value": "250.00"
      },
      "source_ref": "master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "target_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
    },
    "fee_summary": {
      "components": [
        {
          "amount": {
            "currency": "USDC",
            "value": "1.00"
          },
          "kind": "platform_fee"
        }
      ],
      "total": {
        "currency": "USDC",
        "value": "1.00"
      }
    },
    "fill_rate": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "principal_amount": {
      "currency": "USDC",
      "value": "250.00"
    },
    "settled_at": "2026-05-01T10:00:00Z",
    "status": "settled",
    "subject_attribution": {
      "actor": null,
      "approved_by": null,
      "authenticated_principal": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "enterprise_binding": {
        "tenant_type": "enterprise",
        "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "federation": null,
      "identity_source": "platform-managed",
      "initiated_by": null,
      "subject": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      }
    },
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /internal-transfers/{internal_transfer_id}/cancel

**Cancel internal transfer**

**Required capability:** `internal_transfers.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `internal_transfer_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

### internal-transfers-cancel Response 200 schema

Content type: `application/json`.

#### application/json body

| 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})$` |
| `admission_hold_reason` | "CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED" or null | No |  |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `created_at` | string or string | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "deposit" / "withdrawal" / "conversion" / "external_settlement_conversion" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension" | Yes |  |
| `family_params` | object | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `principal_amount` | object | Yes | No additional fields |
| `settled_at` | string or string or null | Yes |  |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

##### application/json body.admission_hold_reason

At least one alternative must match.

###### application/json body.admission_hold_reason: alternative 1

Type: `"CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED"`. 

###### application/json body.admission_hold_reason: alternative 2

Type: `null`. 

##### application/json body.approval_ref

At least one alternative must match.

###### application/json body.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body.approval_ref: alternative 2

Type: `null`. 

##### application/json body.compliance_assessment_ref

At least one alternative must match.

###### application/json body.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body.compliance_assessment_ref: alternative 2

Type: `null`. 

##### application/json body.created_at

At least one alternative must match.

###### application/json body.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.created_at: alternative 2

Type: `string`. format: date-time

##### application/json body.failure_reason

At least one alternative must match.

###### application/json body.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.failure_reason: alternative 2

Type: `null`. 

##### application/json body.fee_summary

At least one alternative must match.

###### application/json body.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body.fee_summary: alternative 1.components item.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.

###### application/json body.fee_summary: alternative 1.total

| 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.

###### application/json body.fee_summary: alternative 2

Type: `null`. 

##### application/json body.fill_rate

At least one alternative must match.

###### application/json body.fill_rate: alternative 1

Type: `string`. 

###### application/json body.fill_rate: alternative 2

Type: `null`. 

##### application/json body.principal_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.

##### application/json body.settled_at

At least one alternative must match.

###### application/json body.settled_at: alternative 1

At least one alternative must match.

###### application/json body.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.settled_at: alternative 2

Type: `null`. 

##### application/json body.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.federation

At least one alternative must match.

###### application/json body.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject: alternative 2

Type: `null`. 

##### application/json body.updated_at

At least one alternative must match.

###### application/json body.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.updated_at: alternative 2

Type: `string`. format: date-time


### internal-transfers-cancel 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.


### internal-transfers-cancel Response 401 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.


### internal-transfers-cancel Response 403 schema

Content type: `application/json`.

See [response 401 schema](#internal-transfers-cancel-response-401-schema).


### internal-transfers-cancel Response 404 schema

Content type: `application/json`.

See [response 401 schema](#internal-transfers-cancel-response-401-schema).


### internal-transfers-cancel Response 409 schema

Content type: `application/json`.

See [response 401 schema](#internal-transfers-cancel-response-401-schema).


### internal-transfers-cancel Response 500 schema

Content type: `application/json`.

See [response 401 schema](#internal-transfers-cancel-response-401-schema).


### internal-transfers-cancel Response 502 schema

Content type: `application/json`.

See [response 400 schema](#internal-transfers-cancel-response-400-schema).


### internal-transfers-cancel Response 503 schema

Content type: `application/json`.

See [response 400 schema](#internal-transfers-cancel-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "approval_ref": null,
    "created_at": "2026-05-01T10:00:00Z",
    "failure_reason": null,
    "family": "internal_transfer",
    "family_params": {
      "amount": {
        "currency": "USDC",
        "value": "250.00"
      },
      "source_ref": "master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "target_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
    },
    "fee_summary": null,
    "fill_rate": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "principal_amount": {
      "currency": "USDC",
      "value": "250.00"
    },
    "settled_at": null,
    "status": "cancelled",
    "subject_attribution": {
      "actor": null,
      "approved_by": null,
      "authenticated_principal": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "enterprise_binding": {
        "tenant_type": "enterprise",
        "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "federation": null,
      "identity_source": "platform-managed",
      "initiated_by": null,
      "subject": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      }
    },
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Conversions

### GET /conversions

**List conversions**

Lists ledger-native conversion operation snapshots. Preview responses are informational only; operation execution may recompute fees and rate before ledger posting, so reads must not be treated as a bound preview replay.

**Required capability:** `conversions.read`

**Authentication:** Bearer token required.

**Parameters:**

- `account_ref` `string` (query)
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### conversions-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| 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})$` |
| `applied_rate` | string or null | Yes |  |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `conversion_execution_id` | string or null | Yes |  |
| `created_at` | string or string | Yes |  |
| `failure_detail` | object or null | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "conversion" | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fee_transaction_ids` | string[] or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `ledger_posted_target_amount` | object or null | Yes |  |
| `leg_attempt_id` | string or null | Yes |  |
| `posted_at` | string or string or null | Yes |  |
| `principal_amount` | object | Yes | No additional fields |
| `principal_transaction_id` | string or null | Yes |  |
| `settled_at` | string or string or null | Yes |  |
| `source_gross_amount` | object or null | Yes |  |
| `source_principal_amount` | object or null | Yes |  |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `target_amount` | object or null | Yes |  |
| `target_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.applied_rate

At least one alternative must match.

###### application/json body.items item.applied_rate: alternative 1

DecimalString

Type: `string`. pattern: `^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$`

###### application/json body.items item.applied_rate: alternative 2

Type: `null`. 

###### application/json body.items item.approval_ref

At least one alternative must match.

###### application/json body.items item.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body.items item.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body.items item.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body.items item.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body.items item.approval_ref: alternative 2

Type: `null`. 

###### application/json body.items item.compliance_assessment_ref

At least one alternative must match.

###### application/json body.items item.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body.items item.compliance_assessment_ref: alternative 2

Type: `null`. 

###### application/json body.items item.conversion_execution_id

At least one alternative must match.

###### application/json body.items item.conversion_execution_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item.conversion_execution_id: alternative 2

Type: `null`. 

###### application/json body.items item.created_at

At least one alternative must match.

###### application/json body.items item.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.created_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.failure_detail

At least one alternative must match.

###### application/json body.items item.failure_detail: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `failed_at` | string or string or null | Yes |  |
| `reason_code` | string | Yes | pattern: `^[a-z0-9_.:-]+$`; minLength: 1; maxLength: 128 |
| `retryable` | boolean or null | Yes |  |
| `stage` | "pre_execution" / "execution" / "post_fill" / "ledger_posting" / "unknown" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.failure_detail: alternative 1.failed_at

At least one alternative must match.

###### application/json body.items item.failure_detail: alternative 1.failed_at: alternative 1

At least one alternative must match.

###### application/json body.items item.failure_detail: alternative 1.failed_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.failure_detail: alternative 1.failed_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.failure_detail: alternative 1.failed_at: alternative 2

Type: `null`. 

###### application/json body.items item.failure_detail: alternative 1.retryable

At least one alternative must match.

###### application/json body.items item.failure_detail: alternative 1.retryable: alternative 1

Type: `boolean`. 

###### application/json body.items item.failure_detail: alternative 1.retryable: alternative 2

Type: `null`. 

###### application/json body.items item.failure_detail: alternative 2

Type: `null`. 

###### application/json body.items item.failure_reason

At least one alternative must match.

###### application/json body.items item.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.items item.failure_reason: alternative 2

Type: `null`. 

###### application/json body.items item.fee_summary

At least one alternative must match.

###### application/json body.items item.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.items item.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body.items item.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.fee_summary: alternative 1.components item.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.

###### application/json body.items item.fee_summary: alternative 1.total

| 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.

###### application/json body.items item.fee_summary: alternative 2

Type: `null`. 

###### application/json body.items item.fee_transaction_ids

At least one alternative must match.

###### application/json body.items item.fee_transaction_ids: alternative 1

Type: `string[]`. 

###### application/json body.items item.fee_transaction_ids: alternative 1 item

Type: `string`. 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)$`

###### application/json body.items item.fee_transaction_ids: alternative 2

Type: `null`. 

###### application/json body.items item.fill_rate

At least one alternative must match.

###### application/json body.items item.fill_rate: alternative 1

Type: `string`. 

###### application/json body.items item.fill_rate: alternative 2

Type: `null`. 

###### application/json body.items item.ledger_posted_target_amount

At least one alternative must match.

###### application/json body.items item.ledger_posted_target_amount: alternative 1

| 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.

###### application/json body.items item.ledger_posted_target_amount: alternative 2

Type: `null`. 

###### application/json body.items item.leg_attempt_id

At least one alternative must match.

###### application/json body.items item.leg_attempt_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item.leg_attempt_id: alternative 2

Type: `null`. 

###### application/json body.items item.posted_at

At least one alternative must match.

###### application/json body.items item.posted_at: alternative 1

At least one alternative must match.

###### application/json body.items item.posted_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.posted_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.posted_at: alternative 2

Type: `null`. 

###### application/json body.items item.principal_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.

###### application/json body.items item.principal_transaction_id

At least one alternative must match.

###### application/json body.items item.principal_transaction_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item.principal_transaction_id: alternative 2

Type: `null`. 

###### application/json body.items item.settled_at

At least one alternative must match.

###### application/json body.items item.settled_at: alternative 1

At least one alternative must match.

###### application/json body.items item.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.settled_at: alternative 2

Type: `null`. 

###### application/json body.items item.source_gross_amount

At least one alternative must match.

###### application/json body.items item.source_gross_amount: alternative 1

| 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.

###### application/json body.items item.source_gross_amount: alternative 2

Type: `null`. 

###### application/json body.items item.source_principal_amount

At least one alternative must match.

###### application/json body.items item.source_principal_amount: alternative 1

| 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.

###### application/json body.items item.source_principal_amount: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.actor

At least one alternative must match.

###### application/json body.items item.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.approved_by

At least one alternative must match.

###### application/json body.items item.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.items item.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.items item.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.federation

At least one alternative must match.

###### application/json body.items item.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body.items item.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.subject

At least one alternative must match.

###### application/json body.items item.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.subject: alternative 2

Type: `null`. 

###### application/json body.items item.target_amount

At least one alternative must match.

###### application/json body.items item.target_amount: alternative 1

| 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.

###### application/json body.items item.target_amount: alternative 2

Type: `null`. 

###### application/json body.items item.updated_at

At least one alternative must match.

###### application/json body.items item.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.updated_at: alternative 2

Type: `string`. format: date-time

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. 

###### application/json body.next_page_token: alternative 2

Type: `null`.


### conversions-list 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.


### conversions-list Response 401 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.


### conversions-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#conversions-list-response-401-schema).


### conversions-list Response 404 schema

Content type: `application/json`.

See [response 401 schema](#conversions-list-response-401-schema).


### conversions-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#conversions-list-response-401-schema).


### conversions-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#conversions-list-response-400-schema).


### conversions-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#conversions-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "applied_rate": "0.00002",
        "approval_ref": null,
        "conversion_execution_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "created_at": "2026-05-01T10:00:00Z",
        "failure_detail": null,
        "failure_reason": null,
        "family": "conversion",
        "fee_summary": {
          "components": [
            {
              "amount": {
                "currency": "USD",
                "value": "1.00"
              },
              "kind": "platform_fee"
            }
          ],
          "total": {
            "currency": "USD",
            "value": "1.00"
          }
        },
        "fee_transaction_ids": [
          "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
        ],
        "fill_rate": "0.00002",
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "ledger_posted_target_amount": {
          "currency": "BTC",
          "value": "0.00498000"
        },
        "leg_attempt_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "posted_at": "2026-05-01T10:00:00Z",
        "principal_amount": {
          "currency": "USD",
          "value": "250.00"
        },
        "principal_transaction_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "settled_at": "2026-05-01T10:00:00Z",
        "source_gross_amount": {
          "currency": "USD",
          "value": "250.00"
        },
        "source_principal_amount": {
          "currency": "USD",
          "value": "249.00"
        },
        "status": "settled",
        "subject_attribution": {
          "actor": null,
          "approved_by": null,
          "authenticated_principal": {
            "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
            "kind": "user",
            "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
          },
          "enterprise_binding": {
            "tenant_type": "enterprise",
            "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
          },
          "federation": null,
          "identity_source": "platform-managed",
          "initiated_by": null,
          "subject": {
            "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
            "kind": "user",
            "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
          }
        },
        "target_amount": {
          "currency": "BTC",
          "value": "0.00498000"
        },
        "target_currency": "BTC",
        "updated_at": "2026-05-01T10:00:00Z"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /conversions

**Create conversion**

Initiates a ledger-native conversion with `account_ref`, `from_amount`, and `to_currency` only. Plain conversions never resolve external settlement facts or carry provider-settlement evidence; use `/external-settlement-conversions` for externally settled conversion roles. Any prior preview is non-binding: conversion execution may recompute fees and rate before ledger posting. The response is the current operation snapshot; after synchronous admission and dispatch the caller can see `admissible`, `pending_approval`, `pending_compliance`, or a terminal state such as `settled` or `failed`. Track it via `GET /conversions/{conversion_id}`. Supply `Idempotency-Key` or body `client_idempotency_key` for idempotent retries; the header takes precedence. If both are omitted, a fresh key is generated. Human callers must obtain a step-up confirmation via `POST /action-tokens` and submit it in the `X-Action-Token` header; use the structured body `{action: "conversion.create", command: <the same conversion body>}`; a matching `command_digest` is also accepted. Service principals are exempt.

**Required capability:** `conversions.create`

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.
- `X-Action-Token` `string` (header) — Single-use step-up confirmation token bound to the server-canonical command for this request. Required when the effective subject is a human user. Callers without a human subject skip only this confirmation check and still pass normal authentication and capability guards. Obtain the token through `POST /action-tokens`, then submit it with the guarded request. Structured commands are supported for withdrawal, conversion, and external-settlement conversion creation; the issue endpoint also accepts `command_digest`. Missing or invalid human-confirmation tokens produce `400` with `code` in {`action_token_required`, `action_token_rejected`}; an unreachable approval service produces `502 action_token_validation_failed`.

**Request body** (`application/json`):

### Request body schema

| 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.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 example:**

```json
{
  "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "from_amount": {
    "currency": "USD",
    "value": "250.00"
  },
  "to_currency": "BTC"
}
```

### conversions-create Response 202 schema

Content type: `application/json`.

#### application/json body

| 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})$` |
| `applied_rate` | string or null | Yes |  |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `conversion_execution_id` | string or null | Yes |  |
| `created_at` | string or string | Yes |  |
| `failure_detail` | object or null | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "conversion" | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fee_transaction_ids` | string[] or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `ledger_posted_target_amount` | object or null | Yes |  |
| `leg_attempt_id` | string or null | Yes |  |
| `posted_at` | string or string or null | Yes |  |
| `principal_amount` | object | Yes | No additional fields |
| `principal_transaction_id` | string or null | Yes |  |
| `settled_at` | string or string or null | Yes |  |
| `source_gross_amount` | object or null | Yes |  |
| `source_principal_amount` | object or null | Yes |  |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `target_amount` | object or null | Yes |  |
| `target_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

##### application/json body.applied_rate

At least one alternative must match.

###### application/json body.applied_rate: alternative 1

DecimalString

Type: `string`. pattern: `^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$`

###### application/json body.applied_rate: alternative 2

Type: `null`. 

##### application/json body.approval_ref

At least one alternative must match.

###### application/json body.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body.approval_ref: alternative 2

Type: `null`. 

##### application/json body.compliance_assessment_ref

At least one alternative must match.

###### application/json body.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body.compliance_assessment_ref: alternative 2

Type: `null`. 

##### application/json body.conversion_execution_id

At least one alternative must match.

###### application/json body.conversion_execution_id: alternative 1

Type: `string`. 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)$`

###### application/json body.conversion_execution_id: alternative 2

Type: `null`. 

##### application/json body.created_at

At least one alternative must match.

###### application/json body.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.created_at: alternative 2

Type: `string`. format: date-time

##### application/json body.failure_detail

At least one alternative must match.

###### application/json body.failure_detail: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `failed_at` | string or string or null | Yes |  |
| `reason_code` | string | Yes | pattern: `^[a-z0-9_.:-]+$`; minLength: 1; maxLength: 128 |
| `retryable` | boolean or null | Yes |  |
| `stage` | "pre_execution" / "execution" / "post_fill" / "ledger_posting" / "unknown" | Yes |  |

Additional fields are not accepted.

###### application/json body.failure_detail: alternative 1.failed_at

At least one alternative must match.

###### application/json body.failure_detail: alternative 1.failed_at: alternative 1

At least one alternative must match.

###### application/json body.failure_detail: alternative 1.failed_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.failure_detail: alternative 1.failed_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.failure_detail: alternative 1.failed_at: alternative 2

Type: `null`. 

###### application/json body.failure_detail: alternative 1.retryable

At least one alternative must match.

###### application/json body.failure_detail: alternative 1.retryable: alternative 1

Type: `boolean`. 

###### application/json body.failure_detail: alternative 1.retryable: alternative 2

Type: `null`. 

###### application/json body.failure_detail: alternative 2

Type: `null`. 

##### application/json body.failure_reason

At least one alternative must match.

###### application/json body.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.failure_reason: alternative 2

Type: `null`. 

##### application/json body.fee_summary

At least one alternative must match.

###### application/json body.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body.fee_summary: alternative 1.components item.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.

###### application/json body.fee_summary: alternative 1.total

| 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.

###### application/json body.fee_summary: alternative 2

Type: `null`. 

##### application/json body.fee_transaction_ids

At least one alternative must match.

###### application/json body.fee_transaction_ids: alternative 1

Type: `string[]`. 

###### application/json body.fee_transaction_ids: alternative 1 item

Type: `string`. 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)$`

###### application/json body.fee_transaction_ids: alternative 2

Type: `null`. 

##### application/json body.fill_rate

At least one alternative must match.

###### application/json body.fill_rate: alternative 1

Type: `string`. 

###### application/json body.fill_rate: alternative 2

Type: `null`. 

##### application/json body.ledger_posted_target_amount

At least one alternative must match.

###### application/json body.ledger_posted_target_amount: alternative 1

| 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.

###### application/json body.ledger_posted_target_amount: alternative 2

Type: `null`. 

##### application/json body.leg_attempt_id

At least one alternative must match.

###### application/json body.leg_attempt_id: alternative 1

Type: `string`. 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)$`

###### application/json body.leg_attempt_id: alternative 2

Type: `null`. 

##### application/json body.posted_at

At least one alternative must match.

###### application/json body.posted_at: alternative 1

At least one alternative must match.

###### application/json body.posted_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.posted_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.posted_at: alternative 2

Type: `null`. 

##### application/json body.principal_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.

##### application/json body.principal_transaction_id

At least one alternative must match.

###### application/json body.principal_transaction_id: alternative 1

Type: `string`. 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)$`

###### application/json body.principal_transaction_id: alternative 2

Type: `null`. 

##### application/json body.settled_at

At least one alternative must match.

###### application/json body.settled_at: alternative 1

At least one alternative must match.

###### application/json body.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.settled_at: alternative 2

Type: `null`. 

##### application/json body.source_gross_amount

At least one alternative must match.

###### application/json body.source_gross_amount: alternative 1

| 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.

###### application/json body.source_gross_amount: alternative 2

Type: `null`. 

##### application/json body.source_principal_amount

At least one alternative must match.

###### application/json body.source_principal_amount: alternative 1

| 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.

###### application/json body.source_principal_amount: alternative 2

Type: `null`. 

##### application/json body.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.federation

At least one alternative must match.

###### application/json body.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject: alternative 2

Type: `null`. 

##### application/json body.target_amount

At least one alternative must match.

###### application/json body.target_amount: alternative 1

| 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.

###### application/json body.target_amount: alternative 2

Type: `null`. 

##### application/json body.updated_at

At least one alternative must match.

###### application/json body.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.updated_at: alternative 2

Type: `string`. format: date-time


### conversions-create 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 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.


### conversions-create Response 401 schema

Content type: `application/json`.

See [response 400 schema](#conversions-create-response-400-schema).


### conversions-create Response 403 schema

Content type: `application/json`.

See [response 400 schema](#conversions-create-response-400-schema).


### conversions-create Response 409 schema

Content type: `application/json`.

See [response 400 schema](#conversions-create-response-400-schema).


### conversions-create Response 422 schema

Content type: `application/json`.

See [response 400 schema](#conversions-create-response-400-schema).


### conversions-create Response 500 schema

Content type: `application/json`.

See [response 400 schema](#conversions-create-response-400-schema).


### conversions-create Response 502 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.


### conversions-create Response 503 schema

Content type: `application/json`.

See [response 502 schema](#conversions-create-response-502-schema).


**Responses:**

- `202` — Request accepted for asynchronous processing. Follow the resource identifiers returned by this operation to observe progress.

  ```json
  {
    "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "applied_rate": null,
    "approval_ref": null,
    "conversion_execution_id": null,
    "created_at": "2026-05-01T10:00:00Z",
    "failure_detail": null,
    "failure_reason": null,
    "family": "conversion",
    "fee_summary": null,
    "fee_transaction_ids": null,
    "fill_rate": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "ledger_posted_target_amount": null,
    "leg_attempt_id": null,
    "posted_at": null,
    "principal_amount": {
      "currency": "USD",
      "value": "250.00"
    },
    "principal_transaction_id": null,
    "settled_at": null,
    "source_gross_amount": null,
    "source_principal_amount": null,
    "status": "admissible",
    "subject_attribution": {
      "actor": null,
      "approved_by": null,
      "authenticated_principal": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "enterprise_binding": {
        "tenant_type": "enterprise",
        "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "federation": null,
      "identity_source": "platform-managed",
      "initiated_by": null,
      "subject": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      }
    },
    "target_amount": null,
    "target_currency": "BTC",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Step-up confirmation failed for a money-movement operation. `code` is one of: `action_token_required` (X-Action-Token header missing), `action_token_rejected` (token is unknown, expired, already consumed, or its server-canonical command binding does not match the current request). Obtain a fresh token via `POST /action-tokens` and retry. Structured issuance accepts `withdrawal.create`, `conversion.create`, and `external_settlement_conversion.create`. The issue endpoint also accepts `command_digest`. Human confirmation applies to the effective user subject; callers without a human subject skip this confirmation check.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `422` — The request cannot be processed under the resource or route contract. Depending on the endpoint, code can be not_admissible or unsupported_currency; inspect the documented code and data.reason.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /conversions/{conversion_id}

**Get conversion**

Returns the current ledger-native conversion operation snapshot. Preview economics are non-binding display data; settled execution may use recomputed fees and rate before ledger posting.

**Required capability:** `conversions.read`

**Authentication:** Bearer token required.

**Parameters:**

- `conversion_id` `string` (path) *(required)*

### conversions-get Response 200 schema

Content type: `application/json`.

#### application/json body

| 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})$` |
| `applied_rate` | string or null | Yes |  |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `conversion_execution_id` | string or null | Yes |  |
| `created_at` | string or string | Yes |  |
| `failure_detail` | object or null | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "conversion" | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fee_transaction_ids` | string[] or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `ledger_posted_target_amount` | object or null | Yes |  |
| `leg_attempt_id` | string or null | Yes |  |
| `posted_at` | string or string or null | Yes |  |
| `principal_amount` | object | Yes | No additional fields |
| `principal_transaction_id` | string or null | Yes |  |
| `settled_at` | string or string or null | Yes |  |
| `source_gross_amount` | object or null | Yes |  |
| `source_principal_amount` | object or null | Yes |  |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `target_amount` | object or null | Yes |  |
| `target_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

##### application/json body.applied_rate

At least one alternative must match.

###### application/json body.applied_rate: alternative 1

DecimalString

Type: `string`. pattern: `^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$`

###### application/json body.applied_rate: alternative 2

Type: `null`. 

##### application/json body.approval_ref

At least one alternative must match.

###### application/json body.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body.approval_ref: alternative 2

Type: `null`. 

##### application/json body.compliance_assessment_ref

At least one alternative must match.

###### application/json body.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body.compliance_assessment_ref: alternative 2

Type: `null`. 

##### application/json body.conversion_execution_id

At least one alternative must match.

###### application/json body.conversion_execution_id: alternative 1

Type: `string`. 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)$`

###### application/json body.conversion_execution_id: alternative 2

Type: `null`. 

##### application/json body.created_at

At least one alternative must match.

###### application/json body.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.created_at: alternative 2

Type: `string`. format: date-time

##### application/json body.failure_detail

At least one alternative must match.

###### application/json body.failure_detail: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `failed_at` | string or string or null | Yes |  |
| `reason_code` | string | Yes | pattern: `^[a-z0-9_.:-]+$`; minLength: 1; maxLength: 128 |
| `retryable` | boolean or null | Yes |  |
| `stage` | "pre_execution" / "execution" / "post_fill" / "ledger_posting" / "unknown" | Yes |  |

Additional fields are not accepted.

###### application/json body.failure_detail: alternative 1.failed_at

At least one alternative must match.

###### application/json body.failure_detail: alternative 1.failed_at: alternative 1

At least one alternative must match.

###### application/json body.failure_detail: alternative 1.failed_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.failure_detail: alternative 1.failed_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.failure_detail: alternative 1.failed_at: alternative 2

Type: `null`. 

###### application/json body.failure_detail: alternative 1.retryable

At least one alternative must match.

###### application/json body.failure_detail: alternative 1.retryable: alternative 1

Type: `boolean`. 

###### application/json body.failure_detail: alternative 1.retryable: alternative 2

Type: `null`. 

###### application/json body.failure_detail: alternative 2

Type: `null`. 

##### application/json body.failure_reason

At least one alternative must match.

###### application/json body.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.failure_reason: alternative 2

Type: `null`. 

##### application/json body.fee_summary

At least one alternative must match.

###### application/json body.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body.fee_summary: alternative 1.components item.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.

###### application/json body.fee_summary: alternative 1.total

| 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.

###### application/json body.fee_summary: alternative 2

Type: `null`. 

##### application/json body.fee_transaction_ids

At least one alternative must match.

###### application/json body.fee_transaction_ids: alternative 1

Type: `string[]`. 

###### application/json body.fee_transaction_ids: alternative 1 item

Type: `string`. 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)$`

###### application/json body.fee_transaction_ids: alternative 2

Type: `null`. 

##### application/json body.fill_rate

At least one alternative must match.

###### application/json body.fill_rate: alternative 1

Type: `string`. 

###### application/json body.fill_rate: alternative 2

Type: `null`. 

##### application/json body.ledger_posted_target_amount

At least one alternative must match.

###### application/json body.ledger_posted_target_amount: alternative 1

| 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.

###### application/json body.ledger_posted_target_amount: alternative 2

Type: `null`. 

##### application/json body.leg_attempt_id

At least one alternative must match.

###### application/json body.leg_attempt_id: alternative 1

Type: `string`. 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)$`

###### application/json body.leg_attempt_id: alternative 2

Type: `null`. 

##### application/json body.posted_at

At least one alternative must match.

###### application/json body.posted_at: alternative 1

At least one alternative must match.

###### application/json body.posted_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.posted_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.posted_at: alternative 2

Type: `null`. 

##### application/json body.principal_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.

##### application/json body.principal_transaction_id

At least one alternative must match.

###### application/json body.principal_transaction_id: alternative 1

Type: `string`. 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)$`

###### application/json body.principal_transaction_id: alternative 2

Type: `null`. 

##### application/json body.settled_at

At least one alternative must match.

###### application/json body.settled_at: alternative 1

At least one alternative must match.

###### application/json body.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.settled_at: alternative 2

Type: `null`. 

##### application/json body.source_gross_amount

At least one alternative must match.

###### application/json body.source_gross_amount: alternative 1

| 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.

###### application/json body.source_gross_amount: alternative 2

Type: `null`. 

##### application/json body.source_principal_amount

At least one alternative must match.

###### application/json body.source_principal_amount: alternative 1

| 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.

###### application/json body.source_principal_amount: alternative 2

Type: `null`. 

##### application/json body.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.federation

At least one alternative must match.

###### application/json body.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject: alternative 2

Type: `null`. 

##### application/json body.target_amount

At least one alternative must match.

###### application/json body.target_amount: alternative 1

| 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.

###### application/json body.target_amount: alternative 2

Type: `null`. 

##### application/json body.updated_at

At least one alternative must match.

###### application/json body.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.updated_at: alternative 2

Type: `string`. format: date-time


### conversions-get 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.


### conversions-get Response 401 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.


### conversions-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#conversions-get-response-401-schema).


### conversions-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#conversions-get-response-401-schema).


### conversions-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#conversions-get-response-401-schema).


### conversions-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#conversions-get-response-400-schema).


### conversions-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#conversions-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "applied_rate": "0.00002",
    "approval_ref": null,
    "conversion_execution_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "created_at": "2026-05-01T10:00:00Z",
    "failure_detail": null,
    "failure_reason": null,
    "family": "conversion",
    "fee_summary": {
      "components": [
        {
          "amount": {
            "currency": "USD",
            "value": "1.00"
          },
          "kind": "platform_fee"
        }
      ],
      "total": {
        "currency": "USD",
        "value": "1.00"
      }
    },
    "fee_transaction_ids": [
      "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
    ],
    "fill_rate": "0.00002",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "ledger_posted_target_amount": {
      "currency": "BTC",
      "value": "0.00498000"
    },
    "leg_attempt_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "posted_at": "2026-05-01T10:00:00Z",
    "principal_amount": {
      "currency": "USD",
      "value": "250.00"
    },
    "principal_transaction_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "settled_at": "2026-05-01T10:00:00Z",
    "source_gross_amount": {
      "currency": "USD",
      "value": "250.00"
    },
    "source_principal_amount": {
      "currency": "USD",
      "value": "249.00"
    },
    "status": "settled",
    "subject_attribution": {
      "actor": null,
      "approved_by": null,
      "authenticated_principal": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "enterprise_binding": {
        "tenant_type": "enterprise",
        "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "federation": null,
      "identity_source": "platform-managed",
      "initiated_by": null,
      "subject": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      }
    },
    "target_amount": {
      "currency": "BTC",
      "value": "0.00498000"
    },
    "target_currency": "BTC",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /conversions/{conversion_id}/cancel

**Cancel conversion**

**Required capability:** `conversions.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `conversion_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

### conversions-cancel Response 200 schema

Content type: `application/json`.

#### application/json body

| 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})$` |
| `applied_rate` | string or null | Yes |  |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `conversion_execution_id` | string or null | Yes |  |
| `created_at` | string or string | Yes |  |
| `failure_detail` | object or null | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "conversion" | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fee_transaction_ids` | string[] or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `ledger_posted_target_amount` | object or null | Yes |  |
| `leg_attempt_id` | string or null | Yes |  |
| `posted_at` | string or string or null | Yes |  |
| `principal_amount` | object | Yes | No additional fields |
| `principal_transaction_id` | string or null | Yes |  |
| `settled_at` | string or string or null | Yes |  |
| `source_gross_amount` | object or null | Yes |  |
| `source_principal_amount` | object or null | Yes |  |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `target_amount` | object or null | Yes |  |
| `target_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

##### application/json body.applied_rate

At least one alternative must match.

###### application/json body.applied_rate: alternative 1

DecimalString

Type: `string`. pattern: `^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$`

###### application/json body.applied_rate: alternative 2

Type: `null`. 

##### application/json body.approval_ref

At least one alternative must match.

###### application/json body.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body.approval_ref: alternative 2

Type: `null`. 

##### application/json body.compliance_assessment_ref

At least one alternative must match.

###### application/json body.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body.compliance_assessment_ref: alternative 2

Type: `null`. 

##### application/json body.conversion_execution_id

At least one alternative must match.

###### application/json body.conversion_execution_id: alternative 1

Type: `string`. 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)$`

###### application/json body.conversion_execution_id: alternative 2

Type: `null`. 

##### application/json body.created_at

At least one alternative must match.

###### application/json body.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.created_at: alternative 2

Type: `string`. format: date-time

##### application/json body.failure_detail

At least one alternative must match.

###### application/json body.failure_detail: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `failed_at` | string or string or null | Yes |  |
| `reason_code` | string | Yes | pattern: `^[a-z0-9_.:-]+$`; minLength: 1; maxLength: 128 |
| `retryable` | boolean or null | Yes |  |
| `stage` | "pre_execution" / "execution" / "post_fill" / "ledger_posting" / "unknown" | Yes |  |

Additional fields are not accepted.

###### application/json body.failure_detail: alternative 1.failed_at

At least one alternative must match.

###### application/json body.failure_detail: alternative 1.failed_at: alternative 1

At least one alternative must match.

###### application/json body.failure_detail: alternative 1.failed_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.failure_detail: alternative 1.failed_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.failure_detail: alternative 1.failed_at: alternative 2

Type: `null`. 

###### application/json body.failure_detail: alternative 1.retryable

At least one alternative must match.

###### application/json body.failure_detail: alternative 1.retryable: alternative 1

Type: `boolean`. 

###### application/json body.failure_detail: alternative 1.retryable: alternative 2

Type: `null`. 

###### application/json body.failure_detail: alternative 2

Type: `null`. 

##### application/json body.failure_reason

At least one alternative must match.

###### application/json body.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.failure_reason: alternative 2

Type: `null`. 

##### application/json body.fee_summary

At least one alternative must match.

###### application/json body.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body.fee_summary: alternative 1.components item.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.

###### application/json body.fee_summary: alternative 1.total

| 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.

###### application/json body.fee_summary: alternative 2

Type: `null`. 

##### application/json body.fee_transaction_ids

At least one alternative must match.

###### application/json body.fee_transaction_ids: alternative 1

Type: `string[]`. 

###### application/json body.fee_transaction_ids: alternative 1 item

Type: `string`. 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)$`

###### application/json body.fee_transaction_ids: alternative 2

Type: `null`. 

##### application/json body.fill_rate

At least one alternative must match.

###### application/json body.fill_rate: alternative 1

Type: `string`. 

###### application/json body.fill_rate: alternative 2

Type: `null`. 

##### application/json body.ledger_posted_target_amount

At least one alternative must match.

###### application/json body.ledger_posted_target_amount: alternative 1

| 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.

###### application/json body.ledger_posted_target_amount: alternative 2

Type: `null`. 

##### application/json body.leg_attempt_id

At least one alternative must match.

###### application/json body.leg_attempt_id: alternative 1

Type: `string`. 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)$`

###### application/json body.leg_attempt_id: alternative 2

Type: `null`. 

##### application/json body.posted_at

At least one alternative must match.

###### application/json body.posted_at: alternative 1

At least one alternative must match.

###### application/json body.posted_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.posted_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.posted_at: alternative 2

Type: `null`. 

##### application/json body.principal_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.

##### application/json body.principal_transaction_id

At least one alternative must match.

###### application/json body.principal_transaction_id: alternative 1

Type: `string`. 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)$`

###### application/json body.principal_transaction_id: alternative 2

Type: `null`. 

##### application/json body.settled_at

At least one alternative must match.

###### application/json body.settled_at: alternative 1

At least one alternative must match.

###### application/json body.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.settled_at: alternative 2

Type: `null`. 

##### application/json body.source_gross_amount

At least one alternative must match.

###### application/json body.source_gross_amount: alternative 1

| 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.

###### application/json body.source_gross_amount: alternative 2

Type: `null`. 

##### application/json body.source_principal_amount

At least one alternative must match.

###### application/json body.source_principal_amount: alternative 1

| 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.

###### application/json body.source_principal_amount: alternative 2

Type: `null`. 

##### application/json body.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.federation

At least one alternative must match.

###### application/json body.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject: alternative 2

Type: `null`. 

##### application/json body.target_amount

At least one alternative must match.

###### application/json body.target_amount: alternative 1

| 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.

###### application/json body.target_amount: alternative 2

Type: `null`. 

##### application/json body.updated_at

At least one alternative must match.

###### application/json body.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.updated_at: alternative 2

Type: `string`. format: date-time


### conversions-cancel 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.


### conversions-cancel Response 401 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.


### conversions-cancel Response 403 schema

Content type: `application/json`.

See [response 401 schema](#conversions-cancel-response-401-schema).


### conversions-cancel Response 404 schema

Content type: `application/json`.

See [response 401 schema](#conversions-cancel-response-401-schema).


### conversions-cancel Response 409 schema

Content type: `application/json`.

See [response 401 schema](#conversions-cancel-response-401-schema).


### conversions-cancel Response 500 schema

Content type: `application/json`.

See [response 401 schema](#conversions-cancel-response-401-schema).


### conversions-cancel Response 502 schema

Content type: `application/json`.

See [response 400 schema](#conversions-cancel-response-400-schema).


### conversions-cancel Response 503 schema

Content type: `application/json`.

See [response 400 schema](#conversions-cancel-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "applied_rate": null,
    "approval_ref": null,
    "conversion_execution_id": null,
    "created_at": "2026-05-01T10:00:00Z",
    "failure_detail": null,
    "failure_reason": null,
    "family": "conversion",
    "fee_summary": null,
    "fee_transaction_ids": null,
    "fill_rate": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "ledger_posted_target_amount": null,
    "leg_attempt_id": null,
    "posted_at": null,
    "principal_amount": {
      "currency": "USD",
      "value": "250.00"
    },
    "principal_transaction_id": null,
    "settled_at": null,
    "source_gross_amount": null,
    "source_principal_amount": null,
    "status": "cancelled",
    "subject_attribution": {
      "actor": null,
      "approved_by": null,
      "authenticated_principal": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "enterprise_binding": {
        "tenant_type": "enterprise",
        "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "federation": null,
      "identity_source": "platform-managed",
      "initiated_by": null,
      "subject": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      }
    },
    "target_amount": null,
    "target_currency": "BTC",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /conversions/preview

**Preview a conversion**

Returns a non-binding ledger-native conversion preview for display. `economics` names source gross amount, fee summary, source principal amount, indicative rate, and target amount explicitly; `binding` is always false. Preview does not reserve funds, lock a rate, create an executable quote, or resolve external settlement facts. Creating/executing a conversion may recompute fees and rate before ledger posting.

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| 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})$` |
| `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.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 example:**

```json
{
  "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "from_amount": {
    "currency": "USD",
    "value": "250.00"
  },
  "to_currency": "BTC"
}
```

### conversions-preview Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `binding` | false | Yes |  |
| `calculated_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))$` |
| `economics` | object | Yes | No additional fields |
| `execution_min_source_amount` | object or null | Yes |  |
| `expires_at` | string or null | Yes |  |
| `fee_summary` | object | Yes | No additional fields |
| `from_amount` | object | Yes | No additional fields |
| `indicative_price` | object | Yes | No additional fields |
| `min_source_amount` | object | Yes | No additional fields |
| `principal_amount` | object | Yes | No additional fields |
| `to_amount` | object | Yes | No additional fields |

Additional fields are not accepted.

##### application/json body.economics

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `binding` | false | Yes |  |
| `fee_summary` | object | Yes | No additional fields |
| `indicative_rate` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |
| `source_gross_amount` | object | Yes | No additional fields |
| `source_principal_amount` | object | Yes | No additional fields |
| `target_amount` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.economics.fee_summary

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.economics.fee_summary.components

Type: `object[]`. 

###### application/json body.economics.fee_summary.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body.economics.fee_summary.components item.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.

###### application/json body.economics.fee_summary.total

| 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.

###### application/json body.economics.source_gross_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.

###### application/json body.economics.source_principal_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.

###### application/json body.economics.target_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.

##### application/json body.execution_min_source_amount

At least one alternative must match.

###### application/json body.execution_min_source_amount: alternative 1

| 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.

###### application/json body.execution_min_source_amount: alternative 2

Type: `null`. 

##### application/json body.expires_at

At least one alternative must match.

###### application/json body.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.expires_at: alternative 2

Type: `null`. 

##### application/json body.fee_summary

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.fee_summary.components

Type: `object[]`. 

###### application/json body.fee_summary.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `type` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |
| `amount` | object | Yes | No additional fields |
| `payee_ref` | string | Yes | pattern: `^(master-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})$` |

Additional fields are not accepted.

###### application/json body.fee_summary.components item.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.

###### application/json body.fee_summary.total

| 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.

##### application/json body.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.

##### application/json body.indicative_price

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `computed_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))$` |
| `expires_at` | string or null | No |  |
| `price` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |
| `price_type` | "indicative" | Yes |  |
| `provider_hint` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.indicative_price.expires_at

At least one alternative must match.

###### application/json body.indicative_price.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.indicative_price.expires_at: alternative 2

Type: `null`. 

###### application/json body.indicative_price.provider_hint

At least one alternative must match.

###### application/json body.indicative_price.provider_hint: alternative 1

Type: `string`. 

###### application/json body.indicative_price.provider_hint: alternative 2

Type: `null`. 

##### application/json body.min_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.

##### application/json body.principal_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.

##### application/json body.to_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.


### conversions-preview 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.


### conversions-preview Response 401 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.


### conversions-preview Response 403 schema

Content type: `application/json`.

See [response 401 schema](#conversions-preview-response-401-schema).


### conversions-preview Response 409 schema

Content type: `application/json`.

See [response 401 schema](#conversions-preview-response-401-schema).


### conversions-preview Response 422 schema

Content type: `application/json`.

See [response 401 schema](#conversions-preview-response-401-schema).


### conversions-preview Response 500 schema

Content type: `application/json`.

See [response 401 schema](#conversions-preview-response-401-schema).


### conversions-preview Response 502 schema

Content type: `application/json`.

See [response 400 schema](#conversions-preview-response-400-schema).


### conversions-preview Response 503 schema

Content type: `application/json`.

See [response 400 schema](#conversions-preview-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "binding": false,
    "calculated_at": "2026-05-01T10:00:00Z",
    "economics": {
      "binding": false,
      "fee_summary": {
        "components": [
          {
            "amount": {
              "currency": "USD",
              "value": "1.00"
            },
            "kind": "platform_fee"
          }
        ],
        "total": {
          "currency": "USD",
          "value": "1.00"
        }
      },
      "indicative_rate": "0.00002",
      "source_gross_amount": {
        "currency": "USD",
        "value": "250.00"
      },
      "source_principal_amount": {
        "currency": "USD",
        "value": "249.00"
      },
      "target_amount": {
        "currency": "BTC",
        "value": "0.00498000"
      }
    },
    "execution_min_source_amount": {
      "currency": "USD",
      "value": "25.00"
    },
    "expires_at": null,
    "fee_summary": {
      "components": [
        {
          "type": "platform_fee",
          "amount": {
            "currency": "USD",
            "value": "1.00"
          },
          "payee_ref": "master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
        }
      ],
      "total": {
        "currency": "USD",
        "value": "1.00"
      }
    },
    "from_amount": {
      "currency": "USD",
      "value": "250.00"
    },
    "indicative_price": {
      "computed_at": "2026-05-01T10:00:00Z",
      "expires_at": null,
      "price": "0.00002",
      "price_type": "indicative",
      "provider_hint": null
    },
    "min_source_amount": {
      "currency": "USD",
      "value": "25.00"
    },
    "principal_amount": {
      "currency": "USD",
      "value": "249.00"
    },
    "to_amount": {
      "currency": "BTC",
      "value": "0.00498000"
    }
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `422` — The request cannot be processed under the resource or route contract. Depending on the endpoint, code can be not_admissible or unsupported_currency; inspect the documented code and data.reason.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## External Settlement Conversions

### GET /external-settlement-conversions

**List external settlement conversions**

Externally settled conversions are conversions that can be connected to an external settlement source when your enterprise needs that settlement model. Contact your account manager for availability and setup details. Lists externally settled conversion operation snapshots for the required account_ref, with external_settlement_conversions.read coverage on that account. page_size defaults to 100 (1–500); pass next_page_token as page_token for the next page. Responses expose lifecycle state, requested target currency, settlement role, settlement currency, and binding-resolved internal settlement account only. Adapter-private settlement details stay behind the service boundary.

**Required capability:** `external_settlement_conversions.read`

**Authentication:** Bearer token required.

**Parameters:**

- `account_ref` `string` (query) *(required)*
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### external-settlement-conversions-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| 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})$` |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `created_at` | string or string | Yes |  |
| `external_settlement_role` | "external_source_spend" / "external_target_disbursement" | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "external_settlement_conversion" | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `internal_settlement_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})$` |
| `principal_amount` | object | Yes | No additional fields |
| `settled_at` | string or string or null | Yes |  |
| `settlement_checked_at` | string or string | Yes |  |
| `settlement_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `target_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.approval_ref

At least one alternative must match.

###### application/json body.items item.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body.items item.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body.items item.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body.items item.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body.items item.approval_ref: alternative 2

Type: `null`. 

###### application/json body.items item.compliance_assessment_ref

At least one alternative must match.

###### application/json body.items item.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body.items item.compliance_assessment_ref: alternative 2

Type: `null`. 

###### application/json body.items item.created_at

At least one alternative must match.

###### application/json body.items item.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.created_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.failure_reason

At least one alternative must match.

###### application/json body.items item.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.items item.failure_reason: alternative 2

Type: `null`. 

###### application/json body.items item.fee_summary

At least one alternative must match.

###### application/json body.items item.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.items item.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body.items item.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.fee_summary: alternative 1.components item.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.

###### application/json body.items item.fee_summary: alternative 1.total

| 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.

###### application/json body.items item.fee_summary: alternative 2

Type: `null`. 

###### application/json body.items item.fill_rate

At least one alternative must match.

###### application/json body.items item.fill_rate: alternative 1

Type: `string`. 

###### application/json body.items item.fill_rate: alternative 2

Type: `null`. 

###### application/json body.items item.principal_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.

###### application/json body.items item.settled_at

At least one alternative must match.

###### application/json body.items item.settled_at: alternative 1

At least one alternative must match.

###### application/json body.items item.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.settled_at: alternative 2

Type: `null`. 

###### application/json body.items item.settlement_checked_at

At least one alternative must match.

###### application/json body.items item.settlement_checked_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.settlement_checked_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.actor

At least one alternative must match.

###### application/json body.items item.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.approved_by

At least one alternative must match.

###### application/json body.items item.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.items item.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.items item.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.federation

At least one alternative must match.

###### application/json body.items item.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body.items item.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.subject

At least one alternative must match.

###### application/json body.items item.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item.subject_attribution.subject: alternative 2

Type: `null`. 

###### application/json body.items item.updated_at

At least one alternative must match.

###### application/json body.items item.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.updated_at: alternative 2

Type: `string`. format: date-time

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. 

###### application/json body.next_page_token: alternative 2

Type: `null`.


### external-settlement-conversions-list 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.


### external-settlement-conversions-list Response 401 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.


### external-settlement-conversions-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#external-settlement-conversions-list-response-401-schema).


### external-settlement-conversions-list Response 404 schema

Content type: `application/json`.

See [response 401 schema](#external-settlement-conversions-list-response-401-schema).


### external-settlement-conversions-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#external-settlement-conversions-list-response-401-schema).


### external-settlement-conversions-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#external-settlement-conversions-list-response-400-schema).


### external-settlement-conversions-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#external-settlement-conversions-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "approval_ref": null,
        "created_at": "2026-05-01T10:00:00Z",
        "external_settlement_role": "external_source_spend",
        "failure_reason": null,
        "family": "external_settlement_conversion",
        "fee_summary": {
          "components": [
            {
              "amount": {
                "currency": "USDC",
                "value": "1.00"
              },
              "kind": "network_fee"
            }
          ],
          "total": {
            "currency": "USDC",
            "value": "1.00"
          }
        },
        "fill_rate": null,
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "internal_settlement_account_ref": "master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "principal_amount": {
          "currency": "EUR",
          "value": "250.00"
        },
        "settled_at": null,
        "settlement_checked_at": "2026-05-01T10:00:00Z",
        "settlement_currency": "EUR",
        "status": "admissible",
        "subject_attribution": {
          "actor": null,
          "approved_by": null,
          "authenticated_principal": {
            "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
            "kind": "user",
            "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
          },
          "enterprise_binding": {
            "tenant_type": "enterprise",
            "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
          },
          "federation": null,
          "identity_source": "platform-managed",
          "initiated_by": null,
          "subject": {
            "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
            "kind": "user",
            "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
          }
        },
        "target_currency": "BTC",
        "updated_at": "2026-05-01T10:00:00Z"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /external-settlement-conversions

**Create external settlement conversion**

Externally settled conversions are conversions that can be connected to an external settlement source when your enterprise needs that settlement model. Contact your account manager for availability and setup details. Creates an explicit externally settled conversion. The strict request supplies `account_ref`, `source_amount` as `{value, currency}`, `target_currency`, and required `external_settlement_role`; settlement routing is binding-resolved by the platform. The account schema accepts AccountRef, but this command currently requires a client account with a matching external-settlement binding; master-account input is denied with 422. `external_source_spend` resolves the source currency externally, while `external_target_disbursement` resolves the target currency externally; the role is never inferred from the asset class. Idempotency-Key takes precedence over optional body client_idempotency_key; omitting both generates a key without caller-controlled replay. The response is the typed operation read projection, not raw family parameters. Callers with an effective human subject must obtain confirmation via `POST /action-tokens` using action `external_settlement_conversion.create` plus the structured command (or a matching command_digest), then send X-Action-Token. Service principals are exempt. The public edge does not accept delegated actor-token exchange or on-behalf-of headers. The 202 response is read after creation, so the caller also needs external_settlement_conversions.read or operations.recovery coverage on the account to receive it; otherwise creation may succeed before the response read returns 404. Policy/settlement denial returns not_admissible (422); unavailable settlement facts return temporarily_unavailable (503).

**Required capability:** `external_settlement_conversions.create`

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.
- `X-Action-Token` `string` (header) — Single-use step-up confirmation token bound to the server-canonical command for this request. Required when the effective subject is a human user. Callers without a human subject skip only this confirmation check and still pass normal authentication and capability guards. Obtain the token through `POST /action-tokens`, then submit it with the guarded request. Structured commands are supported for withdrawal, conversion, and external-settlement conversion creation; the issue endpoint also accepts `command_digest`. Missing or invalid human-confirmation tokens produce `400` with `code` in {`action_token_required`, `action_token_rejected`}; an unreachable approval service produces `502 action_token_validation_failed`.

**Request body** (`application/json`):

### Request body schema

| 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.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 example:**

```json
{
  "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "external_settlement_role": "external_source_spend",
  "source_amount": {
    "currency": "EUR",
    "value": "250.00"
  },
  "target_currency": "BTC"
}
```

### external-settlement-conversions-create Response 202 schema

Content type: `application/json`.

#### application/json body

| 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})$` |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `created_at` | string or string | Yes |  |
| `external_settlement_role` | "external_source_spend" / "external_target_disbursement" | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "external_settlement_conversion" | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `internal_settlement_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})$` |
| `principal_amount` | object | Yes | No additional fields |
| `settled_at` | string or string or null | Yes |  |
| `settlement_checked_at` | string or string | Yes |  |
| `settlement_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `target_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

##### application/json body.approval_ref

At least one alternative must match.

###### application/json body.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body.approval_ref: alternative 2

Type: `null`. 

##### application/json body.compliance_assessment_ref

At least one alternative must match.

###### application/json body.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body.compliance_assessment_ref: alternative 2

Type: `null`. 

##### application/json body.created_at

At least one alternative must match.

###### application/json body.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.created_at: alternative 2

Type: `string`. format: date-time

##### application/json body.failure_reason

At least one alternative must match.

###### application/json body.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.failure_reason: alternative 2

Type: `null`. 

##### application/json body.fee_summary

At least one alternative must match.

###### application/json body.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body.fee_summary: alternative 1.components item.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.

###### application/json body.fee_summary: alternative 1.total

| 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.

###### application/json body.fee_summary: alternative 2

Type: `null`. 

##### application/json body.fill_rate

At least one alternative must match.

###### application/json body.fill_rate: alternative 1

Type: `string`. 

###### application/json body.fill_rate: alternative 2

Type: `null`. 

##### application/json body.principal_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.

##### application/json body.settled_at

At least one alternative must match.

###### application/json body.settled_at: alternative 1

At least one alternative must match.

###### application/json body.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.settled_at: alternative 2

Type: `null`. 

##### application/json body.settlement_checked_at

At least one alternative must match.

###### application/json body.settlement_checked_at: alternative 1

Type: `string`. 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))$`

###### application/json body.settlement_checked_at: alternative 2

Type: `string`. format: date-time

##### application/json body.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.federation

At least one alternative must match.

###### application/json body.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject: alternative 2

Type: `null`. 

##### application/json body.updated_at

At least one alternative must match.

###### application/json body.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.updated_at: alternative 2

Type: `string`. format: date-time


### external-settlement-conversions-create 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 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.


### external-settlement-conversions-create Response 401 schema

Content type: `application/json`.

See [response 400 schema](#external-settlement-conversions-create-response-400-schema).


### external-settlement-conversions-create Response 403 schema

Content type: `application/json`.

See [response 400 schema](#external-settlement-conversions-create-response-400-schema).


### external-settlement-conversions-create Response 404 schema

Content type: `application/json`.

See [response 400 schema](#external-settlement-conversions-create-response-400-schema).


### external-settlement-conversions-create Response 409 schema

Content type: `application/json`.

See [response 400 schema](#external-settlement-conversions-create-response-400-schema).


### external-settlement-conversions-create Response 422 schema

Content type: `application/json`.

See [response 400 schema](#external-settlement-conversions-create-response-400-schema).


### external-settlement-conversions-create Response 500 schema

Content type: `application/json`.

See [response 400 schema](#external-settlement-conversions-create-response-400-schema).


### external-settlement-conversions-create Response 502 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.


### external-settlement-conversions-create Response 503 schema

Content type: `application/json`.

See [response 502 schema](#external-settlement-conversions-create-response-502-schema).


**Responses:**

- `202` — Request accepted for asynchronous processing. Follow the resource identifiers returned by this operation to observe progress.

  ```json
  {
    "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "approval_ref": null,
    "created_at": "2026-05-01T10:00:00Z",
    "external_settlement_role": "external_source_spend",
    "failure_reason": null,
    "family": "external_settlement_conversion",
    "fee_summary": {
      "components": [
        {
          "amount": {
            "currency": "USDC",
            "value": "1.00"
          },
          "kind": "network_fee"
        }
      ],
      "total": {
        "currency": "USDC",
        "value": "1.00"
      }
    },
    "fill_rate": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "internal_settlement_account_ref": "master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "principal_amount": {
      "currency": "EUR",
      "value": "250.00"
    },
    "settled_at": null,
    "settlement_checked_at": "2026-05-01T10:00:00Z",
    "settlement_currency": "EUR",
    "status": "admissible",
    "subject_attribution": {
      "actor": null,
      "approved_by": null,
      "authenticated_principal": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "enterprise_binding": {
        "tenant_type": "enterprise",
        "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "federation": null,
      "identity_source": "platform-managed",
      "initiated_by": null,
      "subject": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      }
    },
    "target_currency": "BTC",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Step-up confirmation failed for a money-movement operation. `code` is one of: `action_token_required` (X-Action-Token header missing), `action_token_rejected` (token is unknown, expired, already consumed, or its server-canonical command binding does not match the current request). Obtain a fresh token via `POST /action-tokens` and retry. Structured issuance accepts `withdrawal.create`, `conversion.create`, and `external_settlement_conversion.create`. The issue endpoint also accepts `command_digest`. Human confirmation applies to the effective user subject; callers without a human subject skip this confirmation check.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `422` — The request cannot be processed under the resource or route contract. Depending on the endpoint, code can be not_admissible or unsupported_currency; inspect the documented code and data.reason.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /external-settlement-conversions/{external_settlement_conversion_id}

**Get external settlement conversion**

Externally settled conversions are conversions that can be connected to an external settlement source when your enterprise needs that settlement model. Contact your account manager for availability and setup details. Returns the typed external settlement conversion operation snapshot. An absent operation, another operation family, or missing read/recovery scope coverage returns 404. The public shape contains sanitized settlement-role evidence only and never raw operation family parameters.

**Required capability:** `external_settlement_conversions.read`

**Authentication:** Bearer token required.

**Parameters:**

- `external_settlement_conversion_id` `string` (path) *(required)*

### external-settlement-conversions-get Response 200 schema

Content type: `application/json`.

#### application/json body

| 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})$` |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `created_at` | string or string | Yes |  |
| `external_settlement_role` | "external_source_spend" / "external_target_disbursement" | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "external_settlement_conversion" | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `internal_settlement_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})$` |
| `principal_amount` | object | Yes | No additional fields |
| `settled_at` | string or string or null | Yes |  |
| `settlement_checked_at` | string or string | Yes |  |
| `settlement_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `target_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

##### application/json body.approval_ref

At least one alternative must match.

###### application/json body.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body.approval_ref: alternative 2

Type: `null`. 

##### application/json body.compliance_assessment_ref

At least one alternative must match.

###### application/json body.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body.compliance_assessment_ref: alternative 2

Type: `null`. 

##### application/json body.created_at

At least one alternative must match.

###### application/json body.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.created_at: alternative 2

Type: `string`. format: date-time

##### application/json body.failure_reason

At least one alternative must match.

###### application/json body.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.failure_reason: alternative 2

Type: `null`. 

##### application/json body.fee_summary

At least one alternative must match.

###### application/json body.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body.fee_summary: alternative 1.components item.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.

###### application/json body.fee_summary: alternative 1.total

| 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.

###### application/json body.fee_summary: alternative 2

Type: `null`. 

##### application/json body.fill_rate

At least one alternative must match.

###### application/json body.fill_rate: alternative 1

Type: `string`. 

###### application/json body.fill_rate: alternative 2

Type: `null`. 

##### application/json body.principal_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.

##### application/json body.settled_at

At least one alternative must match.

###### application/json body.settled_at: alternative 1

At least one alternative must match.

###### application/json body.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.settled_at: alternative 2

Type: `null`. 

##### application/json body.settlement_checked_at

At least one alternative must match.

###### application/json body.settlement_checked_at: alternative 1

Type: `string`. 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))$`

###### application/json body.settlement_checked_at: alternative 2

Type: `string`. format: date-time

##### application/json body.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.federation

At least one alternative must match.

###### application/json body.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject: alternative 2

Type: `null`. 

##### application/json body.updated_at

At least one alternative must match.

###### application/json body.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.updated_at: alternative 2

Type: `string`. format: date-time


### external-settlement-conversions-get 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.


### external-settlement-conversions-get Response 401 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.


### external-settlement-conversions-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#external-settlement-conversions-get-response-401-schema).


### external-settlement-conversions-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#external-settlement-conversions-get-response-401-schema).


### external-settlement-conversions-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#external-settlement-conversions-get-response-401-schema).


### external-settlement-conversions-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#external-settlement-conversions-get-response-400-schema).


### external-settlement-conversions-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#external-settlement-conversions-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "approval_ref": null,
    "created_at": "2026-05-01T10:00:00Z",
    "external_settlement_role": "external_source_spend",
    "failure_reason": null,
    "family": "external_settlement_conversion",
    "fee_summary": {
      "components": [
        {
          "amount": {
            "currency": "USDC",
            "value": "1.00"
          },
          "kind": "network_fee"
        }
      ],
      "total": {
        "currency": "USDC",
        "value": "1.00"
      }
    },
    "fill_rate": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "internal_settlement_account_ref": "master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "principal_amount": {
      "currency": "EUR",
      "value": "250.00"
    },
    "settled_at": null,
    "settlement_checked_at": "2026-05-01T10:00:00Z",
    "settlement_currency": "EUR",
    "status": "admissible",
    "subject_attribution": {
      "actor": null,
      "approved_by": null,
      "authenticated_principal": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "enterprise_binding": {
        "tenant_type": "enterprise",
        "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "federation": null,
      "identity_source": "platform-managed",
      "initiated_by": null,
      "subject": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      }
    },
    "target_currency": "BTC",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Fee Previews

### POST /fee-previews

**Preview a fee**

Returns a non-binding fee preview for a planned operation. `subject_ref` must identify a client, client account, enterprise, or master account within the caller's bound tenant scope (`clients/<uuid>`, `client-accounts/<uuid>`, `enterprises/<uuid>`, or `master-accounts/<uuid>`). Pricing uses `principal_amount`, `service_type`, and the agreements active at `requested_at` (the current time when omitted). `settlement_amount` is accepted but does not currently affect the calculation. The response is wrapped in a `fee_preview` envelope; no fee-specific capability is required, but authentication and tenant scope checks still apply.

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `operation_type` | "withdrawal_crypto" / "withdrawal_fiat" / "deposit_crypto" / "deposit_fiat" / "internal_transfer" / "conversion" | Yes |  |
| `principal_amount` | object | Yes | No additional fields |
| `requested_at` | string | No | 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))$` |
| `service_type` | "custody" / "conversion" / "withdrawal_crypto" / "withdrawal_fiat" / "deposit_crypto" / "deposit_fiat" / "internal_transfer" / "staking" | Yes |  |
| `settlement_amount` | object or null | No |  |
| `subject_ref` | string | Yes | pattern: `^(clients\|client-accounts\|enterprises\|master-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})$` |

Additional fields are not accepted.

#### Request body schema.principal_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.settlement_amount

At least one alternative must match.

##### Request body schema.settlement_amount: alternative 1

| 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.settlement_amount: alternative 2

Type: `null`.

**Request example:**

```json
{
  "operation_type": "withdrawal_crypto",
  "principal_amount": {
    "currency": "USDC",
    "value": "100.00"
  },
  "requested_at": "2026-05-01T10:00:00Z",
  "service_type": "withdrawal_crypto",
  "settlement_amount": null,
  "subject_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}
```

### fee-previews-create Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `fee_preview` | object | Yes | No additional fields |

Additional fields are not accepted.

##### application/json body.fee_preview

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `binding` | "non_binding" | Yes |  |
| `computed_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))$` |
| `enterprise_ca_version` | integer or null | Yes |  |
| `fee_summary` | object | Yes | No additional fields |
| `operation_type` | "withdrawal_crypto" / "withdrawal_fiat" / "deposit_crypto" / "deposit_fiat" / "internal_transfer" / "conversion" | Yes |  |
| `platform_ca_version` | integer or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fee_preview.enterprise_ca_version

At least one alternative must match.

###### application/json body.fee_preview.enterprise_ca_version: alternative 1

Type: `integer`. maximum: 9007199254740991; exclusiveMinimum: 0

###### application/json body.fee_preview.enterprise_ca_version: alternative 2

Type: `null`. 

###### application/json body.fee_preview.fee_summary

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.fee_preview.fee_summary.components

Type: `object[]`. 

###### application/json body.fee_preview.fee_summary.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `type` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |
| `amount` | object | Yes | No additional fields |
| `payee_ref` | string | Yes | pattern: `^(master-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})$` |

Additional fields are not accepted.

###### application/json body.fee_preview.fee_summary.components item.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.

###### application/json body.fee_preview.fee_summary.total

| 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.

###### application/json body.fee_preview.platform_ca_version

At least one alternative must match.

###### application/json body.fee_preview.platform_ca_version: alternative 1

Type: `integer`. maximum: 9007199254740991; exclusiveMinimum: 0

###### application/json body.fee_preview.platform_ca_version: alternative 2

Type: `null`.


### fee-previews-create 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.


### fee-previews-create Response 401 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.


### fee-previews-create Response 403 schema

Content type: `application/json`.

See [response 401 schema](#fee-previews-create-response-401-schema).


### fee-previews-create Response 404 schema

Content type: `application/json`.

See [response 401 schema](#fee-previews-create-response-401-schema).


### fee-previews-create Response 409 schema

Content type: `application/json`.

See [response 401 schema](#fee-previews-create-response-401-schema).


### fee-previews-create Response 500 schema

Content type: `application/json`.

See [response 401 schema](#fee-previews-create-response-401-schema).


### fee-previews-create Response 502 schema

Content type: `application/json`.

See [response 400 schema](#fee-previews-create-response-400-schema).


### fee-previews-create Response 503 schema

Content type: `application/json`.

See [response 400 schema](#fee-previews-create-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "fee_preview": {
      "binding": "non_binding",
      "computed_at": "2026-05-01T10:00:00Z",
      "enterprise_ca_version": 2,
      "fee_summary": {
        "components": [
          {
            "type": "platform_fee",
            "amount": {
              "currency": "USDC",
              "value": "1.00"
            },
            "payee_ref": "master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
          }
        ],
        "total": {
          "currency": "USDC",
          "value": "1.00"
        }
      },
      "operation_type": "withdrawal_crypto",
      "platform_ca_version": 1
    }
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Prices

### GET /prices/assets

**Get per-asset prices**

Returns the current price of each requested asset expressed in `quote_asset`, plus the absolute change over a trailing 24-hour window. `assets` is a comma-separated list (max 50). `account_ref` requires a bound enterprise or client operating scope; missing/platform bindings are refused with 403 and an account outside that scope is hidden with 404. Asset codes are trimmed, uppercased and deduplicated; quote_asset is trimmed and uppercased. The price is account-scoped: the price is produced by the same pricing source that prices a conversion for that account, and the 24h change is attributed to the venue resolved for that account and pair. `change_24h` is `null` — never `0` — whenever the change cannot be established honestly (the venue publishes no rolling 24-hour reference price, the pair routes to the internal book, or the venue stats call failed); a `null` must not be rendered as a flat market. Assets that could not be priced are listed under `unavailable` with a machine-readable reason instead of being silently dropped. This response is informational only; execution must request pricing again.

**Authentication:** Bearer token required.

**Parameters:**

- `assets` `string` (query) *(required)*
- `quote_asset` `string` (query) *(required)*
- `account_ref` `string` (query) *(required)*

### prices-assets Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `prices` | object[] | Yes |  |
| `quote_asset` | string | Yes | minLength: 1 |
| `unavailable` | object[] | Yes |  |

Additional fields are not accepted.

##### application/json body.prices

Type: `object[]`. 

###### application/json body.prices item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | minLength: 1 |
| `calculated_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))$` |
| `change_24h` | string or null | Yes |  |
| `change_source` | string or null | Yes |  |
| `price` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |
| `price_source` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.prices item.change_24h

At least one alternative must match.

###### application/json body.prices item.change_24h: alternative 1

SignedDecimalString

Type: `string`. pattern: `^-?(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$`

###### application/json body.prices item.change_24h: alternative 2

Type: `null`. 

###### application/json body.prices item.change_source

At least one alternative must match.

###### application/json body.prices item.change_source: alternative 1

Type: `string`. 

###### application/json body.prices item.change_source: alternative 2

Type: `null`. 

###### application/json body.prices item.price_source

At least one alternative must match.

###### application/json body.prices item.price_source: alternative 1

Type: `string`. 

###### application/json body.prices item.price_source: alternative 2

Type: `null`. 

##### application/json body.unavailable

Type: `object[]`. 

###### application/json body.unavailable item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | minLength: 1 |
| `reason` | "unknown_pair" / "pricing_unavailable" | Yes |  |

Additional fields are not accepted.


### prices-assets 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.


### prices-assets Response 401 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.


### prices-assets Response 403 schema

Content type: `application/json`.

See [response 401 schema](#prices-assets-response-401-schema).


### prices-assets Response 404 schema

Content type: `application/json`.

See [response 401 schema](#prices-assets-response-401-schema).


### prices-assets Response 500 schema

Content type: `application/json`.

See [response 401 schema](#prices-assets-response-401-schema).


### prices-assets Response 502 schema

Content type: `application/json`.

See [response 400 schema](#prices-assets-response-400-schema).


### prices-assets Response 503 schema

Content type: `application/json`.

See [response 400 schema](#prices-assets-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "prices": [
      {
        "asset": "BTC",
        "calculated_at": "2026-05-01T10:00:00Z",
        "change_24h": "-1204.31",
        "change_source": "binance:BTCUSDC",
        "price": "65789.47",
        "price_source": "binance:ws:via_usdc"
      },
      {
        "asset": "ETH",
        "calculated_at": "2026-05-01T10:00:00Z",
        "change_24h": null,
        "change_source": null,
        "price": "3421.08",
        "price_source": "binance:ws:via_usdc"
      }
    ],
    "quote_asset": "USD",
    "unavailable": [
      {
        "asset": "SOL",
        "reason": "unknown_pair"
      }
    ]
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /prices/indicative

**Get indicative price**

Returns the raw non-binding exchange pricing envelope for a from-asset/to-asset pair. Supply exactly the positive anchored amount: `from_amount` when `amount_basis=from`, or `to_amount` when `amount_basis=to`; omit the other amount. `indicative_price.price` is the to-asset amount per unit of from-asset. `account_ref` requires a bound enterprise or client operating scope; missing/platform bindings are refused with 403 and an account outside that scope is hidden with 404. This response is informational only; execution must request pricing again.

**Authentication:** Bearer token required.

**Parameters:**

- `from_asset` `string` (query) *(required)*
- `to_asset` `string` (query) *(required)*
- `amount_basis` `string` (query) *(required)*
- `from_amount` `string` (query)
- `to_amount` `string` (query)
- `account_ref` `string` (query) *(required)*

### prices-indicative Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount_basis` | "from" / "to" | Yes |  |
| `binding` | false | Yes |  |
| `calculated_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))$` |
| `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))$` |
| `flow_type` | "conversion" | Yes |  |
| `from_amount` | object | Yes | No additional fields |
| `from_asset` | string | Yes | minLength: 1 |
| `indicative_price` | object | Yes | No additional fields |
| `pricing_mode` | "indicative" | Yes |  |
| `to_amount` | object | Yes | No additional fields |
| `to_asset` | string | Yes | minLength: 1 |

Additional fields are not accepted.

##### application/json body.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.

##### application/json body.indicative_price

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `computed_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))$` |
| `expires_at` | string or null | No |  |
| `price` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |
| `price_type` | "indicative" | Yes |  |
| `provider_hint` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.indicative_price.expires_at

At least one alternative must match.

###### application/json body.indicative_price.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.indicative_price.expires_at: alternative 2

Type: `null`. 

###### application/json body.indicative_price.provider_hint

At least one alternative must match.

###### application/json body.indicative_price.provider_hint: alternative 1

Type: `string`. 

###### application/json body.indicative_price.provider_hint: alternative 2

Type: `null`. 

##### application/json body.to_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.


### prices-indicative 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.


### prices-indicative Response 401 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.


### prices-indicative Response 403 schema

Content type: `application/json`.

See [response 401 schema](#prices-indicative-response-401-schema).


### prices-indicative Response 404 schema

Content type: `application/json`.

See [response 401 schema](#prices-indicative-response-401-schema).


### prices-indicative Response 500 schema

Content type: `application/json`.

See [response 401 schema](#prices-indicative-response-401-schema).


### prices-indicative Response 502 schema

Content type: `application/json`.

See [response 400 schema](#prices-indicative-response-400-schema).


### prices-indicative Response 503 schema

Content type: `application/json`.

See [response 400 schema](#prices-indicative-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "amount_basis": "from",
    "binding": false,
    "calculated_at": "2026-05-01T10:00:00Z",
    "expires_at": "2026-05-01T10:01:00.000Z",
    "flow_type": "conversion",
    "from_amount": {
      "currency": "USDC",
      "value": "250.00"
    },
    "from_asset": "USDC",
    "indicative_price": {
      "computed_at": "2026-05-01T10:00:00Z",
      "price": "0.0000152",
      "price_type": "indicative"
    },
    "pricing_mode": "indicative",
    "to_amount": {
      "currency": "BTC",
      "value": "0.00380000"
    },
    "to_asset": "BTC"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## User Invitations

### GET /user-invitations

**List user invitations**

Lists user invitations under an enterprise scope.

**Required capability:** `users.read`

**Authentication:** Bearer token required.

**Parameters:**

- `enterprise_ref` `string` (query) *(required)*
- `status` `string` (query)
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### user-invitations-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `accepted_at` | string or null | Yes |  |
| `cancelled_at` | string or null | Yes |  |
| `created_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))$` |
| `email_constraint` | string | Yes | format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`; maxLength: 254 |
| `enterprise_ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |
| `etag` | string | Yes | minLength: 1 |
| `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))$` |
| `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)$` |
| `invited_by` | string | Yes | pattern: `^(users\|service-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})$` |
| `pending_human_actor_ref` | string | Yes | pattern: `^(users)\/([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})$` |
| `role` | string | Yes | pattern: `^(roles)\/([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})$` |
| `scope` | string or string | Yes |  |
| `status` | "pending" / "accepting" / "accepted" / "expired" / "cancelled" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

###### application/json body.items item.accepted_at

At least one alternative must match.

###### application/json body.items item.accepted_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.accepted_at: alternative 2

Type: `null`. 

###### application/json body.items item.cancelled_at

At least one alternative must match.

###### application/json body.items item.cancelled_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.cancelled_at: alternative 2

Type: `null`. 

###### application/json body.items item.scope

At least one alternative must match.

###### application/json body.items item.scope: alternative 1

Type: `string`. pattern: `^(enterprises)\/([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})$`

###### application/json body.items item.scope: alternative 2

Type: `string`. pattern: `^(clients)\/([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})$`

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. 

###### application/json body.next_page_token: alternative 2

Type: `null`.


### user-invitations-list 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.


### user-invitations-list Response 401 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.


### user-invitations-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#user-invitations-list-response-401-schema).


### user-invitations-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#user-invitations-list-response-401-schema).


### user-invitations-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#user-invitations-list-response-400-schema).


### user-invitations-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#user-invitations-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "accepted_at": null,
        "cancelled_at": null,
        "created_at": "2026-05-01T10:00:00Z",
        "email_constraint": "jane.doe@acme.example",
        "enterprise_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
        "expires_at": "2026-05-02T10:00:00Z",
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "invited_by": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "pending_human_actor_ref": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "role": "roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "scope": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "status": "pending",
        "updated_at": "2026-05-01T10:00:00Z"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /user-invitations

**Create user invitation**

Reserves a pending user and grants its role immediately; the assignment becomes usable when the actor is activated. The inviter must belong to the owning enterprise and be allowed to grant the selected role over the scope subtree. An existing pending invitation for the same scope and email is refreshed and returns status `resent`. When no pending invitation exists and that email already belongs to a user under the selected scope, creation returns `409 state_conflict` with `data.reason=email_already_used_under_parent`; it does not add an invitation to an existing active user. Hosted first access sends the one-time challenge only in a magic-link email; public invitation responses never include challenge_ref. `enterprise_idp` first access creates no hosted challenge or email and completes through `POST /users/{user_id}/activate-federated`.

**Required capability:** `users.invite`

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `display_name` | string or null | No |  |
| `email` | string | Yes | format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`; maxLength: 254 |
| `role` | string | Yes | pattern: `^(roles)\/([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})$` |
| `scope` | string or string | Yes |  |

Additional fields are not accepted.

#### Request body schema.display_name

At least one alternative must match.

##### Request body schema.display_name: alternative 1

Type: `string`. minLength: 1; maxLength: 255

##### Request body schema.display_name: alternative 2

Type: `null`. 

#### Request body schema.scope

At least one alternative must match.

##### Request body schema.scope: alternative 1

Type: `string`. pattern: `^(enterprises)\/([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})$`

##### Request body schema.scope: alternative 2

Type: `string`. pattern: `^(clients)\/([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})$`

**Request example:**

```json
{
  "display_name": "Jane Doe",
  "email": "jane.doe@acme.example",
  "role": "roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "scope": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}
```

### user-invitations-create Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `invitation` | object | Yes | No additional fields |
| `status` | "pending" / "resent" | Yes |  |

Additional fields are not accepted.

##### application/json body.invitation

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `accepted_at` | string or null | Yes |  |
| `cancelled_at` | string or null | Yes |  |
| `created_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))$` |
| `email_constraint` | string | Yes | format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`; maxLength: 254 |
| `enterprise_ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |
| `etag` | string | Yes | minLength: 1 |
| `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))$` |
| `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)$` |
| `invited_by` | string | Yes | pattern: `^(users\|service-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})$` |
| `pending_human_actor_ref` | string | Yes | pattern: `^(users)\/([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})$` |
| `role` | string | Yes | pattern: `^(roles)\/([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})$` |
| `scope` | string or string | Yes |  |
| `status` | "pending" / "accepting" / "accepted" / "expired" / "cancelled" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

###### application/json body.invitation.accepted_at

At least one alternative must match.

###### application/json body.invitation.accepted_at: alternative 1

Type: `string`. 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))$`

###### application/json body.invitation.accepted_at: alternative 2

Type: `null`. 

###### application/json body.invitation.cancelled_at

At least one alternative must match.

###### application/json body.invitation.cancelled_at: alternative 1

Type: `string`. 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))$`

###### application/json body.invitation.cancelled_at: alternative 2

Type: `null`. 

###### application/json body.invitation.scope

At least one alternative must match.

###### application/json body.invitation.scope: alternative 1

Type: `string`. pattern: `^(enterprises)\/([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})$`

###### application/json body.invitation.scope: alternative 2

Type: `string`. pattern: `^(clients)\/([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})$`


### user-invitations-create 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.


### user-invitations-create Response 401 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.


### user-invitations-create Response 403 schema

Content type: `application/json`.

See [response 401 schema](#user-invitations-create-response-401-schema).


### user-invitations-create Response 404 schema

Content type: `application/json`.

See [response 401 schema](#user-invitations-create-response-401-schema).


### user-invitations-create Response 409 schema

Content type: `application/json`.

See [response 401 schema](#user-invitations-create-response-401-schema).


### user-invitations-create Response 500 schema

Content type: `application/json`.

See [response 401 schema](#user-invitations-create-response-401-schema).


### user-invitations-create Response 502 schema

Content type: `application/json`.

See [response 400 schema](#user-invitations-create-response-400-schema).


### user-invitations-create Response 503 schema

Content type: `application/json`.

See [response 400 schema](#user-invitations-create-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "invitation": {
      "accepted_at": null,
      "cancelled_at": null,
      "created_at": "2026-05-01T10:00:00Z",
      "email_constraint": "jane.doe@acme.example",
      "enterprise_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
      "expires_at": "2026-05-02T10:00:00Z",
      "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "invited_by": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "pending_human_actor_ref": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "role": "roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "scope": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "status": "pending",
      "updated_at": "2026-05-01T10:00:00Z"
    },
    "status": "pending"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /user-invitations/{invitation_id}

**Get user invitation**

**Required capability:** `users.read`

**Authentication:** Bearer token required.

**Parameters:**

- `invitation_id` `string` (path) *(required)*

### user-invitations-get Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `accepted_at` | string or null | Yes |  |
| `cancelled_at` | string or null | Yes |  |
| `created_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))$` |
| `email_constraint` | string | Yes | format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`; maxLength: 254 |
| `enterprise_ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |
| `etag` | string | Yes | minLength: 1 |
| `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))$` |
| `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)$` |
| `invited_by` | string | Yes | pattern: `^(users\|service-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})$` |
| `pending_human_actor_ref` | string | Yes | pattern: `^(users)\/([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})$` |
| `role` | string | Yes | pattern: `^(roles)\/([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})$` |
| `scope` | string or string | Yes |  |
| `status` | "pending" / "accepting" / "accepted" / "expired" / "cancelled" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.accepted_at

At least one alternative must match.

###### application/json body.accepted_at: alternative 1

Type: `string`. 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))$`

###### application/json body.accepted_at: alternative 2

Type: `null`. 

##### application/json body.cancelled_at

At least one alternative must match.

###### application/json body.cancelled_at: alternative 1

Type: `string`. 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))$`

###### application/json body.cancelled_at: alternative 2

Type: `null`. 

##### application/json body.scope

At least one alternative must match.

###### application/json body.scope: alternative 1

Type: `string`. pattern: `^(enterprises)\/([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})$`

###### application/json body.scope: alternative 2

Type: `string`. pattern: `^(clients)\/([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})$`


### user-invitations-get 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.


### user-invitations-get Response 401 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.


### user-invitations-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#user-invitations-get-response-401-schema).


### user-invitations-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#user-invitations-get-response-401-schema).


### user-invitations-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#user-invitations-get-response-401-schema).


### user-invitations-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#user-invitations-get-response-400-schema).


### user-invitations-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#user-invitations-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "accepted_at": null,
    "cancelled_at": null,
    "created_at": "2026-05-01T10:00:00Z",
    "email_constraint": "jane.doe@acme.example",
    "enterprise_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
    "expires_at": "2026-05-02T10:00:00Z",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "invited_by": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "pending_human_actor_ref": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "role": "roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "scope": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "pending",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /user-invitations/accept

**Accept user invitation**

Public hosted-accept endpoint: no Bearer token is required. Submit `invitation_id` and the one-time `challenge_ref` from the magic-link email. Accept activates the reserved user and its already-granted role and returns an accepted invitation plus a short-lived `session_token`. This credential response is never cached or replayed, even with Idempotency-Key, and the challenge is single-use: repeating an accept that already succeeded, for example after the response was lost, returns `409 state_conflict` with `data.reason=invitation_already_terminal` instead of a second session. The account is already active, so the user signs in normally instead. That token is a federated session assertion: exchange it as `subject_token` at `POST /oauth/token` with `grant_type=urn:ietf:params:oauth:grant-type:token-exchange` before calling protected API routes. Production returns `409 state_conflict` with `data.reason=not_supported`; enterprise_idp first access uses `POST /users/{user_id}/activate-federated` instead.

**Authentication:** No bearer token required.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `challenge_ref` | string | Yes | minLength: 1; maxLength: 256 |
| `invitation_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 example:**

```json
{
  "challenge_ref": "challenge-ref-0001",
  "invitation_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}
```

### user-invitations-accept Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor_scope_ref` | string or string | Yes |  |
| `enterprise_ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |
| `invitation` | object | Yes | No additional fields |
| `session_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))$` |
| `session_token` | string | Yes | minLength: 1 |

Additional fields are not accepted.

##### application/json body.actor_scope_ref

At least one alternative must match.

###### application/json body.actor_scope_ref: alternative 1

Type: `string`. pattern: `^(enterprises)\/([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})$`

###### application/json body.actor_scope_ref: alternative 2

Type: `string`. pattern: `^(clients)\/([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})$`

##### application/json body.invitation

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `accepted_at` | string or null | Yes |  |
| `cancelled_at` | string or null | Yes |  |
| `created_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))$` |
| `email_constraint` | string | Yes | format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`; maxLength: 254 |
| `enterprise_ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |
| `etag` | string | Yes | minLength: 1 |
| `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))$` |
| `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)$` |
| `invited_by` | string | Yes | pattern: `^(users\|service-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})$` |
| `pending_human_actor_ref` | string | Yes | pattern: `^(users)\/([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})$` |
| `role` | string | Yes | pattern: `^(roles)\/([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})$` |
| `scope` | string or string | Yes |  |
| `status` | "pending" / "accepting" / "accepted" / "expired" / "cancelled" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

###### application/json body.invitation.accepted_at

At least one alternative must match.

###### application/json body.invitation.accepted_at: alternative 1

Type: `string`. 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))$`

###### application/json body.invitation.accepted_at: alternative 2

Type: `null`. 

###### application/json body.invitation.cancelled_at

At least one alternative must match.

###### application/json body.invitation.cancelled_at: alternative 1

Type: `string`. 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))$`

###### application/json body.invitation.cancelled_at: alternative 2

Type: `null`. 

###### application/json body.invitation.scope

At least one alternative must match.

###### application/json body.invitation.scope: alternative 1

Type: `string`. pattern: `^(enterprises)\/([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})$`

###### application/json body.invitation.scope: alternative 2

Type: `string`. pattern: `^(clients)\/([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})$`


| Response header | Type | Description |
| --- | --- | --- |
| `Cache-Control` | "no-store" |  |

### user-invitations-accept 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.


### user-invitations-accept Response 404 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.


### user-invitations-accept Response 409 schema

Content type: `application/json`.

See [response 404 schema](#user-invitations-accept-response-404-schema).


### user-invitations-accept Response 500 schema

Content type: `application/json`.

See [response 404 schema](#user-invitations-accept-response-404-schema).


### user-invitations-accept Response 502 schema

Content type: `application/json`.

See [response 400 schema](#user-invitations-accept-response-400-schema).


### user-invitations-accept Response 503 schema

Content type: `application/json`.

See [response 400 schema](#user-invitations-accept-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "actor_scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "enterprise_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "invitation": {
      "accepted_at": "2026-05-01T10:00:00Z",
      "cancelled_at": null,
      "created_at": "2026-05-01T10:00:00Z",
      "email_constraint": "jane.doe@acme.example",
      "enterprise_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
      "expires_at": "2026-05-02T10:00:00Z",
      "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "invited_by": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "pending_human_actor_ref": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "role": "roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "scope": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "status": "accepted",
      "updated_at": "2026-05-01T10:00:00Z"
    },
    "session_expires_at": "2026-05-01T11:00:00Z",
    "session_token": "sess_eyJhbGciOiJSUzI1NiJ9.payload.sig"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /user-invitations/cancel

**Cancel user invitation**

Cancels a pending invitation. Requires `If-Match` for optimistic concurrency. Send `invitation_id` and optional `reason` in the body. Use the individual invitation GET response `ETag` header for `If-Match`; the body `etag` is the raw storage version. The list response header is an aggregate tag and cannot cancel an individual invitation.

**Required capability:** `users.invite`

**Authentication:** Bearer token required.

**Parameters:**

- `If-Match` `string` (header) *(required)* — Weak entity tag from a prior GET. Mismatch causes the request to fail with 412 Precondition Failed.
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `invitation_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)$` |
| `reason` | string or null | No |  |

Additional fields are not accepted.

#### Request body schema.reason

At least one alternative must match.

##### Request body schema.reason: alternative 1

Type: `string`. maxLength: 500

##### Request body schema.reason: alternative 2

Type: `null`.

**Request example:**

```json
{
  "invitation_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "reason": "User withdrew their request"
}
```

### user-invitations-cancel Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `accepted_at` | string or null | Yes |  |
| `cancelled_at` | string or null | Yes |  |
| `created_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))$` |
| `email_constraint` | string | Yes | format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`; maxLength: 254 |
| `enterprise_ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |
| `etag` | string | Yes | minLength: 1 |
| `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))$` |
| `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)$` |
| `invited_by` | string | Yes | pattern: `^(users\|service-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})$` |
| `pending_human_actor_ref` | string | Yes | pattern: `^(users)\/([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})$` |
| `role` | string | Yes | pattern: `^(roles)\/([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})$` |
| `scope` | string or string | Yes |  |
| `status` | "pending" / "accepting" / "accepted" / "expired" / "cancelled" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.accepted_at

At least one alternative must match.

###### application/json body.accepted_at: alternative 1

Type: `string`. 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))$`

###### application/json body.accepted_at: alternative 2

Type: `null`. 

##### application/json body.cancelled_at

At least one alternative must match.

###### application/json body.cancelled_at: alternative 1

Type: `string`. 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))$`

###### application/json body.cancelled_at: alternative 2

Type: `null`. 

##### application/json body.scope

At least one alternative must match.

###### application/json body.scope: alternative 1

Type: `string`. pattern: `^(enterprises)\/([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})$`

###### application/json body.scope: alternative 2

Type: `string`. pattern: `^(clients)\/([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})$`


### user-invitations-cancel 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.


### user-invitations-cancel Response 401 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.


### user-invitations-cancel Response 403 schema

Content type: `application/json`.

See [response 401 schema](#user-invitations-cancel-response-401-schema).


### user-invitations-cancel Response 404 schema

Content type: `application/json`.

See [response 401 schema](#user-invitations-cancel-response-401-schema).


### user-invitations-cancel Response 409 schema

Content type: `application/json`.

See [response 401 schema](#user-invitations-cancel-response-401-schema).


### user-invitations-cancel Response 412 schema

Content type: `application/json`.

See [response 401 schema](#user-invitations-cancel-response-401-schema).


### user-invitations-cancel Response 500 schema

Content type: `application/json`.

See [response 401 schema](#user-invitations-cancel-response-401-schema).


### user-invitations-cancel Response 502 schema

Content type: `application/json`.

See [response 400 schema](#user-invitations-cancel-response-400-schema).


### user-invitations-cancel Response 503 schema

Content type: `application/json`.

See [response 400 schema](#user-invitations-cancel-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "accepted_at": null,
    "cancelled_at": "2026-05-01T10:00:00Z",
    "created_at": "2026-05-01T10:00:00Z",
    "email_constraint": "jane.doe@acme.example",
    "enterprise_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
    "expires_at": "2026-05-02T10:00:00Z",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "invited_by": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "pending_human_actor_ref": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "role": "roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "scope": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "cancelled",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `412` — If-Match check failed; the resource has changed since the cached etag.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /user-invitations/resend

**Resend user invitation**

Resends first access for the invitation identified by the invited user (`user_ref`). Hosted invitations receive a refreshed magic-link email; an enterprise_idp invitation triggers its identity command instead and carries no hosted challenge. The role and scope remain unchanged.

**Required capability:** `users.invite`

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `user_ref` | string | Yes | pattern: `^(users)\/([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})$` |

Additional fields are not accepted.

**Request example:**

```json
{
  "user_ref": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}
```

### user-invitations-resend Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `accepted_at` | string or null | Yes |  |
| `cancelled_at` | string or null | Yes |  |
| `created_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))$` |
| `email_constraint` | string | Yes | format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`; maxLength: 254 |
| `enterprise_ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |
| `etag` | string | Yes | minLength: 1 |
| `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))$` |
| `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)$` |
| `invited_by` | string | Yes | pattern: `^(users\|service-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})$` |
| `pending_human_actor_ref` | string | Yes | pattern: `^(users)\/([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})$` |
| `role` | string | Yes | pattern: `^(roles)\/([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})$` |
| `scope` | string or string | Yes |  |
| `status` | "pending" / "accepting" / "accepted" / "expired" / "cancelled" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.accepted_at

At least one alternative must match.

###### application/json body.accepted_at: alternative 1

Type: `string`. 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))$`

###### application/json body.accepted_at: alternative 2

Type: `null`. 

##### application/json body.cancelled_at

At least one alternative must match.

###### application/json body.cancelled_at: alternative 1

Type: `string`. 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))$`

###### application/json body.cancelled_at: alternative 2

Type: `null`. 

##### application/json body.scope

At least one alternative must match.

###### application/json body.scope: alternative 1

Type: `string`. pattern: `^(enterprises)\/([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})$`

###### application/json body.scope: alternative 2

Type: `string`. pattern: `^(clients)\/([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})$`


### user-invitations-resend 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.


### user-invitations-resend Response 401 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.


### user-invitations-resend Response 403 schema

Content type: `application/json`.

See [response 401 schema](#user-invitations-resend-response-401-schema).


### user-invitations-resend Response 404 schema

Content type: `application/json`.

See [response 401 schema](#user-invitations-resend-response-401-schema).


### user-invitations-resend Response 409 schema

Content type: `application/json`.

See [response 401 schema](#user-invitations-resend-response-401-schema).


### user-invitations-resend Response 500 schema

Content type: `application/json`.

See [response 401 schema](#user-invitations-resend-response-401-schema).


### user-invitations-resend Response 502 schema

Content type: `application/json`.

See [response 400 schema](#user-invitations-resend-response-400-schema).


### user-invitations-resend Response 503 schema

Content type: `application/json`.

See [response 400 schema](#user-invitations-resend-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "accepted_at": null,
    "cancelled_at": null,
    "created_at": "2026-05-01T10:00:00Z",
    "email_constraint": "jane.doe@acme.example",
    "enterprise_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
    "expires_at": "2026-05-02T10:00:00Z",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "invited_by": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "pending_human_actor_ref": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "role": "roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "scope": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "status": "pending",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## On-ramp Sessions

### GET /on-ramp-sessions

**List on-ramp sessions**

**Required capability:** `ramps.read`

**Authentication:** Bearer token required.

**Parameters:**

- `account_ref` `string` (query)
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### on-ramp-sessions-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object or object or object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object or object or object[]`. 

###### application/json body.items item

At least one alternative must match.

###### application/json body.items item: 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})$` |
| `applied_rate` | string or null | Yes |  |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `conversion_execution_id` | string or null | Yes |  |
| `created_at` | string or string | Yes |  |
| `failure_detail` | object or null | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "conversion" | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fee_transaction_ids` | string[] or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `ledger_posted_target_amount` | object or null | Yes |  |
| `leg_attempt_id` | string or null | Yes |  |
| `posted_at` | string or string or null | Yes |  |
| `principal_amount` | object | Yes | No additional fields |
| `principal_transaction_id` | string or null | Yes |  |
| `settled_at` | string or string or null | Yes |  |
| `source_gross_amount` | object or null | Yes |  |
| `source_principal_amount` | object or null | Yes |  |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `target_amount` | object or null | Yes |  |
| `target_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.applied_rate

At least one alternative must match.

###### application/json body.items item: alternative 1.applied_rate: alternative 1

DecimalString

Type: `string`. pattern: `^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$`

###### application/json body.items item: alternative 1.applied_rate: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.approval_ref

At least one alternative must match.

###### application/json body.items item: alternative 1.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body.items item: alternative 1.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 1.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 1.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body.items item: alternative 1.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body.items item: alternative 1.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.approval_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.compliance_assessment_ref

At least one alternative must match.

###### application/json body.items item: alternative 1.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body.items item: alternative 1.compliance_assessment_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.conversion_execution_id

At least one alternative must match.

###### application/json body.items item: alternative 1.conversion_execution_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item: alternative 1.conversion_execution_id: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.created_at

At least one alternative must match.

###### application/json body.items item: alternative 1.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 1.created_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 1.failure_detail

At least one alternative must match.

###### application/json body.items item: alternative 1.failure_detail: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `failed_at` | string or string or null | Yes |  |
| `reason_code` | string | Yes | pattern: `^[a-z0-9_.:-]+$`; minLength: 1; maxLength: 128 |
| `retryable` | boolean or null | Yes |  |
| `stage` | "pre_execution" / "execution" / "post_fill" / "ledger_posting" / "unknown" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.failure_detail: alternative 1.failed_at

At least one alternative must match.

###### application/json body.items item: alternative 1.failure_detail: alternative 1.failed_at: alternative 1

At least one alternative must match.

###### application/json body.items item: alternative 1.failure_detail: alternative 1.failed_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 1.failure_detail: alternative 1.failed_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 1.failure_detail: alternative 1.failed_at: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.failure_detail: alternative 1.retryable

At least one alternative must match.

###### application/json body.items item: alternative 1.failure_detail: alternative 1.retryable: alternative 1

Type: `boolean`. 

###### application/json body.items item: alternative 1.failure_detail: alternative 1.retryable: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.failure_detail: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.failure_reason

At least one alternative must match.

###### application/json body.items item: alternative 1.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.items item: alternative 1.failure_reason: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.fee_summary

At least one alternative must match.

###### application/json body.items item: alternative 1.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body.items item: alternative 1.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.fee_summary: alternative 1.components item.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.

###### application/json body.items item: alternative 1.fee_summary: alternative 1.total

| 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.

###### application/json body.items item: alternative 1.fee_summary: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.fee_transaction_ids

At least one alternative must match.

###### application/json body.items item: alternative 1.fee_transaction_ids: alternative 1

Type: `string[]`. 

###### application/json body.items item: alternative 1.fee_transaction_ids: alternative 1 item

Type: `string`. 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)$`

###### application/json body.items item: alternative 1.fee_transaction_ids: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.fill_rate

At least one alternative must match.

###### application/json body.items item: alternative 1.fill_rate: alternative 1

Type: `string`. 

###### application/json body.items item: alternative 1.fill_rate: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.ledger_posted_target_amount

At least one alternative must match.

###### application/json body.items item: alternative 1.ledger_posted_target_amount: alternative 1

| 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.

###### application/json body.items item: alternative 1.ledger_posted_target_amount: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.leg_attempt_id

At least one alternative must match.

###### application/json body.items item: alternative 1.leg_attempt_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item: alternative 1.leg_attempt_id: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.posted_at

At least one alternative must match.

###### application/json body.items item: alternative 1.posted_at: alternative 1

At least one alternative must match.

###### application/json body.items item: alternative 1.posted_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 1.posted_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 1.posted_at: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.principal_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.

###### application/json body.items item: alternative 1.principal_transaction_id

At least one alternative must match.

###### application/json body.items item: alternative 1.principal_transaction_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item: alternative 1.principal_transaction_id: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.settled_at

At least one alternative must match.

###### application/json body.items item: alternative 1.settled_at: alternative 1

At least one alternative must match.

###### application/json body.items item: alternative 1.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 1.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 1.settled_at: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.source_gross_amount

At least one alternative must match.

###### application/json body.items item: alternative 1.source_gross_amount: alternative 1

| 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.

###### application/json body.items item: alternative 1.source_gross_amount: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.source_principal_amount

At least one alternative must match.

###### application/json body.items item: alternative 1.source_principal_amount: alternative 1

| 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.

###### application/json body.items item: alternative 1.source_principal_amount: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.subject_attribution.actor

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 1.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution.approved_by

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 1.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 1.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 1.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution.federation

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 1.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution.subject

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 1.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution.subject: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.target_amount

At least one alternative must match.

###### application/json body.items item: alternative 1.target_amount: alternative 1

| 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.

###### application/json body.items item: alternative 1.target_amount: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.updated_at

At least one alternative must match.

###### application/json body.items item: alternative 1.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 1.updated_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: 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})$` |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `created_at` | string or string | Yes |  |
| `external_settlement_role` | "external_source_spend" / "external_target_disbursement" | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "external_settlement_conversion" | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `internal_settlement_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})$` |
| `principal_amount` | object | Yes | No additional fields |
| `settled_at` | string or string or null | Yes |  |
| `settlement_checked_at` | string or string | Yes |  |
| `settlement_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `target_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.approval_ref

At least one alternative must match.

###### application/json body.items item: alternative 2.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body.items item: alternative 2.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 2.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 2.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body.items item: alternative 2.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body.items item: alternative 2.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.approval_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.compliance_assessment_ref

At least one alternative must match.

###### application/json body.items item: alternative 2.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body.items item: alternative 2.compliance_assessment_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.created_at

At least one alternative must match.

###### application/json body.items item: alternative 2.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 2.created_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 2.failure_reason

At least one alternative must match.

###### application/json body.items item: alternative 2.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.items item: alternative 2.failure_reason: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.fee_summary

At least one alternative must match.

###### application/json body.items item: alternative 2.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body.items item: alternative 2.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.fee_summary: alternative 1.components item.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.

###### application/json body.items item: alternative 2.fee_summary: alternative 1.total

| 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.

###### application/json body.items item: alternative 2.fee_summary: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.fill_rate

At least one alternative must match.

###### application/json body.items item: alternative 2.fill_rate: alternative 1

Type: `string`. 

###### application/json body.items item: alternative 2.fill_rate: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.principal_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.

###### application/json body.items item: alternative 2.settled_at

At least one alternative must match.

###### application/json body.items item: alternative 2.settled_at: alternative 1

At least one alternative must match.

###### application/json body.items item: alternative 2.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 2.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 2.settled_at: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.settlement_checked_at

At least one alternative must match.

###### application/json body.items item: alternative 2.settlement_checked_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 2.settlement_checked_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 2.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.subject_attribution.actor

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 2.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.subject_attribution.approved_by

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 2.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 2.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 2.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.subject_attribution.federation

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 2.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.subject_attribution.subject

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 2.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.subject_attribution.subject: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.updated_at

At least one alternative must match.

###### application/json body.items item: alternative 2.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 2.updated_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 3

| 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})$` |
| `admission_hold_reason` | "CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED" or null | No |  |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `created_at` | string or string | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "deposit" / "withdrawal" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension" | Yes |  |
| `family_params` | object | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `principal_amount` | object | Yes | No additional fields |
| `settled_at` | string or string or null | Yes |  |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.admission_hold_reason

At least one alternative must match.

###### application/json body.items item: alternative 3.admission_hold_reason: alternative 1

Type: `"CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED"`. 

###### application/json body.items item: alternative 3.admission_hold_reason: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.approval_ref

At least one alternative must match.

###### application/json body.items item: alternative 3.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body.items item: alternative 3.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 3.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 3.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body.items item: alternative 3.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body.items item: alternative 3.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.approval_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.compliance_assessment_ref

At least one alternative must match.

###### application/json body.items item: alternative 3.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body.items item: alternative 3.compliance_assessment_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.created_at

At least one alternative must match.

###### application/json body.items item: alternative 3.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 3.created_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 3.failure_reason

At least one alternative must match.

###### application/json body.items item: alternative 3.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.items item: alternative 3.failure_reason: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.fee_summary

At least one alternative must match.

###### application/json body.items item: alternative 3.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body.items item: alternative 3.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.fee_summary: alternative 1.components item.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.

###### application/json body.items item: alternative 3.fee_summary: alternative 1.total

| 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.

###### application/json body.items item: alternative 3.fee_summary: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.fill_rate

At least one alternative must match.

###### application/json body.items item: alternative 3.fill_rate: alternative 1

Type: `string`. 

###### application/json body.items item: alternative 3.fill_rate: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.principal_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.

###### application/json body.items item: alternative 3.settled_at

At least one alternative must match.

###### application/json body.items item: alternative 3.settled_at: alternative 1

At least one alternative must match.

###### application/json body.items item: alternative 3.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 3.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 3.settled_at: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.subject_attribution.actor

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 3.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution.approved_by

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 3.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 3.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 3.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution.federation

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 3.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution.subject

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 3.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution.subject: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.updated_at

At least one alternative must match.

###### application/json body.items item: alternative 3.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 3.updated_at: alternative 2

Type: `string`. format: date-time

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. 

###### application/json body.next_page_token: alternative 2

Type: `null`.


### on-ramp-sessions-list 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.


### on-ramp-sessions-list Response 401 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.


### on-ramp-sessions-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#on-ramp-sessions-list-response-401-schema).


### on-ramp-sessions-list Response 404 schema

Content type: `application/json`.

See [response 401 schema](#on-ramp-sessions-list-response-401-schema).


### on-ramp-sessions-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#on-ramp-sessions-list-response-401-schema).


### on-ramp-sessions-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#on-ramp-sessions-list-response-400-schema).


### on-ramp-sessions-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#on-ramp-sessions-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "approval_ref": null,
        "created_at": "2026-05-01T10:00:00Z",
        "failure_reason": null,
        "family": "on_ramp",
        "family_params": {
          "destination_payload": {},
          "destination_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
          "intermediate_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
          "source_amount": {
            "currency": "EUR",
            "value": "250.00"
          },
          "source_rail": "fiat",
          "target_currency": "USDC"
        },
        "fee_summary": {
          "components": [
            {
              "amount": {
                "currency": "EUR",
                "value": "1.00"
              },
              "kind": "platform_fee"
            }
          ],
          "total": {
            "currency": "EUR",
            "value": "1.00"
          }
        },
        "fill_rate": null,
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "principal_amount": {
          "currency": "EUR",
          "value": "250.00"
        },
        "settled_at": "2026-05-01T10:00:00Z",
        "status": "settled",
        "subject_attribution": {
          "actor": null,
          "approved_by": null,
          "authenticated_principal": {
            "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
            "kind": "user",
            "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
          },
          "enterprise_binding": {
            "tenant_type": "enterprise",
            "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
          },
          "federation": null,
          "identity_source": "platform-managed",
          "initiated_by": null,
          "subject": {
            "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
            "kind": "user",
            "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
          }
        },
        "updated_at": "2026-05-01T10:00:00Z"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /on-ramp-sessions

**Create on-ramp session**

Initiates an on-ramp session. `amount` is the expected inbound principal; `target_currency` is the asset the account will receive after conversion; `source_rail` selects the inbound funding rail (`fiat` or `crypto`). `destination` is optional and defaults to an empty object; it uses a generic record rather than a typed funding-instruction schema. Supply `Idempotency-Key` or body `client_idempotency_key` for idempotent retries; the header takes precedence. If both are absent, edge generates a fresh key, so a retry creates another operation.

**Required capability:** `ramps.create`

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| 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 |
| `client_idempotency_key` | string | No | minLength: 1 |
| `destination` | object | No |  |
| `source_rail` | "fiat" / "crypto" | Yes |  |
| `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.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 example:**

```json
{
  "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "amount": {
    "currency": "EUR",
    "value": "250.00"
  },
  "source_rail": "fiat",
  "target_currency": "USDC"
}
```

### on-ramp-sessions-create Response 201 schema

Content type: `application/json`.

#### application/json body

| 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})$` |
| `admission_hold_reason` | "CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED" or null | No |  |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `created_at` | string or string | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "deposit" / "withdrawal" / "conversion" / "external_settlement_conversion" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension" | Yes |  |
| `family_params` | object | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `principal_amount` | object | Yes | No additional fields |
| `settled_at` | string or string or null | Yes |  |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

##### application/json body.admission_hold_reason

At least one alternative must match.

###### application/json body.admission_hold_reason: alternative 1

Type: `"CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED"`. 

###### application/json body.admission_hold_reason: alternative 2

Type: `null`. 

##### application/json body.approval_ref

At least one alternative must match.

###### application/json body.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body.approval_ref: alternative 2

Type: `null`. 

##### application/json body.compliance_assessment_ref

At least one alternative must match.

###### application/json body.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body.compliance_assessment_ref: alternative 2

Type: `null`. 

##### application/json body.created_at

At least one alternative must match.

###### application/json body.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.created_at: alternative 2

Type: `string`. format: date-time

##### application/json body.failure_reason

At least one alternative must match.

###### application/json body.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.failure_reason: alternative 2

Type: `null`. 

##### application/json body.fee_summary

At least one alternative must match.

###### application/json body.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body.fee_summary: alternative 1.components item.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.

###### application/json body.fee_summary: alternative 1.total

| 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.

###### application/json body.fee_summary: alternative 2

Type: `null`. 

##### application/json body.fill_rate

At least one alternative must match.

###### application/json body.fill_rate: alternative 1

Type: `string`. 

###### application/json body.fill_rate: alternative 2

Type: `null`. 

##### application/json body.principal_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.

##### application/json body.settled_at

At least one alternative must match.

###### application/json body.settled_at: alternative 1

At least one alternative must match.

###### application/json body.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.settled_at: alternative 2

Type: `null`. 

##### application/json body.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.federation

At least one alternative must match.

###### application/json body.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject: alternative 2

Type: `null`. 

##### application/json body.updated_at

At least one alternative must match.

###### application/json body.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.updated_at: alternative 2

Type: `string`. format: date-time


### on-ramp-sessions-create 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.


### on-ramp-sessions-create Response 401 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.


### on-ramp-sessions-create Response 403 schema

Content type: `application/json`.

See [response 401 schema](#on-ramp-sessions-create-response-401-schema).


### on-ramp-sessions-create Response 409 schema

Content type: `application/json`.

See [response 401 schema](#on-ramp-sessions-create-response-401-schema).


### on-ramp-sessions-create Response 422 schema

Content type: `application/json`.

See [response 401 schema](#on-ramp-sessions-create-response-401-schema).


### on-ramp-sessions-create Response 500 schema

Content type: `application/json`.

See [response 401 schema](#on-ramp-sessions-create-response-401-schema).


### on-ramp-sessions-create Response 502 schema

Content type: `application/json`.

See [response 400 schema](#on-ramp-sessions-create-response-400-schema).


### on-ramp-sessions-create Response 503 schema

Content type: `application/json`.

See [response 400 schema](#on-ramp-sessions-create-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "approval_ref": null,
    "created_at": "2026-05-01T10:00:00Z",
    "failure_reason": null,
    "family": "on_ramp",
    "family_params": {
      "destination_payload": {},
      "destination_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "intermediate_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "source_amount": {
        "currency": "EUR",
        "value": "250.00"
      },
      "source_rail": "fiat",
      "target_currency": "USDC"
    },
    "fee_summary": null,
    "fill_rate": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "principal_amount": {
      "currency": "EUR",
      "value": "250.00"
    },
    "settled_at": null,
    "status": "admissible",
    "subject_attribution": {
      "actor": null,
      "approved_by": null,
      "authenticated_principal": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "enterprise_binding": {
        "tenant_type": "enterprise",
        "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "federation": null,
      "identity_source": "platform-managed",
      "initiated_by": null,
      "subject": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      }
    },
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `422` — The request cannot be processed under the resource or route contract. Depending on the endpoint, code can be not_admissible or unsupported_currency; inspect the documented code and data.reason.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /on-ramp-sessions/{session_id}

**Get on-ramp session**

**Required capability:** `ramps.read`

**Authentication:** Bearer token required.

**Parameters:**

- `session_id` `string` (path) *(required)*

### on-ramp-sessions-get Response 200 schema

Content type: `application/json`.

#### application/json body

At least one alternative must match.

##### application/json body: 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})$` |
| `applied_rate` | string or null | Yes |  |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `conversion_execution_id` | string or null | Yes |  |
| `created_at` | string or string | Yes |  |
| `failure_detail` | object or null | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "conversion" | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fee_transaction_ids` | string[] or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `ledger_posted_target_amount` | object or null | Yes |  |
| `leg_attempt_id` | string or null | Yes |  |
| `posted_at` | string or string or null | Yes |  |
| `principal_amount` | object | Yes | No additional fields |
| `principal_transaction_id` | string or null | Yes |  |
| `settled_at` | string or string or null | Yes |  |
| `source_gross_amount` | object or null | Yes |  |
| `source_principal_amount` | object or null | Yes |  |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `target_amount` | object or null | Yes |  |
| `target_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 1.applied_rate

At least one alternative must match.

###### application/json body: alternative 1.applied_rate: alternative 1

DecimalString

Type: `string`. pattern: `^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$`

###### application/json body: alternative 1.applied_rate: alternative 2

Type: `null`. 

###### application/json body: alternative 1.approval_ref

At least one alternative must match.

###### application/json body: alternative 1.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 1.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body: alternative 1.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 1.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 1.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body: alternative 1.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body: alternative 1.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body: alternative 1.approval_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 1.compliance_assessment_ref

At least one alternative must match.

###### application/json body: alternative 1.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body: alternative 1.compliance_assessment_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 1.conversion_execution_id

At least one alternative must match.

###### application/json body: alternative 1.conversion_execution_id: alternative 1

Type: `string`. 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)$`

###### application/json body: alternative 1.conversion_execution_id: alternative 2

Type: `null`. 

###### application/json body: alternative 1.created_at

At least one alternative must match.

###### application/json body: alternative 1.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 1.created_at: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 1.failure_detail

At least one alternative must match.

###### application/json body: alternative 1.failure_detail: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `failed_at` | string or string or null | Yes |  |
| `reason_code` | string | Yes | pattern: `^[a-z0-9_.:-]+$`; minLength: 1; maxLength: 128 |
| `retryable` | boolean or null | Yes |  |
| `stage` | "pre_execution" / "execution" / "post_fill" / "ledger_posting" / "unknown" | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 1.failure_detail: alternative 1.failed_at

At least one alternative must match.

###### application/json body: alternative 1.failure_detail: alternative 1.failed_at: alternative 1

At least one alternative must match.

###### application/json body: alternative 1.failure_detail: alternative 1.failed_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 1.failure_detail: alternative 1.failed_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 1.failure_detail: alternative 1.failed_at: alternative 2

Type: `null`. 

###### application/json body: alternative 1.failure_detail: alternative 1.retryable

At least one alternative must match.

###### application/json body: alternative 1.failure_detail: alternative 1.retryable: alternative 1

Type: `boolean`. 

###### application/json body: alternative 1.failure_detail: alternative 1.retryable: alternative 2

Type: `null`. 

###### application/json body: alternative 1.failure_detail: alternative 2

Type: `null`. 

###### application/json body: alternative 1.failure_reason

At least one alternative must match.

###### application/json body: alternative 1.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body: alternative 1.failure_reason: alternative 2

Type: `null`. 

###### application/json body: alternative 1.fee_summary

At least one alternative must match.

###### application/json body: alternative 1.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body: alternative 1.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body: alternative 1.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 1.fee_summary: alternative 1.components item.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.

###### application/json body: alternative 1.fee_summary: alternative 1.total

| 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.

###### application/json body: alternative 1.fee_summary: alternative 2

Type: `null`. 

###### application/json body: alternative 1.fee_transaction_ids

At least one alternative must match.

###### application/json body: alternative 1.fee_transaction_ids: alternative 1

Type: `string[]`. 

###### application/json body: alternative 1.fee_transaction_ids: alternative 1 item

Type: `string`. 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)$`

###### application/json body: alternative 1.fee_transaction_ids: alternative 2

Type: `null`. 

###### application/json body: alternative 1.fill_rate

At least one alternative must match.

###### application/json body: alternative 1.fill_rate: alternative 1

Type: `string`. 

###### application/json body: alternative 1.fill_rate: alternative 2

Type: `null`. 

###### application/json body: alternative 1.ledger_posted_target_amount

At least one alternative must match.

###### application/json body: alternative 1.ledger_posted_target_amount: alternative 1

| 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.

###### application/json body: alternative 1.ledger_posted_target_amount: alternative 2

Type: `null`. 

###### application/json body: alternative 1.leg_attempt_id

At least one alternative must match.

###### application/json body: alternative 1.leg_attempt_id: alternative 1

Type: `string`. 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)$`

###### application/json body: alternative 1.leg_attempt_id: alternative 2

Type: `null`. 

###### application/json body: alternative 1.posted_at

At least one alternative must match.

###### application/json body: alternative 1.posted_at: alternative 1

At least one alternative must match.

###### application/json body: alternative 1.posted_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 1.posted_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 1.posted_at: alternative 2

Type: `null`. 

###### application/json body: alternative 1.principal_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.

###### application/json body: alternative 1.principal_transaction_id

At least one alternative must match.

###### application/json body: alternative 1.principal_transaction_id: alternative 1

Type: `string`. 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)$`

###### application/json body: alternative 1.principal_transaction_id: alternative 2

Type: `null`. 

###### application/json body: alternative 1.settled_at

At least one alternative must match.

###### application/json body: alternative 1.settled_at: alternative 1

At least one alternative must match.

###### application/json body: alternative 1.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 1.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 1.settled_at: alternative 2

Type: `null`. 

###### application/json body: alternative 1.source_gross_amount

At least one alternative must match.

###### application/json body: alternative 1.source_gross_amount: alternative 1

| 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.

###### application/json body: alternative 1.source_gross_amount: alternative 2

Type: `null`. 

###### application/json body: alternative 1.source_principal_amount

At least one alternative must match.

###### application/json body: alternative 1.source_principal_amount: alternative 1

| 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.

###### application/json body: alternative 1.source_principal_amount: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 1.subject_attribution.actor

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 1.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 1.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution.approved_by

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 1.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 1.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 1.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 1.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 1.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 1.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution.federation

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body: alternative 1.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 1.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 1.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution.subject

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 1.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 1.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution.subject: alternative 2

Type: `null`. 

###### application/json body: alternative 1.target_amount

At least one alternative must match.

###### application/json body: alternative 1.target_amount: alternative 1

| 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.

###### application/json body: alternative 1.target_amount: alternative 2

Type: `null`. 

###### application/json body: alternative 1.updated_at

At least one alternative must match.

###### application/json body: alternative 1.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 1.updated_at: alternative 2

Type: `string`. format: date-time

##### application/json body: 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})$` |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `created_at` | string or string | Yes |  |
| `external_settlement_role` | "external_source_spend" / "external_target_disbursement" | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "external_settlement_conversion" | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `internal_settlement_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})$` |
| `principal_amount` | object | Yes | No additional fields |
| `settled_at` | string or string or null | Yes |  |
| `settlement_checked_at` | string or string | Yes |  |
| `settlement_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `target_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 2.approval_ref

At least one alternative must match.

###### application/json body: alternative 2.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 2.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body: alternative 2.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 2.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 2.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body: alternative 2.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body: alternative 2.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body: alternative 2.approval_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 2.compliance_assessment_ref

At least one alternative must match.

###### application/json body: alternative 2.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body: alternative 2.compliance_assessment_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 2.created_at

At least one alternative must match.

###### application/json body: alternative 2.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 2.created_at: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 2.failure_reason

At least one alternative must match.

###### application/json body: alternative 2.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body: alternative 2.failure_reason: alternative 2

Type: `null`. 

###### application/json body: alternative 2.fee_summary

At least one alternative must match.

###### application/json body: alternative 2.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body: alternative 2.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body: alternative 2.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 2.fee_summary: alternative 1.components item.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.

###### application/json body: alternative 2.fee_summary: alternative 1.total

| 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.

###### application/json body: alternative 2.fee_summary: alternative 2

Type: `null`. 

###### application/json body: alternative 2.fill_rate

At least one alternative must match.

###### application/json body: alternative 2.fill_rate: alternative 1

Type: `string`. 

###### application/json body: alternative 2.fill_rate: alternative 2

Type: `null`. 

###### application/json body: alternative 2.principal_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.

###### application/json body: alternative 2.settled_at

At least one alternative must match.

###### application/json body: alternative 2.settled_at: alternative 1

At least one alternative must match.

###### application/json body: alternative 2.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 2.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 2.settled_at: alternative 2

Type: `null`. 

###### application/json body: alternative 2.settlement_checked_at

At least one alternative must match.

###### application/json body: alternative 2.settlement_checked_at: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 2.settlement_checked_at: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 2.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 2.subject_attribution.actor

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 2.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 2.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 2.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body: alternative 2.subject_attribution.approved_by

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 2.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 2.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 2.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body: alternative 2.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 2.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 2.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 2.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 2.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 2.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 2.subject_attribution.federation

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body: alternative 2.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body: alternative 2.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 2.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 2.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 2.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body: alternative 2.subject_attribution.subject

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 2.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 2.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 2.subject_attribution.subject: alternative 2

Type: `null`. 

###### application/json body: alternative 2.updated_at

At least one alternative must match.

###### application/json body: alternative 2.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 2.updated_at: alternative 2

Type: `string`. format: date-time

##### application/json body: alternative 3

| 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})$` |
| `admission_hold_reason` | "CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED" or null | No |  |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `created_at` | string or string | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "deposit" / "withdrawal" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension" | Yes |  |
| `family_params` | object | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `principal_amount` | object | Yes | No additional fields |
| `settled_at` | string or string or null | Yes |  |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 3.admission_hold_reason

At least one alternative must match.

###### application/json body: alternative 3.admission_hold_reason: alternative 1

Type: `"CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED"`. 

###### application/json body: alternative 3.admission_hold_reason: alternative 2

Type: `null`. 

###### application/json body: alternative 3.approval_ref

At least one alternative must match.

###### application/json body: alternative 3.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 3.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body: alternative 3.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 3.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 3.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body: alternative 3.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body: alternative 3.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body: alternative 3.approval_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 3.compliance_assessment_ref

At least one alternative must match.

###### application/json body: alternative 3.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body: alternative 3.compliance_assessment_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 3.created_at

At least one alternative must match.

###### application/json body: alternative 3.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 3.created_at: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 3.failure_reason

At least one alternative must match.

###### application/json body: alternative 3.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body: alternative 3.failure_reason: alternative 2

Type: `null`. 

###### application/json body: alternative 3.fee_summary

At least one alternative must match.

###### application/json body: alternative 3.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body: alternative 3.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body: alternative 3.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 3.fee_summary: alternative 1.components item.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.

###### application/json body: alternative 3.fee_summary: alternative 1.total

| 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.

###### application/json body: alternative 3.fee_summary: alternative 2

Type: `null`. 

###### application/json body: alternative 3.fill_rate

At least one alternative must match.

###### application/json body: alternative 3.fill_rate: alternative 1

Type: `string`. 

###### application/json body: alternative 3.fill_rate: alternative 2

Type: `null`. 

###### application/json body: alternative 3.principal_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.

###### application/json body: alternative 3.settled_at

At least one alternative must match.

###### application/json body: alternative 3.settled_at: alternative 1

At least one alternative must match.

###### application/json body: alternative 3.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 3.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 3.settled_at: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 3.subject_attribution.actor

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 3.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 3.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution.approved_by

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 3.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 3.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 3.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 3.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 3.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 3.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution.federation

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body: alternative 3.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 3.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 3.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution.subject

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 3.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 3.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution.subject: alternative 2

Type: `null`. 

###### application/json body: alternative 3.updated_at

At least one alternative must match.

###### application/json body: alternative 3.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 3.updated_at: alternative 2

Type: `string`. format: date-time


### on-ramp-sessions-get 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.


### on-ramp-sessions-get Response 401 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.


### on-ramp-sessions-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#on-ramp-sessions-get-response-401-schema).


### on-ramp-sessions-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#on-ramp-sessions-get-response-401-schema).


### on-ramp-sessions-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#on-ramp-sessions-get-response-401-schema).


### on-ramp-sessions-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#on-ramp-sessions-get-response-400-schema).


### on-ramp-sessions-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#on-ramp-sessions-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "approval_ref": null,
    "created_at": "2026-05-01T10:00:00Z",
    "failure_reason": null,
    "family": "on_ramp",
    "family_params": {
      "destination_payload": {},
      "destination_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "intermediate_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "source_amount": {
        "currency": "EUR",
        "value": "250.00"
      },
      "source_rail": "fiat",
      "target_currency": "USDC"
    },
    "fee_summary": {
      "components": [
        {
          "amount": {
            "currency": "EUR",
            "value": "1.00"
          },
          "kind": "platform_fee"
        }
      ],
      "total": {
        "currency": "EUR",
        "value": "1.00"
      }
    },
    "fill_rate": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "principal_amount": {
      "currency": "EUR",
      "value": "250.00"
    },
    "settled_at": "2026-05-01T10:00:00Z",
    "status": "settled",
    "subject_attribution": {
      "actor": null,
      "approved_by": null,
      "authenticated_principal": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "enterprise_binding": {
        "tenant_type": "enterprise",
        "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "federation": null,
      "identity_source": "platform-managed",
      "initiated_by": null,
      "subject": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      }
    },
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /on-ramp-sessions/{session_id}/cancel

**Cancel on-ramp session**

**Required capability:** `ramps.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `session_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

### on-ramp-sessions-cancel Response 201 schema

Content type: `application/json`.

#### application/json body

| 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})$` |
| `admission_hold_reason` | "CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED" or null | No |  |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `created_at` | string or string | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "deposit" / "withdrawal" / "conversion" / "external_settlement_conversion" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension" | Yes |  |
| `family_params` | object | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `principal_amount` | object | Yes | No additional fields |
| `settled_at` | string or string or null | Yes |  |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

##### application/json body.admission_hold_reason

At least one alternative must match.

###### application/json body.admission_hold_reason: alternative 1

Type: `"CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED"`. 

###### application/json body.admission_hold_reason: alternative 2

Type: `null`. 

##### application/json body.approval_ref

At least one alternative must match.

###### application/json body.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body.approval_ref: alternative 2

Type: `null`. 

##### application/json body.compliance_assessment_ref

At least one alternative must match.

###### application/json body.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body.compliance_assessment_ref: alternative 2

Type: `null`. 

##### application/json body.created_at

At least one alternative must match.

###### application/json body.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.created_at: alternative 2

Type: `string`. format: date-time

##### application/json body.failure_reason

At least one alternative must match.

###### application/json body.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.failure_reason: alternative 2

Type: `null`. 

##### application/json body.fee_summary

At least one alternative must match.

###### application/json body.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body.fee_summary: alternative 1.components item.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.

###### application/json body.fee_summary: alternative 1.total

| 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.

###### application/json body.fee_summary: alternative 2

Type: `null`. 

##### application/json body.fill_rate

At least one alternative must match.

###### application/json body.fill_rate: alternative 1

Type: `string`. 

###### application/json body.fill_rate: alternative 2

Type: `null`. 

##### application/json body.principal_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.

##### application/json body.settled_at

At least one alternative must match.

###### application/json body.settled_at: alternative 1

At least one alternative must match.

###### application/json body.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.settled_at: alternative 2

Type: `null`. 

##### application/json body.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.federation

At least one alternative must match.

###### application/json body.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject: alternative 2

Type: `null`. 

##### application/json body.updated_at

At least one alternative must match.

###### application/json body.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.updated_at: alternative 2

Type: `string`. format: date-time


### on-ramp-sessions-cancel 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.


### on-ramp-sessions-cancel Response 401 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.


### on-ramp-sessions-cancel Response 403 schema

Content type: `application/json`.

See [response 401 schema](#on-ramp-sessions-cancel-response-401-schema).


### on-ramp-sessions-cancel Response 404 schema

Content type: `application/json`.

See [response 401 schema](#on-ramp-sessions-cancel-response-401-schema).


### on-ramp-sessions-cancel Response 409 schema

Content type: `application/json`.

See [response 401 schema](#on-ramp-sessions-cancel-response-401-schema).


### on-ramp-sessions-cancel Response 500 schema

Content type: `application/json`.

See [response 401 schema](#on-ramp-sessions-cancel-response-401-schema).


### on-ramp-sessions-cancel Response 502 schema

Content type: `application/json`.

See [response 400 schema](#on-ramp-sessions-cancel-response-400-schema).


### on-ramp-sessions-cancel Response 503 schema

Content type: `application/json`.

See [response 400 schema](#on-ramp-sessions-cancel-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "approval_ref": null,
    "created_at": "2026-05-01T10:00:00Z",
    "failure_reason": null,
    "family": "on_ramp",
    "family_params": {
      "destination_payload": {},
      "destination_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "intermediate_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "source_amount": {
        "currency": "EUR",
        "value": "250.00"
      },
      "source_rail": "fiat",
      "target_currency": "USDC"
    },
    "fee_summary": null,
    "fill_rate": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "principal_amount": {
      "currency": "EUR",
      "value": "250.00"
    },
    "settled_at": null,
    "status": "cancelled",
    "subject_attribution": {
      "actor": null,
      "approved_by": null,
      "authenticated_principal": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "enterprise_binding": {
        "tenant_type": "enterprise",
        "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "federation": null,
      "identity_source": "platform-managed",
      "initiated_by": null,
      "subject": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      }
    },
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Off-ramp Sessions

### GET /off-ramp-sessions

**List off-ramp sessions**

**Required capability:** `ramps.read`

**Authentication:** Bearer token required.

**Parameters:**

- `account_ref` `string` (query)
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### off-ramp-sessions-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object or object or object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object or object or object[]`. 

###### application/json body.items item

At least one alternative must match.

###### application/json body.items item: 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})$` |
| `applied_rate` | string or null | Yes |  |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `conversion_execution_id` | string or null | Yes |  |
| `created_at` | string or string | Yes |  |
| `failure_detail` | object or null | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "conversion" | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fee_transaction_ids` | string[] or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `ledger_posted_target_amount` | object or null | Yes |  |
| `leg_attempt_id` | string or null | Yes |  |
| `posted_at` | string or string or null | Yes |  |
| `principal_amount` | object | Yes | No additional fields |
| `principal_transaction_id` | string or null | Yes |  |
| `settled_at` | string or string or null | Yes |  |
| `source_gross_amount` | object or null | Yes |  |
| `source_principal_amount` | object or null | Yes |  |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `target_amount` | object or null | Yes |  |
| `target_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.applied_rate

At least one alternative must match.

###### application/json body.items item: alternative 1.applied_rate: alternative 1

DecimalString

Type: `string`. pattern: `^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$`

###### application/json body.items item: alternative 1.applied_rate: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.approval_ref

At least one alternative must match.

###### application/json body.items item: alternative 1.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body.items item: alternative 1.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 1.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 1.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body.items item: alternative 1.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body.items item: alternative 1.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.approval_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.compliance_assessment_ref

At least one alternative must match.

###### application/json body.items item: alternative 1.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body.items item: alternative 1.compliance_assessment_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.conversion_execution_id

At least one alternative must match.

###### application/json body.items item: alternative 1.conversion_execution_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item: alternative 1.conversion_execution_id: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.created_at

At least one alternative must match.

###### application/json body.items item: alternative 1.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 1.created_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 1.failure_detail

At least one alternative must match.

###### application/json body.items item: alternative 1.failure_detail: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `failed_at` | string or string or null | Yes |  |
| `reason_code` | string | Yes | pattern: `^[a-z0-9_.:-]+$`; minLength: 1; maxLength: 128 |
| `retryable` | boolean or null | Yes |  |
| `stage` | "pre_execution" / "execution" / "post_fill" / "ledger_posting" / "unknown" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.failure_detail: alternative 1.failed_at

At least one alternative must match.

###### application/json body.items item: alternative 1.failure_detail: alternative 1.failed_at: alternative 1

At least one alternative must match.

###### application/json body.items item: alternative 1.failure_detail: alternative 1.failed_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 1.failure_detail: alternative 1.failed_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 1.failure_detail: alternative 1.failed_at: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.failure_detail: alternative 1.retryable

At least one alternative must match.

###### application/json body.items item: alternative 1.failure_detail: alternative 1.retryable: alternative 1

Type: `boolean`. 

###### application/json body.items item: alternative 1.failure_detail: alternative 1.retryable: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.failure_detail: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.failure_reason

At least one alternative must match.

###### application/json body.items item: alternative 1.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.items item: alternative 1.failure_reason: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.fee_summary

At least one alternative must match.

###### application/json body.items item: alternative 1.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body.items item: alternative 1.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.fee_summary: alternative 1.components item.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.

###### application/json body.items item: alternative 1.fee_summary: alternative 1.total

| 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.

###### application/json body.items item: alternative 1.fee_summary: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.fee_transaction_ids

At least one alternative must match.

###### application/json body.items item: alternative 1.fee_transaction_ids: alternative 1

Type: `string[]`. 

###### application/json body.items item: alternative 1.fee_transaction_ids: alternative 1 item

Type: `string`. 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)$`

###### application/json body.items item: alternative 1.fee_transaction_ids: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.fill_rate

At least one alternative must match.

###### application/json body.items item: alternative 1.fill_rate: alternative 1

Type: `string`. 

###### application/json body.items item: alternative 1.fill_rate: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.ledger_posted_target_amount

At least one alternative must match.

###### application/json body.items item: alternative 1.ledger_posted_target_amount: alternative 1

| 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.

###### application/json body.items item: alternative 1.ledger_posted_target_amount: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.leg_attempt_id

At least one alternative must match.

###### application/json body.items item: alternative 1.leg_attempt_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item: alternative 1.leg_attempt_id: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.posted_at

At least one alternative must match.

###### application/json body.items item: alternative 1.posted_at: alternative 1

At least one alternative must match.

###### application/json body.items item: alternative 1.posted_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 1.posted_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 1.posted_at: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.principal_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.

###### application/json body.items item: alternative 1.principal_transaction_id

At least one alternative must match.

###### application/json body.items item: alternative 1.principal_transaction_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item: alternative 1.principal_transaction_id: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.settled_at

At least one alternative must match.

###### application/json body.items item: alternative 1.settled_at: alternative 1

At least one alternative must match.

###### application/json body.items item: alternative 1.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 1.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 1.settled_at: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.source_gross_amount

At least one alternative must match.

###### application/json body.items item: alternative 1.source_gross_amount: alternative 1

| 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.

###### application/json body.items item: alternative 1.source_gross_amount: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.source_principal_amount

At least one alternative must match.

###### application/json body.items item: alternative 1.source_principal_amount: alternative 1

| 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.

###### application/json body.items item: alternative 1.source_principal_amount: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.subject_attribution.actor

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 1.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution.approved_by

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 1.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 1.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 1.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution.federation

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 1.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution.subject

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 1.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 1.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 1.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.subject_attribution.subject: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.target_amount

At least one alternative must match.

###### application/json body.items item: alternative 1.target_amount: alternative 1

| 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.

###### application/json body.items item: alternative 1.target_amount: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 1.updated_at

At least one alternative must match.

###### application/json body.items item: alternative 1.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 1.updated_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: 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})$` |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `created_at` | string or string | Yes |  |
| `external_settlement_role` | "external_source_spend" / "external_target_disbursement" | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "external_settlement_conversion" | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `internal_settlement_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})$` |
| `principal_amount` | object | Yes | No additional fields |
| `settled_at` | string or string or null | Yes |  |
| `settlement_checked_at` | string or string | Yes |  |
| `settlement_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `target_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.approval_ref

At least one alternative must match.

###### application/json body.items item: alternative 2.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body.items item: alternative 2.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 2.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 2.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body.items item: alternative 2.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body.items item: alternative 2.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.approval_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.compliance_assessment_ref

At least one alternative must match.

###### application/json body.items item: alternative 2.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body.items item: alternative 2.compliance_assessment_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.created_at

At least one alternative must match.

###### application/json body.items item: alternative 2.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 2.created_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 2.failure_reason

At least one alternative must match.

###### application/json body.items item: alternative 2.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.items item: alternative 2.failure_reason: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.fee_summary

At least one alternative must match.

###### application/json body.items item: alternative 2.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body.items item: alternative 2.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.fee_summary: alternative 1.components item.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.

###### application/json body.items item: alternative 2.fee_summary: alternative 1.total

| 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.

###### application/json body.items item: alternative 2.fee_summary: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.fill_rate

At least one alternative must match.

###### application/json body.items item: alternative 2.fill_rate: alternative 1

Type: `string`. 

###### application/json body.items item: alternative 2.fill_rate: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.principal_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.

###### application/json body.items item: alternative 2.settled_at

At least one alternative must match.

###### application/json body.items item: alternative 2.settled_at: alternative 1

At least one alternative must match.

###### application/json body.items item: alternative 2.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 2.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 2.settled_at: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.settlement_checked_at

At least one alternative must match.

###### application/json body.items item: alternative 2.settlement_checked_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 2.settlement_checked_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 2.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.subject_attribution.actor

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 2.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.subject_attribution.approved_by

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 2.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 2.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 2.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.subject_attribution.federation

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 2.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.subject_attribution.subject

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 2.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 2.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 2.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.subject_attribution.subject: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 2.updated_at

At least one alternative must match.

###### application/json body.items item: alternative 2.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 2.updated_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 3

| 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})$` |
| `admission_hold_reason` | "CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED" or null | No |  |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `created_at` | string or string | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "deposit" / "withdrawal" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension" | Yes |  |
| `family_params` | object | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `principal_amount` | object | Yes | No additional fields |
| `settled_at` | string or string or null | Yes |  |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.admission_hold_reason

At least one alternative must match.

###### application/json body.items item: alternative 3.admission_hold_reason: alternative 1

Type: `"CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED"`. 

###### application/json body.items item: alternative 3.admission_hold_reason: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.approval_ref

At least one alternative must match.

###### application/json body.items item: alternative 3.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body.items item: alternative 3.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 3.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 3.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body.items item: alternative 3.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body.items item: alternative 3.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.approval_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.compliance_assessment_ref

At least one alternative must match.

###### application/json body.items item: alternative 3.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body.items item: alternative 3.compliance_assessment_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.created_at

At least one alternative must match.

###### application/json body.items item: alternative 3.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 3.created_at: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 3.failure_reason

At least one alternative must match.

###### application/json body.items item: alternative 3.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.items item: alternative 3.failure_reason: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.fee_summary

At least one alternative must match.

###### application/json body.items item: alternative 3.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body.items item: alternative 3.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.fee_summary: alternative 1.components item.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.

###### application/json body.items item: alternative 3.fee_summary: alternative 1.total

| 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.

###### application/json body.items item: alternative 3.fee_summary: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.fill_rate

At least one alternative must match.

###### application/json body.items item: alternative 3.fill_rate: alternative 1

Type: `string`. 

###### application/json body.items item: alternative 3.fill_rate: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.principal_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.

###### application/json body.items item: alternative 3.settled_at

At least one alternative must match.

###### application/json body.items item: alternative 3.settled_at: alternative 1

At least one alternative must match.

###### application/json body.items item: alternative 3.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 3.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.items item: alternative 3.settled_at: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.subject_attribution.actor

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 3.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution.approved_by

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 3.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 3.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 3.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution.federation

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 3.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution.subject

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.items item: alternative 3.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.items item: alternative 3.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.items item: alternative 3.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.subject_attribution.subject: alternative 2

Type: `null`. 

###### application/json body.items item: alternative 3.updated_at

At least one alternative must match.

###### application/json body.items item: alternative 3.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item: alternative 3.updated_at: alternative 2

Type: `string`. format: date-time

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. 

###### application/json body.next_page_token: alternative 2

Type: `null`.


### off-ramp-sessions-list 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.


### off-ramp-sessions-list Response 401 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.


### off-ramp-sessions-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#off-ramp-sessions-list-response-401-schema).


### off-ramp-sessions-list Response 404 schema

Content type: `application/json`.

See [response 401 schema](#off-ramp-sessions-list-response-401-schema).


### off-ramp-sessions-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#off-ramp-sessions-list-response-401-schema).


### off-ramp-sessions-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#off-ramp-sessions-list-response-400-schema).


### off-ramp-sessions-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#off-ramp-sessions-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "approval_ref": null,
        "created_at": "2026-05-01T10:00:00Z",
        "failure_reason": null,
        "family": "off_ramp",
        "family_params": {
          "destination_payload": {
            "destination": {
              "bank_coordinates": {
                "account_holder_name": "Acme Treasury",
                "bank_name": "Demo Bank",
                "bic": "NWBKGB2L",
                "country": "GB",
                "iban": "GB29NWBK60161331926819",
                "scheme": "iban"
              },
              "beneficiary_name": "Acme Treasury",
              "currency": "EUR",
              "fiat_rail": "sepa_credit_transfer",
              "method": "bank_transfer",
              "reference_hint": null
            },
            "fiat_rail": "sepa_credit_transfer",
            "method": "bank_transfer",
            "payment_reference": "RF18539007547034",
            "withdrawal_destination_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
          },
          "intermediate_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
          "source_amount": {
            "currency": "USDC",
            "value": "250.00"
          },
          "source_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
          "target_currency": "EUR",
          "target_rail": "fiat"
        },
        "fee_summary": {
          "components": [
            {
              "amount": {
                "currency": "USDC",
                "value": "1.00"
              },
              "kind": "network_fee"
            }
          ],
          "total": {
            "currency": "USDC",
            "value": "1.00"
          }
        },
        "fill_rate": null,
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "principal_amount": {
          "currency": "USDC",
          "value": "250.00"
        },
        "settled_at": null,
        "status": "admissible",
        "subject_attribution": {
          "actor": null,
          "approved_by": null,
          "authenticated_principal": {
            "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
            "kind": "user",
            "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
          },
          "enterprise_binding": {
            "tenant_type": "enterprise",
            "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
          },
          "federation": null,
          "identity_source": "platform-managed",
          "initiated_by": null,
          "subject": {
            "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
            "kind": "user",
            "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
          }
        },
        "updated_at": "2026-05-01T10:00:00Z"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /off-ramp-sessions

**Create off-ramp session**

Initiates an off-ramp session. `amount` is the principal to debit from the account; `target_currency` is the asset the recipient will receive; `target_rail` selects the outbound delivery rail (`fiat` or `crypto`), and `destination` carries the matching typed withdrawal destination command. Crypto commands include a nullable destination_id, network and strict address/memo; fiat commands must identify an existing stored withdrawal destination and restate its routing. Caller fiat bank details may include bank_address and account_type where applicable; provider-issued receive details are refused. An `amount` with more fractional digits than the catalog scale of its asset is refused with `400 invalid_request` and `data.reason = amount_scale_exceeded` before anything is held; trailing zeros do not count, and an asset the catalog has no scale for (including crypto assets missing scale metadata) is not checked. Supply `Idempotency-Key` or body `client_idempotency_key` for idempotent retries; the header takes precedence. If both are absent, edge generates a fresh key, so a retry creates another operation.

**Required capability:** `ramps.create`

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

Exactly one alternative must match.

#### Request body schema: 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 |
| `client_idempotency_key` | string | No | minLength: 1 |
| `destination` | object | Yes | No additional fields |
| `target_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `target_rail` | "crypto" | Yes |  |

Additional fields are not accepted.

##### Request body schema: 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.destination

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `destination` | object | Yes | No additional fields |
| `destination_id` | string or null | Yes |  |
| `network` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### Request body schema: alternative 1.destination.destination

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `address` | string | Yes | minLength: 1; maxLength: 256 |
| `memo` | string or null | Yes |  |

Additional fields are not accepted.

###### Request body schema: alternative 1.destination.destination.memo

At least one alternative must match.

###### Request body schema: alternative 1.destination.destination.memo: alternative 1

Type: `string`. 

###### Request body schema: alternative 1.destination.destination.memo: alternative 2

Type: `null`. 

###### Request body schema: alternative 1.destination.destination_id

At least one alternative must match.

###### Request body schema: alternative 1.destination.destination_id: alternative 1

Type: `string`. 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)$`

###### Request body schema: alternative 1.destination.destination_id: alternative 2

Type: `null`. 

#### Request body schema: 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 |
| `client_idempotency_key` | string | No | minLength: 1 |
| `destination` | object | Yes | No additional fields |
| `target_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `target_rail` | "fiat" | Yes |  |

Additional fields are not accepted.

##### Request body schema: 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.destination

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `destination` | object | Yes | No additional fields |
| `fiat_rail` | "sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire" | Yes |  |
| `method` | "bank_transfer" | Yes |  |
| `payment_reference` | string or null | Yes |  |
| `route_owner_ref` | string | Yes | pattern: `^(enterprises\|platform-operators\|clients)\/([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})$` |
| `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 2.destination.destination

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `bank_coordinates` | object or object | Yes |  |
| `beneficiary_name` | string | Yes | minLength: 1; maxLength: 140 |
| `currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `fiat_rail` | "sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire" | Yes |  |
| `method` | "bank_transfer" | Yes |  |
| `reference_hint` | string or null | Yes |  |

Additional fields are not accepted.

###### Request body schema: alternative 2.destination.destination.bank_coordinates

Exactly one alternative must match.

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `iban` | string | Yes | minLength: 1; maxLength: 34 |
| `scheme` | "iban" | Yes |  |

Additional fields are not accepted.

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 1.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 1.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 1.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 1.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 1.bank_address: alternative 1.postal_code

At least one alternative must match.

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 1.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 1.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 1.bank_address: alternative 1.region

At least one alternative must match.

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 1.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 1.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 1.bank_address: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 1.bank_name

At least one alternative must match.

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 1.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 1.bank_name: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 1.bic

At least one alternative must match.

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 1.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 1.bic: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string | Yes | minLength: 1; maxLength: 64 |
| `account_type` | "checking" / "savings" or null | No | Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept. |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `routing_codes` | object[] | Yes | minItems: 1; maxItems: 16 |
| `scheme` | "local_account" | Yes |  |

Additional fields are not accepted.

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 2.account_type

Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept.

At least one alternative must match.

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 2.account_type: alternative 1

Type: `"checking" / "savings"`. 

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 2.account_type: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 2.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 2.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 2.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 2.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 2.bank_address: alternative 1.postal_code

At least one alternative must match.

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 2.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 2.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 2.bank_address: alternative 1.region

At least one alternative must match.

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 2.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 2.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 2.bank_address: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 2.bank_name

At least one alternative must match.

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 2.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 2.bank_name: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 2.bic

At least one alternative must match.

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 2.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 2.bic: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 2.routing_codes

Type: `object[]`. minItems: 1; maxItems: 16

###### Request body schema: alternative 2.destination.destination.bank_coordinates: alternative 2.routing_codes item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `type` | string | Yes | minLength: 1; maxLength: 64 |
| `value` | string | Yes | minLength: 1; maxLength: 64 |

Additional fields are not accepted.

###### Request body schema: alternative 2.destination.destination.reference_hint

At least one alternative must match.

###### Request body schema: alternative 2.destination.destination.reference_hint: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema: alternative 2.destination.destination.reference_hint: alternative 2

Type: `null`. 

###### Request body schema: alternative 2.destination.payment_reference

At least one alternative must match.

###### Request body schema: alternative 2.destination.payment_reference: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema: alternative 2.destination.payment_reference: alternative 2

Type: `null`.

**Request example:**

```json
{
  "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "amount": {
    "currency": "USDC",
    "value": "250.00"
  },
  "destination": {
    "destination": {
      "bank_coordinates": {
        "account_holder_name": "Acme Treasury",
        "bank_name": "Demo Bank",
        "bic": "NWBKGB2L",
        "country": "GB",
        "iban": "GB29NWBK60161331926819",
        "scheme": "iban"
      },
      "beneficiary_name": "Acme Treasury",
      "currency": "EUR",
      "fiat_rail": "sepa_credit_transfer",
      "method": "bank_transfer",
      "reference_hint": null
    },
    "fiat_rail": "sepa_credit_transfer",
    "method": "bank_transfer",
    "payment_reference": "RF18539007547034",
    "route_owner_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "withdrawal_destination_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
  },
  "target_currency": "EUR",
  "target_rail": "fiat"
}
```

### off-ramp-sessions-create Response 201 schema

Content type: `application/json`.

#### application/json body

| 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})$` |
| `admission_hold_reason` | "CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED" or null | No |  |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `created_at` | string or string | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "deposit" / "withdrawal" / "conversion" / "external_settlement_conversion" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension" | Yes |  |
| `family_params` | object | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `principal_amount` | object | Yes | No additional fields |
| `settled_at` | string or string or null | Yes |  |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

##### application/json body.admission_hold_reason

At least one alternative must match.

###### application/json body.admission_hold_reason: alternative 1

Type: `"CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED"`. 

###### application/json body.admission_hold_reason: alternative 2

Type: `null`. 

##### application/json body.approval_ref

At least one alternative must match.

###### application/json body.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body.approval_ref: alternative 2

Type: `null`. 

##### application/json body.compliance_assessment_ref

At least one alternative must match.

###### application/json body.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body.compliance_assessment_ref: alternative 2

Type: `null`. 

##### application/json body.created_at

At least one alternative must match.

###### application/json body.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.created_at: alternative 2

Type: `string`. format: date-time

##### application/json body.failure_reason

At least one alternative must match.

###### application/json body.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.failure_reason: alternative 2

Type: `null`. 

##### application/json body.fee_summary

At least one alternative must match.

###### application/json body.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body.fee_summary: alternative 1.components item.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.

###### application/json body.fee_summary: alternative 1.total

| 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.

###### application/json body.fee_summary: alternative 2

Type: `null`. 

##### application/json body.fill_rate

At least one alternative must match.

###### application/json body.fill_rate: alternative 1

Type: `string`. 

###### application/json body.fill_rate: alternative 2

Type: `null`. 

##### application/json body.principal_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.

##### application/json body.settled_at

At least one alternative must match.

###### application/json body.settled_at: alternative 1

At least one alternative must match.

###### application/json body.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.settled_at: alternative 2

Type: `null`. 

##### application/json body.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.federation

At least one alternative must match.

###### application/json body.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject: alternative 2

Type: `null`. 

##### application/json body.updated_at

At least one alternative must match.

###### application/json body.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.updated_at: alternative 2

Type: `string`. format: date-time


### off-ramp-sessions-create 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.


### off-ramp-sessions-create Response 401 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.


### off-ramp-sessions-create Response 403 schema

Content type: `application/json`.

See [response 401 schema](#off-ramp-sessions-create-response-401-schema).


### off-ramp-sessions-create Response 409 schema

Content type: `application/json`.

See [response 401 schema](#off-ramp-sessions-create-response-401-schema).


### off-ramp-sessions-create Response 422 schema

Content type: `application/json`.

See [response 401 schema](#off-ramp-sessions-create-response-401-schema).


### off-ramp-sessions-create Response 500 schema

Content type: `application/json`.

See [response 401 schema](#off-ramp-sessions-create-response-401-schema).


### off-ramp-sessions-create Response 502 schema

Content type: `application/json`.

See [response 400 schema](#off-ramp-sessions-create-response-400-schema).


### off-ramp-sessions-create Response 503 schema

Content type: `application/json`.

See [response 400 schema](#off-ramp-sessions-create-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "approval_ref": null,
    "created_at": "2026-05-01T10:00:00Z",
    "failure_reason": null,
    "family": "off_ramp",
    "family_params": {
      "destination_payload": {
        "destination": {
          "bank_coordinates": {
            "account_holder_name": "Acme Treasury",
            "bank_name": "Demo Bank",
            "bic": "NWBKGB2L",
            "country": "GB",
            "iban": "GB29NWBK60161331926819",
            "scheme": "iban"
          },
          "beneficiary_name": "Acme Treasury",
          "currency": "EUR",
          "fiat_rail": "sepa_credit_transfer",
          "method": "bank_transfer",
          "reference_hint": null
        },
        "fiat_rail": "sepa_credit_transfer",
        "method": "bank_transfer",
        "payment_reference": "RF18539007547034",
        "withdrawal_destination_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "intermediate_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "source_amount": {
        "currency": "USDC",
        "value": "250.00"
      },
      "source_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "target_currency": "EUR",
      "target_rail": "fiat"
    },
    "fee_summary": null,
    "fill_rate": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "principal_amount": {
      "currency": "USDC",
      "value": "250.00"
    },
    "settled_at": null,
    "status": "admissible",
    "subject_attribution": {
      "actor": null,
      "approved_by": null,
      "authenticated_principal": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "enterprise_binding": {
        "tenant_type": "enterprise",
        "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "federation": null,
      "identity_source": "platform-managed",
      "initiated_by": null,
      "subject": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      }
    },
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `422` — The request cannot be processed under the resource or route contract. Depending on the endpoint, code can be not_admissible or unsupported_currency; inspect the documented code and data.reason.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /off-ramp-sessions/{session_id}

**Get off-ramp session**

**Required capability:** `ramps.read`

**Authentication:** Bearer token required.

**Parameters:**

- `session_id` `string` (path) *(required)*

### off-ramp-sessions-get Response 200 schema

Content type: `application/json`.

#### application/json body

At least one alternative must match.

##### application/json body: 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})$` |
| `applied_rate` | string or null | Yes |  |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `conversion_execution_id` | string or null | Yes |  |
| `created_at` | string or string | Yes |  |
| `failure_detail` | object or null | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "conversion" | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fee_transaction_ids` | string[] or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `ledger_posted_target_amount` | object or null | Yes |  |
| `leg_attempt_id` | string or null | Yes |  |
| `posted_at` | string or string or null | Yes |  |
| `principal_amount` | object | Yes | No additional fields |
| `principal_transaction_id` | string or null | Yes |  |
| `settled_at` | string or string or null | Yes |  |
| `source_gross_amount` | object or null | Yes |  |
| `source_principal_amount` | object or null | Yes |  |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `target_amount` | object or null | Yes |  |
| `target_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 1.applied_rate

At least one alternative must match.

###### application/json body: alternative 1.applied_rate: alternative 1

DecimalString

Type: `string`. pattern: `^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$`

###### application/json body: alternative 1.applied_rate: alternative 2

Type: `null`. 

###### application/json body: alternative 1.approval_ref

At least one alternative must match.

###### application/json body: alternative 1.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 1.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body: alternative 1.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 1.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 1.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body: alternative 1.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body: alternative 1.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body: alternative 1.approval_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 1.compliance_assessment_ref

At least one alternative must match.

###### application/json body: alternative 1.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body: alternative 1.compliance_assessment_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 1.conversion_execution_id

At least one alternative must match.

###### application/json body: alternative 1.conversion_execution_id: alternative 1

Type: `string`. 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)$`

###### application/json body: alternative 1.conversion_execution_id: alternative 2

Type: `null`. 

###### application/json body: alternative 1.created_at

At least one alternative must match.

###### application/json body: alternative 1.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 1.created_at: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 1.failure_detail

At least one alternative must match.

###### application/json body: alternative 1.failure_detail: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `failed_at` | string or string or null | Yes |  |
| `reason_code` | string | Yes | pattern: `^[a-z0-9_.:-]+$`; minLength: 1; maxLength: 128 |
| `retryable` | boolean or null | Yes |  |
| `stage` | "pre_execution" / "execution" / "post_fill" / "ledger_posting" / "unknown" | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 1.failure_detail: alternative 1.failed_at

At least one alternative must match.

###### application/json body: alternative 1.failure_detail: alternative 1.failed_at: alternative 1

At least one alternative must match.

###### application/json body: alternative 1.failure_detail: alternative 1.failed_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 1.failure_detail: alternative 1.failed_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 1.failure_detail: alternative 1.failed_at: alternative 2

Type: `null`. 

###### application/json body: alternative 1.failure_detail: alternative 1.retryable

At least one alternative must match.

###### application/json body: alternative 1.failure_detail: alternative 1.retryable: alternative 1

Type: `boolean`. 

###### application/json body: alternative 1.failure_detail: alternative 1.retryable: alternative 2

Type: `null`. 

###### application/json body: alternative 1.failure_detail: alternative 2

Type: `null`. 

###### application/json body: alternative 1.failure_reason

At least one alternative must match.

###### application/json body: alternative 1.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body: alternative 1.failure_reason: alternative 2

Type: `null`. 

###### application/json body: alternative 1.fee_summary

At least one alternative must match.

###### application/json body: alternative 1.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body: alternative 1.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body: alternative 1.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 1.fee_summary: alternative 1.components item.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.

###### application/json body: alternative 1.fee_summary: alternative 1.total

| 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.

###### application/json body: alternative 1.fee_summary: alternative 2

Type: `null`. 

###### application/json body: alternative 1.fee_transaction_ids

At least one alternative must match.

###### application/json body: alternative 1.fee_transaction_ids: alternative 1

Type: `string[]`. 

###### application/json body: alternative 1.fee_transaction_ids: alternative 1 item

Type: `string`. 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)$`

###### application/json body: alternative 1.fee_transaction_ids: alternative 2

Type: `null`. 

###### application/json body: alternative 1.fill_rate

At least one alternative must match.

###### application/json body: alternative 1.fill_rate: alternative 1

Type: `string`. 

###### application/json body: alternative 1.fill_rate: alternative 2

Type: `null`. 

###### application/json body: alternative 1.ledger_posted_target_amount

At least one alternative must match.

###### application/json body: alternative 1.ledger_posted_target_amount: alternative 1

| 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.

###### application/json body: alternative 1.ledger_posted_target_amount: alternative 2

Type: `null`. 

###### application/json body: alternative 1.leg_attempt_id

At least one alternative must match.

###### application/json body: alternative 1.leg_attempt_id: alternative 1

Type: `string`. 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)$`

###### application/json body: alternative 1.leg_attempt_id: alternative 2

Type: `null`. 

###### application/json body: alternative 1.posted_at

At least one alternative must match.

###### application/json body: alternative 1.posted_at: alternative 1

At least one alternative must match.

###### application/json body: alternative 1.posted_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 1.posted_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 1.posted_at: alternative 2

Type: `null`. 

###### application/json body: alternative 1.principal_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.

###### application/json body: alternative 1.principal_transaction_id

At least one alternative must match.

###### application/json body: alternative 1.principal_transaction_id: alternative 1

Type: `string`. 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)$`

###### application/json body: alternative 1.principal_transaction_id: alternative 2

Type: `null`. 

###### application/json body: alternative 1.settled_at

At least one alternative must match.

###### application/json body: alternative 1.settled_at: alternative 1

At least one alternative must match.

###### application/json body: alternative 1.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 1.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 1.settled_at: alternative 2

Type: `null`. 

###### application/json body: alternative 1.source_gross_amount

At least one alternative must match.

###### application/json body: alternative 1.source_gross_amount: alternative 1

| 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.

###### application/json body: alternative 1.source_gross_amount: alternative 2

Type: `null`. 

###### application/json body: alternative 1.source_principal_amount

At least one alternative must match.

###### application/json body: alternative 1.source_principal_amount: alternative 1

| 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.

###### application/json body: alternative 1.source_principal_amount: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 1.subject_attribution.actor

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 1.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 1.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution.approved_by

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 1.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 1.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 1.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 1.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 1.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 1.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution.federation

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body: alternative 1.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 1.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 1.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution.subject

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 1.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 1.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 1.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 1.subject_attribution.subject: alternative 2

Type: `null`. 

###### application/json body: alternative 1.target_amount

At least one alternative must match.

###### application/json body: alternative 1.target_amount: alternative 1

| 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.

###### application/json body: alternative 1.target_amount: alternative 2

Type: `null`. 

###### application/json body: alternative 1.updated_at

At least one alternative must match.

###### application/json body: alternative 1.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 1.updated_at: alternative 2

Type: `string`. format: date-time

##### application/json body: 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})$` |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `created_at` | string or string | Yes |  |
| `external_settlement_role` | "external_source_spend" / "external_target_disbursement" | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "external_settlement_conversion" | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `internal_settlement_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})$` |
| `principal_amount` | object | Yes | No additional fields |
| `settled_at` | string or string or null | Yes |  |
| `settlement_checked_at` | string or string | Yes |  |
| `settlement_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `target_currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 2.approval_ref

At least one alternative must match.

###### application/json body: alternative 2.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 2.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body: alternative 2.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 2.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 2.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body: alternative 2.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body: alternative 2.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body: alternative 2.approval_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 2.compliance_assessment_ref

At least one alternative must match.

###### application/json body: alternative 2.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body: alternative 2.compliance_assessment_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 2.created_at

At least one alternative must match.

###### application/json body: alternative 2.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 2.created_at: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 2.failure_reason

At least one alternative must match.

###### application/json body: alternative 2.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body: alternative 2.failure_reason: alternative 2

Type: `null`. 

###### application/json body: alternative 2.fee_summary

At least one alternative must match.

###### application/json body: alternative 2.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body: alternative 2.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body: alternative 2.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 2.fee_summary: alternative 1.components item.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.

###### application/json body: alternative 2.fee_summary: alternative 1.total

| 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.

###### application/json body: alternative 2.fee_summary: alternative 2

Type: `null`. 

###### application/json body: alternative 2.fill_rate

At least one alternative must match.

###### application/json body: alternative 2.fill_rate: alternative 1

Type: `string`. 

###### application/json body: alternative 2.fill_rate: alternative 2

Type: `null`. 

###### application/json body: alternative 2.principal_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.

###### application/json body: alternative 2.settled_at

At least one alternative must match.

###### application/json body: alternative 2.settled_at: alternative 1

At least one alternative must match.

###### application/json body: alternative 2.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 2.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 2.settled_at: alternative 2

Type: `null`. 

###### application/json body: alternative 2.settlement_checked_at

At least one alternative must match.

###### application/json body: alternative 2.settlement_checked_at: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 2.settlement_checked_at: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 2.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 2.subject_attribution.actor

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 2.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 2.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 2.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body: alternative 2.subject_attribution.approved_by

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 2.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 2.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 2.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body: alternative 2.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 2.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 2.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 2.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 2.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 2.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 2.subject_attribution.federation

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body: alternative 2.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body: alternative 2.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 2.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 2.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 2.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body: alternative 2.subject_attribution.subject

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 2.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 2.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 2.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 2.subject_attribution.subject: alternative 2

Type: `null`. 

###### application/json body: alternative 2.updated_at

At least one alternative must match.

###### application/json body: alternative 2.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 2.updated_at: alternative 2

Type: `string`. format: date-time

##### application/json body: alternative 3

| 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})$` |
| `admission_hold_reason` | "CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED" or null | No |  |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `created_at` | string or string | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "deposit" / "withdrawal" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension" | Yes |  |
| `family_params` | object | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `principal_amount` | object | Yes | No additional fields |
| `settled_at` | string or string or null | Yes |  |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 3.admission_hold_reason

At least one alternative must match.

###### application/json body: alternative 3.admission_hold_reason: alternative 1

Type: `"CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED"`. 

###### application/json body: alternative 3.admission_hold_reason: alternative 2

Type: `null`. 

###### application/json body: alternative 3.approval_ref

At least one alternative must match.

###### application/json body: alternative 3.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 3.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body: alternative 3.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 3.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 3.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body: alternative 3.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body: alternative 3.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body: alternative 3.approval_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 3.compliance_assessment_ref

At least one alternative must match.

###### application/json body: alternative 3.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body: alternative 3.compliance_assessment_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 3.created_at

At least one alternative must match.

###### application/json body: alternative 3.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 3.created_at: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 3.failure_reason

At least one alternative must match.

###### application/json body: alternative 3.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body: alternative 3.failure_reason: alternative 2

Type: `null`. 

###### application/json body: alternative 3.fee_summary

At least one alternative must match.

###### application/json body: alternative 3.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body: alternative 3.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body: alternative 3.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 3.fee_summary: alternative 1.components item.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.

###### application/json body: alternative 3.fee_summary: alternative 1.total

| 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.

###### application/json body: alternative 3.fee_summary: alternative 2

Type: `null`. 

###### application/json body: alternative 3.fill_rate

At least one alternative must match.

###### application/json body: alternative 3.fill_rate: alternative 1

Type: `string`. 

###### application/json body: alternative 3.fill_rate: alternative 2

Type: `null`. 

###### application/json body: alternative 3.principal_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.

###### application/json body: alternative 3.settled_at

At least one alternative must match.

###### application/json body: alternative 3.settled_at: alternative 1

At least one alternative must match.

###### application/json body: alternative 3.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 3.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body: alternative 3.settled_at: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 3.subject_attribution.actor

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 3.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 3.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution.approved_by

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 3.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 3.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 3.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 3.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body: alternative 3.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 3.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution.federation

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body: alternative 3.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 3.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 3.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution.subject

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body: alternative 3.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body: alternative 3.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body: alternative 3.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body: alternative 3.subject_attribution.subject: alternative 2

Type: `null`. 

###### application/json body: alternative 3.updated_at

At least one alternative must match.

###### application/json body: alternative 3.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body: alternative 3.updated_at: alternative 2

Type: `string`. format: date-time


### off-ramp-sessions-get 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.


### off-ramp-sessions-get Response 401 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.


### off-ramp-sessions-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#off-ramp-sessions-get-response-401-schema).


### off-ramp-sessions-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#off-ramp-sessions-get-response-401-schema).


### off-ramp-sessions-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#off-ramp-sessions-get-response-401-schema).


### off-ramp-sessions-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#off-ramp-sessions-get-response-400-schema).


### off-ramp-sessions-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#off-ramp-sessions-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "approval_ref": null,
    "created_at": "2026-05-01T10:00:00Z",
    "failure_reason": null,
    "family": "off_ramp",
    "family_params": {
      "destination_payload": {
        "destination": {
          "bank_coordinates": {
            "account_holder_name": "Acme Treasury",
            "bank_name": "Demo Bank",
            "bic": "NWBKGB2L",
            "country": "GB",
            "iban": "GB29NWBK60161331926819",
            "scheme": "iban"
          },
          "beneficiary_name": "Acme Treasury",
          "currency": "EUR",
          "fiat_rail": "sepa_credit_transfer",
          "method": "bank_transfer",
          "reference_hint": null
        },
        "fiat_rail": "sepa_credit_transfer",
        "method": "bank_transfer",
        "payment_reference": "RF18539007547034",
        "withdrawal_destination_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "intermediate_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "source_amount": {
        "currency": "USDC",
        "value": "250.00"
      },
      "source_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "target_currency": "EUR",
      "target_rail": "fiat"
    },
    "fee_summary": {
      "components": [
        {
          "amount": {
            "currency": "USDC",
            "value": "1.00"
          },
          "kind": "network_fee"
        }
      ],
      "total": {
        "currency": "USDC",
        "value": "1.00"
      }
    },
    "fill_rate": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "principal_amount": {
      "currency": "USDC",
      "value": "250.00"
    },
    "settled_at": null,
    "status": "admissible",
    "subject_attribution": {
      "actor": null,
      "approved_by": null,
      "authenticated_principal": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "enterprise_binding": {
        "tenant_type": "enterprise",
        "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "federation": null,
      "identity_source": "platform-managed",
      "initiated_by": null,
      "subject": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      }
    },
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /off-ramp-sessions/{session_id}/cancel

**Cancel off-ramp session**

**Required capability:** `ramps.manage`

**Authentication:** Bearer token required.

**Parameters:**

- `session_id` `string` (path) *(required)*
- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

### off-ramp-sessions-cancel Response 201 schema

Content type: `application/json`.

#### application/json body

| 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})$` |
| `admission_hold_reason` | "CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED" or null | No |  |
| `approval_ref` | object or null | Yes |  |
| `compliance_assessment_ref` | string or null | No |  |
| `created_at` | string or string | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `family` | "deposit" / "withdrawal" / "conversion" / "external_settlement_conversion" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension" | Yes |  |
| `family_params` | object | Yes |  |
| `fee_summary` | object or null | Yes |  |
| `fill_rate` | string or null | Yes |  |
| `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)$` |
| `principal_amount` | object | Yes | No additional fields |
| `settled_at` | string or string or null | Yes |  |
| `status` | "requested" / "admissible" / "executing" / "pending_approval" / "pending_admission" / "pending_compliance" / "executed" / "settled" / "ledger_visible" / "failed" / "cancelled" / "partially_settled" | Yes |  |
| `subject_attribution` | object | Yes | No additional fields |
| `updated_at` | string or string | Yes |  |

Additional fields are not accepted.

##### application/json body.admission_hold_reason

At least one alternative must match.

###### application/json body.admission_hold_reason: alternative 1

Type: `"CLIENT_NOT_VERIFIED" / "ENTERPRISE_NOT_VERIFIED" / "ENTERPRISE_NOT_OPERATIONAL" / "ENTERPRISE_RESTRICTED" / "ACCOUNT_SUSPENDED" / "ACCOUNT_CLOSED" / "CLIENT_SUSPENDED" / "CLIENT_CLOSED"`. 

###### application/json body.admission_hold_reason: alternative 2

Type: `null`. 

##### application/json body.approval_ref

At least one alternative must match.

###### application/json body.approval_ref: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `approval_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)$` |
| `expires_at` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.approval_ref: alternative 1.expires_at

At least one alternative must match.

###### application/json body.approval_ref: alternative 1.expires_at: alternative 1

Type: `string`. 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))$`

###### application/json body.approval_ref: alternative 1.expires_at: alternative 2

Type: `string`. format: date-time

###### application/json body.approval_ref: alternative 1.reason_code

At least one alternative must match.

###### application/json body.approval_ref: alternative 1.reason_code: alternative 1

Type: `string`. 

###### application/json body.approval_ref: alternative 1.reason_code: alternative 2

Type: `null`. 

###### application/json body.approval_ref: alternative 2

Type: `null`. 

##### application/json body.compliance_assessment_ref

At least one alternative must match.

###### application/json body.compliance_assessment_ref: alternative 1

Type: `string`. pattern: `^(compliance-assessments)\/([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})$`

###### application/json body.compliance_assessment_ref: alternative 2

Type: `null`. 

##### application/json body.created_at

At least one alternative must match.

###### application/json body.created_at: alternative 1

Type: `string`. 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))$`

###### application/json body.created_at: alternative 2

Type: `string`. format: date-time

##### application/json body.failure_reason

At least one alternative must match.

###### application/json body.failure_reason: alternative 1

Type: `string`. minLength: 1

###### application/json body.failure_reason: alternative 2

Type: `null`. 

##### application/json body.fee_summary

At least one alternative must match.

###### application/json body.fee_summary: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `components` | object[] | Yes |  |
| `total` | object | Yes | No additional fields |

Additional fields are not accepted.

###### application/json body.fee_summary: alternative 1.components

Type: `object[]`. 

###### application/json body.fee_summary: alternative 1.components item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `amount` | object | Yes | No additional fields |
| `kind` | "platform_fee" / "enterprise_fee" / "network_fee" / "spread" | Yes |  |

Additional fields are not accepted.

###### application/json body.fee_summary: alternative 1.components item.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.

###### application/json body.fee_summary: alternative 1.total

| 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.

###### application/json body.fee_summary: alternative 2

Type: `null`. 

##### application/json body.fill_rate

At least one alternative must match.

###### application/json body.fill_rate: alternative 1

Type: `string`. 

###### application/json body.fill_rate: alternative 2

Type: `null`. 

##### application/json body.principal_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.

##### application/json body.settled_at

At least one alternative must match.

###### application/json body.settled_at: alternative 1

At least one alternative must match.

###### application/json body.settled_at: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.settled_at: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.settled_at: alternative 2

Type: `null`. 

##### application/json body.subject_attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `enterprise_binding` | object | Yes | No additional fields |
| `federation` | object or null | Yes |  |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.actor: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.actor: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.approved_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.authenticated_principal.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.enterprise_binding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `tenant_type` | "enterprise" / "platform_operator" | Yes |  |
| `topology_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.enterprise_binding.topology_ref

At least one alternative must match.

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.enterprise_binding.topology_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.federation

At least one alternative must match.

###### application/json body.subject_attribution.federation: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_subject` | string | Yes | minLength: 1 |
| `issuer` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.subject_attribution.federation: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.initiated_by: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `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)$` |
| `kind` | "user" / "service" / "system" | Yes |  |
| `tenant_ref` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref

At least one alternative must match.

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients)\/([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})$`

###### application/json body.subject_attribution.subject: alternative 1.tenant_ref: alternative 2

Type: `null`. 

###### application/json body.subject_attribution.subject: alternative 2

Type: `null`. 

##### application/json body.updated_at

At least one alternative must match.

###### application/json body.updated_at: alternative 1

Type: `string`. 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))$`

###### application/json body.updated_at: alternative 2

Type: `string`. format: date-time


### off-ramp-sessions-cancel 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.


### off-ramp-sessions-cancel Response 401 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.


### off-ramp-sessions-cancel Response 403 schema

Content type: `application/json`.

See [response 401 schema](#off-ramp-sessions-cancel-response-401-schema).


### off-ramp-sessions-cancel Response 404 schema

Content type: `application/json`.

See [response 401 schema](#off-ramp-sessions-cancel-response-401-schema).


### off-ramp-sessions-cancel Response 409 schema

Content type: `application/json`.

See [response 401 schema](#off-ramp-sessions-cancel-response-401-schema).


### off-ramp-sessions-cancel Response 500 schema

Content type: `application/json`.

See [response 401 schema](#off-ramp-sessions-cancel-response-401-schema).


### off-ramp-sessions-cancel Response 502 schema

Content type: `application/json`.

See [response 400 schema](#off-ramp-sessions-cancel-response-400-schema).


### off-ramp-sessions-cancel Response 503 schema

Content type: `application/json`.

See [response 400 schema](#off-ramp-sessions-cancel-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "approval_ref": null,
    "created_at": "2026-05-01T10:00:00Z",
    "failure_reason": null,
    "family": "off_ramp",
    "family_params": {
      "destination_payload": {
        "destination": {
          "bank_coordinates": {
            "account_holder_name": "Acme Treasury",
            "bank_name": "Demo Bank",
            "bic": "NWBKGB2L",
            "country": "GB",
            "iban": "GB29NWBK60161331926819",
            "scheme": "iban"
          },
          "beneficiary_name": "Acme Treasury",
          "currency": "EUR",
          "fiat_rail": "sepa_credit_transfer",
          "method": "bank_transfer",
          "reference_hint": null
        },
        "fiat_rail": "sepa_credit_transfer",
        "method": "bank_transfer",
        "payment_reference": "RF18539007547034",
        "withdrawal_destination_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "intermediate_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "source_amount": {
        "currency": "USDC",
        "value": "250.00"
      },
      "source_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "target_currency": "EUR",
      "target_rail": "fiat"
    },
    "fee_summary": null,
    "fill_rate": null,
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "principal_amount": {
      "currency": "USDC",
      "value": "250.00"
    },
    "settled_at": null,
    "status": "cancelled",
    "subject_attribution": {
      "actor": null,
      "approved_by": null,
      "authenticated_principal": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "enterprise_binding": {
        "tenant_type": "enterprise",
        "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "federation": null,
      "identity_source": "platform-managed",
      "initiated_by": null,
      "subject": {
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "kind": "user",
        "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      }
    },
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Operations Activity Exports

### GET /operations-activity-exports

**List operations activity exports**

Lists exports within the current caller operations_reports.read coverage, with optional status and limit filters. limit defaults to 50 and is bounded 1..200. Results contain an items array without cursor pagination.

**Required capability:** `operations_reports.read`

**Authentication:** Bearer token required.

**Parameters:**

- `status` `string` (query)
- `limit` `integer` (query)

### operations-activity-exports-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `format` | "csv" / "json" | Yes |  |
| `byte_size` | integer or null | Yes |  |
| `download_path` | string or null | Yes |  |
| `expires_at_utc` | string or string or null | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `filter_criteria` | object | Yes | No additional fields |
| `finished_at_utc` | string or string or null | Yes |  |
| `generated_at_utc` | string or string | Yes |  |
| `generated_by` | string | Yes | pattern: `^(users\|service-accounts\|platform-principals\|identity-providers)\/([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})$` |
| `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)$` |
| `requested_scope` | object or object or object or object or object | Yes |  |
| `row_count` | integer or null | Yes |  |
| `status` | "queued" / "running" / "ready" / "failed" / "expired" | Yes |  |
| `storage_location` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.byte_size

At least one alternative must match.

###### application/json body.items item.byte_size: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### application/json body.items item.byte_size: alternative 2

Type: `null`. 

###### application/json body.items item.download_path

At least one alternative must match.

###### application/json body.items item.download_path: alternative 1

Type: `string`. 

###### application/json body.items item.download_path: alternative 2

Type: `null`. 

###### application/json body.items item.expires_at_utc

At least one alternative must match.

###### application/json body.items item.expires_at_utc: alternative 1

At least one alternative must match.

###### application/json body.items item.expires_at_utc: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.expires_at_utc: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.expires_at_utc: alternative 2

Type: `null`. 

###### application/json body.items item.failure_reason

At least one alternative must match.

###### application/json body.items item.failure_reason: alternative 1

Type: `string`. 

###### application/json body.items item.failure_reason: alternative 2

Type: `null`. 

###### application/json body.items item.filter_criteria

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `assets` | string[] | No |  |
| `client_account_refs` | string[] | No |  |
| `client_refs` | string[] | No |  |
| `date_from_utc` | string or string | Yes |  |
| `date_to_utc` | string or string | Yes |  |
| `failure_reason_codes` | string[] | No |  |
| `operation_families` | "deposit" / "withdrawal" / "conversion" / "external_settlement_conversion" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension"[] | No |  |
| `statuses` | "created" / "pending_approval" / "in_progress" / "completed" / "failed" / "cancelled" / "reversed" / "corrected"[] | No |  |

Additional fields are not accepted.

###### application/json body.items item.filter_criteria.assets

Type: `string[]`. 

###### application/json body.items item.filter_criteria.assets item

Currency code (ISO-4217 or on-chain ticker)

Type: `string`. pattern: `^[A-Z0-9]{1,16}$`

###### application/json body.items item.filter_criteria.client_account_refs

Type: `string[]`. 

###### application/json body.items item.filter_criteria.client_account_refs item

Type: `string`. pattern: `^(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})$`

###### application/json body.items item.filter_criteria.client_refs

Type: `string[]`. 

###### application/json body.items item.filter_criteria.client_refs item

Type: `string`. pattern: `^(clients)\/([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})$`

###### application/json body.items item.filter_criteria.date_from_utc

At least one alternative must match.

###### application/json body.items item.filter_criteria.date_from_utc: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.filter_criteria.date_from_utc: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.filter_criteria.date_to_utc

At least one alternative must match.

###### application/json body.items item.filter_criteria.date_to_utc: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.filter_criteria.date_to_utc: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.filter_criteria.failure_reason_codes

Type: `string[]`. 

###### application/json body.items item.filter_criteria.failure_reason_codes item

Type: `string`. minLength: 1

###### application/json body.items item.filter_criteria.operation_families

Type: `"deposit" / "withdrawal" / "conversion" / "external_settlement_conversion" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension"[]`. 

###### application/json body.items item.filter_criteria.operation_families item

Type: `"deposit" / "withdrawal" / "conversion" / "external_settlement_conversion" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension"`. 

###### application/json body.items item.filter_criteria.statuses

Type: `"created" / "pending_approval" / "in_progress" / "completed" / "failed" / "cancelled" / "reversed" / "corrected"[]`. 

###### application/json body.items item.filter_criteria.statuses item

Type: `"created" / "pending_approval" / "in_progress" / "completed" / "failed" / "cancelled" / "reversed" / "corrected"`. 

###### application/json body.items item.finished_at_utc

At least one alternative must match.

###### application/json body.items item.finished_at_utc: alternative 1

At least one alternative must match.

###### application/json body.items item.finished_at_utc: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.finished_at_utc: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.finished_at_utc: alternative 2

Type: `null`. 

###### application/json body.items item.generated_at_utc

At least one alternative must match.

###### application/json body.items item.generated_at_utc: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.generated_at_utc: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.requested_scope

Exactly one alternative must match.

###### application/json body.items item.requested_scope: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "enterprise" | Yes |  |
| `ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |

Additional fields are not accepted.

###### application/json body.items item.requested_scope: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "master_account" | Yes |  |
| `ref` | string | Yes | pattern: `^(master-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})$` |

Additional fields are not accepted.

###### application/json body.items item.requested_scope: alternative 3

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "client" | Yes |  |
| `ref` | string | Yes | pattern: `^(clients)\/([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})$` |

Additional fields are not accepted.

###### application/json body.items item.requested_scope: alternative 4

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "client_account" | Yes |  |
| `ref` | string | Yes | pattern: `^(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})$` |

Additional fields are not accepted.

###### application/json body.items item.requested_scope: alternative 5

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "platform_operator" | Yes |  |
| `ref` | string | Yes | pattern: `^(platform-operators)\/([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})$` |

Additional fields are not accepted.

###### application/json body.items item.row_count

At least one alternative must match.

###### application/json body.items item.row_count: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### application/json body.items item.row_count: alternative 2

Type: `null`. 

###### application/json body.items item.storage_location

At least one alternative must match.

###### application/json body.items item.storage_location: alternative 1

Type: `string`. 

###### application/json body.items item.storage_location: alternative 2

Type: `null`.


### operations-activity-exports-list 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.


### operations-activity-exports-list Response 401 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.


### operations-activity-exports-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#operations-activity-exports-list-response-401-schema).


### operations-activity-exports-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#operations-activity-exports-list-response-401-schema).


### operations-activity-exports-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#operations-activity-exports-list-response-400-schema).


### operations-activity-exports-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#operations-activity-exports-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "format": "csv",
        "byte_size": 32768,
        "download_path": "/operations-activity-exports/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b/download",
        "expires_at_utc": "2026-05-02T10:00:00Z",
        "failure_reason": null,
        "filter_criteria": {
          "date_from_utc": "2026-04-01T00:00:00Z",
          "date_to_utc": "2026-04-30T23:59:59Z"
        },
        "finished_at_utc": "2026-05-01T10:00:00Z",
        "generated_at_utc": "2026-05-01T10:00:00Z",
        "generated_by": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "requested_scope": {
          "kind": "enterprise",
          "ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
        },
        "row_count": 150,
        "status": "ready",
        "storage_location": null
      }
    ]
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /operations-activity-exports

**Create operations activity export**

Creates an operations activity export with format csv or json; json produces newline-delimited JSON. The time range must be strictly increasing. Requested scope requires operations_reports.create_export coverage; client_refs and client_account_refs filters also require operations_reports.read coverage. Inspect status and download_path for readiness. storage_location is always null; download_path is a relative gateway route.

**Required capability:** `operations_reports.create_export`

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `format` | "csv" / "json" | Yes |  |
| `filter_criteria` | object | Yes | No additional fields |
| `requested_scope` | object or object or object or object or object | Yes |  |

Additional fields are not accepted.

#### Request body schema.filter_criteria

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `assets` | string[] | No |  |
| `client_account_refs` | string[] | No |  |
| `client_refs` | string[] | No |  |
| `date_from_utc` | string or string | Yes |  |
| `date_to_utc` | string or string | Yes |  |
| `failure_reason_codes` | string[] | No |  |
| `operation_families` | "deposit" / "withdrawal" / "conversion" / "external_settlement_conversion" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension"[] | No |  |
| `statuses` | "created" / "pending_approval" / "in_progress" / "completed" / "failed" / "cancelled" / "reversed" / "corrected"[] | No |  |

Additional fields are not accepted.

##### Request body schema.filter_criteria.assets

Type: `string[]`. 

###### Request body schema.filter_criteria.assets item

Currency code (ISO-4217 or on-chain ticker)

Type: `string`. pattern: `^[A-Z0-9]{1,16}$`

##### Request body schema.filter_criteria.client_account_refs

Type: `string[]`. 

###### Request body schema.filter_criteria.client_account_refs item

Type: `string`. pattern: `^(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})$`

##### Request body schema.filter_criteria.client_refs

Type: `string[]`. 

###### Request body schema.filter_criteria.client_refs item

Type: `string`. pattern: `^(clients)\/([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})$`

##### Request body schema.filter_criteria.date_from_utc

At least one alternative must match.

###### Request body schema.filter_criteria.date_from_utc: alternative 1

Type: `string`. 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))$`

###### Request body schema.filter_criteria.date_from_utc: alternative 2

Type: `string`. format: date-time

##### Request body schema.filter_criteria.date_to_utc

At least one alternative must match.

###### Request body schema.filter_criteria.date_to_utc: alternative 1

Type: `string`. 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))$`

###### Request body schema.filter_criteria.date_to_utc: alternative 2

Type: `string`. format: date-time

##### Request body schema.filter_criteria.failure_reason_codes

Type: `string[]`. 

###### Request body schema.filter_criteria.failure_reason_codes item

Type: `string`. minLength: 1

##### Request body schema.filter_criteria.operation_families

Type: `"deposit" / "withdrawal" / "conversion" / "external_settlement_conversion" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension"[]`. 

###### Request body schema.filter_criteria.operation_families item

Type: `"deposit" / "withdrawal" / "conversion" / "external_settlement_conversion" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension"`. 

##### Request body schema.filter_criteria.statuses

Type: `"created" / "pending_approval" / "in_progress" / "completed" / "failed" / "cancelled" / "reversed" / "corrected"[]`. 

###### Request body schema.filter_criteria.statuses item

Type: `"created" / "pending_approval" / "in_progress" / "completed" / "failed" / "cancelled" / "reversed" / "corrected"`. 

#### Request body schema.requested_scope

Exactly one alternative must match.

##### Request body schema.requested_scope: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "enterprise" | Yes |  |
| `ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |

Additional fields are not accepted.

##### Request body schema.requested_scope: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "master_account" | Yes |  |
| `ref` | string | Yes | pattern: `^(master-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})$` |

Additional fields are not accepted.

##### Request body schema.requested_scope: alternative 3

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "client" | Yes |  |
| `ref` | string | Yes | pattern: `^(clients)\/([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})$` |

Additional fields are not accepted.

##### Request body schema.requested_scope: alternative 4

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "client_account" | Yes |  |
| `ref` | string | Yes | pattern: `^(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})$` |

Additional fields are not accepted.

##### Request body schema.requested_scope: alternative 5

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "platform_operator" | Yes |  |
| `ref` | string | Yes | pattern: `^(platform-operators)\/([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})$` |

Additional fields are not accepted.

**Request example:**

```json
{
  "format": "csv",
  "filter_criteria": {
    "date_from_utc": "2026-04-01T00:00:00Z",
    "date_to_utc": "2026-04-30T23:59:59Z"
  },
  "requested_scope": {
    "kind": "enterprise",
    "ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
  }
}
```

### operations-activity-exports-create Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `format` | "csv" / "json" | Yes |  |
| `byte_size` | integer or null | Yes |  |
| `download_path` | string or null | Yes |  |
| `expires_at_utc` | string or string or null | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `filter_criteria` | object | Yes | No additional fields |
| `finished_at_utc` | string or string or null | Yes |  |
| `generated_at_utc` | string or string | Yes |  |
| `generated_by` | string | Yes | pattern: `^(users\|service-accounts\|platform-principals\|identity-providers)\/([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})$` |
| `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)$` |
| `requested_scope` | object or object or object or object or object | Yes |  |
| `row_count` | integer or null | Yes |  |
| `status` | "queued" / "running" / "ready" / "failed" / "expired" | Yes |  |
| `storage_location` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.byte_size

At least one alternative must match.

###### application/json body.byte_size: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### application/json body.byte_size: alternative 2

Type: `null`. 

##### application/json body.download_path

At least one alternative must match.

###### application/json body.download_path: alternative 1

Type: `string`. 

###### application/json body.download_path: alternative 2

Type: `null`. 

##### application/json body.expires_at_utc

At least one alternative must match.

###### application/json body.expires_at_utc: alternative 1

At least one alternative must match.

###### application/json body.expires_at_utc: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.expires_at_utc: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.expires_at_utc: alternative 2

Type: `null`. 

##### application/json body.failure_reason

At least one alternative must match.

###### application/json body.failure_reason: alternative 1

Type: `string`. 

###### application/json body.failure_reason: alternative 2

Type: `null`. 

##### application/json body.filter_criteria

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `assets` | string[] | No |  |
| `client_account_refs` | string[] | No |  |
| `client_refs` | string[] | No |  |
| `date_from_utc` | string or string | Yes |  |
| `date_to_utc` | string or string | Yes |  |
| `failure_reason_codes` | string[] | No |  |
| `operation_families` | "deposit" / "withdrawal" / "conversion" / "external_settlement_conversion" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension"[] | No |  |
| `statuses` | "created" / "pending_approval" / "in_progress" / "completed" / "failed" / "cancelled" / "reversed" / "corrected"[] | No |  |

Additional fields are not accepted.

###### application/json body.filter_criteria.assets

Type: `string[]`. 

###### application/json body.filter_criteria.assets item

Currency code (ISO-4217 or on-chain ticker)

Type: `string`. pattern: `^[A-Z0-9]{1,16}$`

###### application/json body.filter_criteria.client_account_refs

Type: `string[]`. 

###### application/json body.filter_criteria.client_account_refs item

Type: `string`. pattern: `^(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})$`

###### application/json body.filter_criteria.client_refs

Type: `string[]`. 

###### application/json body.filter_criteria.client_refs item

Type: `string`. pattern: `^(clients)\/([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})$`

###### application/json body.filter_criteria.date_from_utc

At least one alternative must match.

###### application/json body.filter_criteria.date_from_utc: alternative 1

Type: `string`. 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))$`

###### application/json body.filter_criteria.date_from_utc: alternative 2

Type: `string`. format: date-time

###### application/json body.filter_criteria.date_to_utc

At least one alternative must match.

###### application/json body.filter_criteria.date_to_utc: alternative 1

Type: `string`. 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))$`

###### application/json body.filter_criteria.date_to_utc: alternative 2

Type: `string`. format: date-time

###### application/json body.filter_criteria.failure_reason_codes

Type: `string[]`. 

###### application/json body.filter_criteria.failure_reason_codes item

Type: `string`. minLength: 1

###### application/json body.filter_criteria.operation_families

Type: `"deposit" / "withdrawal" / "conversion" / "external_settlement_conversion" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension"[]`. 

###### application/json body.filter_criteria.operation_families item

Type: `"deposit" / "withdrawal" / "conversion" / "external_settlement_conversion" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension"`. 

###### application/json body.filter_criteria.statuses

Type: `"created" / "pending_approval" / "in_progress" / "completed" / "failed" / "cancelled" / "reversed" / "corrected"[]`. 

###### application/json body.filter_criteria.statuses item

Type: `"created" / "pending_approval" / "in_progress" / "completed" / "failed" / "cancelled" / "reversed" / "corrected"`. 

##### application/json body.finished_at_utc

At least one alternative must match.

###### application/json body.finished_at_utc: alternative 1

At least one alternative must match.

###### application/json body.finished_at_utc: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.finished_at_utc: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.finished_at_utc: alternative 2

Type: `null`. 

##### application/json body.generated_at_utc

At least one alternative must match.

###### application/json body.generated_at_utc: alternative 1

Type: `string`. 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))$`

###### application/json body.generated_at_utc: alternative 2

Type: `string`. format: date-time

##### application/json body.requested_scope

Exactly one alternative must match.

###### application/json body.requested_scope: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "enterprise" | Yes |  |
| `ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |

Additional fields are not accepted.

###### application/json body.requested_scope: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "master_account" | Yes |  |
| `ref` | string | Yes | pattern: `^(master-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})$` |

Additional fields are not accepted.

###### application/json body.requested_scope: alternative 3

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "client" | Yes |  |
| `ref` | string | Yes | pattern: `^(clients)\/([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})$` |

Additional fields are not accepted.

###### application/json body.requested_scope: alternative 4

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "client_account" | Yes |  |
| `ref` | string | Yes | pattern: `^(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})$` |

Additional fields are not accepted.

###### application/json body.requested_scope: alternative 5

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "platform_operator" | Yes |  |
| `ref` | string | Yes | pattern: `^(platform-operators)\/([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})$` |

Additional fields are not accepted.

##### application/json body.row_count

At least one alternative must match.

###### application/json body.row_count: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### application/json body.row_count: alternative 2

Type: `null`. 

##### application/json body.storage_location

At least one alternative must match.

###### application/json body.storage_location: alternative 1

Type: `string`. 

###### application/json body.storage_location: alternative 2

Type: `null`.


### operations-activity-exports-create 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.


### operations-activity-exports-create Response 401 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.


### operations-activity-exports-create Response 403 schema

Content type: `application/json`.

See [response 401 schema](#operations-activity-exports-create-response-401-schema).


### operations-activity-exports-create Response 409 schema

Content type: `application/json`.

See [response 401 schema](#operations-activity-exports-create-response-401-schema).


### operations-activity-exports-create Response 500 schema

Content type: `application/json`.

See [response 401 schema](#operations-activity-exports-create-response-401-schema).


### operations-activity-exports-create Response 502 schema

Content type: `application/json`.

See [response 400 schema](#operations-activity-exports-create-response-400-schema).


### operations-activity-exports-create Response 503 schema

Content type: `application/json`.

See [response 400 schema](#operations-activity-exports-create-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "format": "csv",
    "byte_size": 32768,
    "download_path": "/operations-activity-exports/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b/download",
    "expires_at_utc": "2026-05-02T10:00:00Z",
    "failure_reason": null,
    "filter_criteria": {
      "date_from_utc": "2026-04-01T00:00:00Z",
      "date_to_utc": "2026-04-30T23:59:59Z"
    },
    "finished_at_utc": "2026-05-01T10:00:00Z",
    "generated_at_utc": "2026-05-01T10:00:00Z",
    "generated_by": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "requested_scope": {
      "kind": "enterprise",
      "ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
    },
    "row_count": 150,
    "status": "ready",
    "storage_location": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /operations-activity-exports/{export_id}

**Get operations activity export**

Reads an export covered by operations_reports.read for its stored scope. Missing or hidden exports return 404. download_path is null until ready and after expiry.

**Required capability:** `operations_reports.read`

**Authentication:** Bearer token required.

**Parameters:**

- `export_id` `string` (path) *(required)*

### operations-activity-exports-get Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `format` | "csv" / "json" | Yes |  |
| `byte_size` | integer or null | Yes |  |
| `download_path` | string or null | Yes |  |
| `expires_at_utc` | string or string or null | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `filter_criteria` | object | Yes | No additional fields |
| `finished_at_utc` | string or string or null | Yes |  |
| `generated_at_utc` | string or string | Yes |  |
| `generated_by` | string | Yes | pattern: `^(users\|service-accounts\|platform-principals\|identity-providers)\/([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})$` |
| `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)$` |
| `requested_scope` | object or object or object or object or object | Yes |  |
| `row_count` | integer or null | Yes |  |
| `status` | "queued" / "running" / "ready" / "failed" / "expired" | Yes |  |
| `storage_location` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.byte_size

At least one alternative must match.

###### application/json body.byte_size: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### application/json body.byte_size: alternative 2

Type: `null`. 

##### application/json body.download_path

At least one alternative must match.

###### application/json body.download_path: alternative 1

Type: `string`. 

###### application/json body.download_path: alternative 2

Type: `null`. 

##### application/json body.expires_at_utc

At least one alternative must match.

###### application/json body.expires_at_utc: alternative 1

At least one alternative must match.

###### application/json body.expires_at_utc: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.expires_at_utc: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.expires_at_utc: alternative 2

Type: `null`. 

##### application/json body.failure_reason

At least one alternative must match.

###### application/json body.failure_reason: alternative 1

Type: `string`. 

###### application/json body.failure_reason: alternative 2

Type: `null`. 

##### application/json body.filter_criteria

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `assets` | string[] | No |  |
| `client_account_refs` | string[] | No |  |
| `client_refs` | string[] | No |  |
| `date_from_utc` | string or string | Yes |  |
| `date_to_utc` | string or string | Yes |  |
| `failure_reason_codes` | string[] | No |  |
| `operation_families` | "deposit" / "withdrawal" / "conversion" / "external_settlement_conversion" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension"[] | No |  |
| `statuses` | "created" / "pending_approval" / "in_progress" / "completed" / "failed" / "cancelled" / "reversed" / "corrected"[] | No |  |

Additional fields are not accepted.

###### application/json body.filter_criteria.assets

Type: `string[]`. 

###### application/json body.filter_criteria.assets item

Currency code (ISO-4217 or on-chain ticker)

Type: `string`. pattern: `^[A-Z0-9]{1,16}$`

###### application/json body.filter_criteria.client_account_refs

Type: `string[]`. 

###### application/json body.filter_criteria.client_account_refs item

Type: `string`. pattern: `^(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})$`

###### application/json body.filter_criteria.client_refs

Type: `string[]`. 

###### application/json body.filter_criteria.client_refs item

Type: `string`. pattern: `^(clients)\/([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})$`

###### application/json body.filter_criteria.date_from_utc

At least one alternative must match.

###### application/json body.filter_criteria.date_from_utc: alternative 1

Type: `string`. 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))$`

###### application/json body.filter_criteria.date_from_utc: alternative 2

Type: `string`. format: date-time

###### application/json body.filter_criteria.date_to_utc

At least one alternative must match.

###### application/json body.filter_criteria.date_to_utc: alternative 1

Type: `string`. 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))$`

###### application/json body.filter_criteria.date_to_utc: alternative 2

Type: `string`. format: date-time

###### application/json body.filter_criteria.failure_reason_codes

Type: `string[]`. 

###### application/json body.filter_criteria.failure_reason_codes item

Type: `string`. minLength: 1

###### application/json body.filter_criteria.operation_families

Type: `"deposit" / "withdrawal" / "conversion" / "external_settlement_conversion" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension"[]`. 

###### application/json body.filter_criteria.operation_families item

Type: `"deposit" / "withdrawal" / "conversion" / "external_settlement_conversion" / "internal_transfer" / "on_ramp" / "off_ramp" / "loan_origination" / "loan_repayment" / "loan_liquidation" / "loan_closing" / "loan_extension"`. 

###### application/json body.filter_criteria.statuses

Type: `"created" / "pending_approval" / "in_progress" / "completed" / "failed" / "cancelled" / "reversed" / "corrected"[]`. 

###### application/json body.filter_criteria.statuses item

Type: `"created" / "pending_approval" / "in_progress" / "completed" / "failed" / "cancelled" / "reversed" / "corrected"`. 

##### application/json body.finished_at_utc

At least one alternative must match.

###### application/json body.finished_at_utc: alternative 1

At least one alternative must match.

###### application/json body.finished_at_utc: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.finished_at_utc: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.finished_at_utc: alternative 2

Type: `null`. 

##### application/json body.generated_at_utc

At least one alternative must match.

###### application/json body.generated_at_utc: alternative 1

Type: `string`. 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))$`

###### application/json body.generated_at_utc: alternative 2

Type: `string`. format: date-time

##### application/json body.requested_scope

Exactly one alternative must match.

###### application/json body.requested_scope: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "enterprise" | Yes |  |
| `ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |

Additional fields are not accepted.

###### application/json body.requested_scope: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "master_account" | Yes |  |
| `ref` | string | Yes | pattern: `^(master-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})$` |

Additional fields are not accepted.

###### application/json body.requested_scope: alternative 3

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "client" | Yes |  |
| `ref` | string | Yes | pattern: `^(clients)\/([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})$` |

Additional fields are not accepted.

###### application/json body.requested_scope: alternative 4

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "client_account" | Yes |  |
| `ref` | string | Yes | pattern: `^(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})$` |

Additional fields are not accepted.

###### application/json body.requested_scope: alternative 5

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "platform_operator" | Yes |  |
| `ref` | string | Yes | pattern: `^(platform-operators)\/([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})$` |

Additional fields are not accepted.

##### application/json body.row_count

At least one alternative must match.

###### application/json body.row_count: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### application/json body.row_count: alternative 2

Type: `null`. 

##### application/json body.storage_location

At least one alternative must match.

###### application/json body.storage_location: alternative 1

Type: `string`. 

###### application/json body.storage_location: alternative 2

Type: `null`.


### operations-activity-exports-get 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.


### operations-activity-exports-get Response 401 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.


### operations-activity-exports-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#operations-activity-exports-get-response-401-schema).


### operations-activity-exports-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#operations-activity-exports-get-response-401-schema).


### operations-activity-exports-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#operations-activity-exports-get-response-401-schema).


### operations-activity-exports-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#operations-activity-exports-get-response-400-schema).


### operations-activity-exports-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#operations-activity-exports-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "format": "csv",
    "byte_size": 32768,
    "download_path": "/operations-activity-exports/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b/download",
    "expires_at_utc": "2026-05-02T10:00:00Z",
    "failure_reason": null,
    "filter_criteria": {
      "date_from_utc": "2026-04-01T00:00:00Z",
      "date_to_utc": "2026-04-30T23:59:59Z"
    },
    "finished_at_utc": "2026-05-01T10:00:00Z",
    "generated_at_utc": "2026-05-01T10:00:00Z",
    "generated_by": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "requested_scope": {
      "kind": "enterprise",
      "ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
    },
    "row_count": 150,
    "status": "ready",
    "storage_location": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /operations-activity-exports/{export_id}/download

**Download operations activity export file**

Streams the ready export through edge. csv yields text/csv and json yields application/x-ndjson: one JSON object per line, with UTF-8 encoding. Content-Type, Content-Disposition and optional Content-Length are forwarded from the download service. Unavailable, expired or hidden exports return 404; an unsuccessful upstream response other than 404 returns 502.

**Required capability:** `operations_reports.read`

**Authentication:** Bearer token required.

**Parameters:**

- `export_id` `string` (path) *(required)*

### operations-activity-exports-download Response 200 schema

Content type: `application/x-ndjson`.

#### application/x-ndjson body

UTF-8 newline-delimited JSON, one OperationsActivityRow object per line.

Type: `string`.

Content type: `text/csv`.

#### text/csv body

UTF-8 CSV file with a header row.

Type: `string`.


| Response header | Type | Description |
| --- | --- | --- |
| `Content-Disposition` | string |  |
| `Content-Length` | string |  |

### operations-activity-exports-download 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.


### operations-activity-exports-download Response 401 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.


### operations-activity-exports-download Response 403 schema

Content type: `application/json`.

See [response 401 schema](#operations-activity-exports-download-response-401-schema).


### operations-activity-exports-download Response 404 schema

Content type: `application/json`.

See [response 401 schema](#operations-activity-exports-download-response-401-schema).


### operations-activity-exports-download Response 500 schema

Content type: `application/json`.

See [response 401 schema](#operations-activity-exports-download-response-401-schema).


### operations-activity-exports-download Response 502 schema

Content type: `application/json`.

See [response 400 schema](#operations-activity-exports-download-response-400-schema).


### operations-activity-exports-download Response 503 schema

Content type: `application/json`.

See [response 400 schema](#operations-activity-exports-download-response-400-schema).


**Responses:**

- `200` — Operation succeeded.
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## User Action Audit Entries

### GET /user-action-audit-entries/{entry_id}

**Get audit log entry**

**Required capability:** `audit.read`

**Authentication:** Bearer token required.

**Parameters:**

- `entry_id` `string` (path) *(required)*

### user-action-audit-entries-get Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `action_family` | "human_actor_lifecycle" / "role_assignment" / "policy_change" / "service_account_governance" / "webhook_subscription_governance" / "financial_operation_audit" / "tenant_governance" / "approval_decision" / "authentication" / "other" or null | Yes |  |
| `approval_state` | "not_required" / "pending" / "approved" / "rejected" / "cancelled" / "expired" or null | Yes |  |
| `attribution` | object | Yes | No additional fields |
| `changed_fields` | object[] or null | Yes |  |
| `correlation_id` | string or null | Yes |  |
| `detail` | object or null | Yes |  |
| `event_id` | string or null | Yes |  |
| `event_type` | string | Yes | pattern: `^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){2,3}$` |
| `human_actor_id` | string or null | Yes |  |
| `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)$` |
| `occurred_at_utc` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |
| `reason_text` | string or null | Yes |  |
| `recorded_at_utc` | string or string | Yes |  |
| `request_id` | string or null | Yes |  |
| `resource_ref` | string or null | Yes |  |
| `resource_type` | string or null | Yes |  |
| `result_status` | "succeeded" / "failed" / "denied" / "rejected" / "cancelled" | Yes |  |
| `scope` | object | Yes | No additional fields |
| `service_account_id` | string or null | Yes |  |
| `source_service` | string | Yes | minLength: 1 |
| `trace_id` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.action_family

At least one alternative must match.

###### application/json body.action_family: alternative 1

Type: `"human_actor_lifecycle" / "role_assignment" / "policy_change" / "service_account_governance" / "webhook_subscription_governance" / "financial_operation_audit" / "tenant_governance" / "approval_decision" / "authentication" / "other"`. 

###### application/json body.action_family: alternative 2

Type: `null`. 

##### application/json body.approval_state

At least one alternative must match.

###### application/json body.approval_state: alternative 1

Type: `"not_required" / "pending" / "approved" / "rejected" / "cancelled" / "expired"`. 

###### application/json body.approval_state: alternative 2

Type: `null`. 

##### application/json body.attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.attribution.actor

At least one alternative must match.

###### application/json body.attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "user" / "service" / "system" | Yes |  |
| `ref` | string | Yes | pattern: `^(users\|service-accounts\|platform-principals\|identity-providers)\/([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})$` |

Additional fields are not accepted.

###### application/json body.attribution.actor: alternative 2

Type: `null`. 

###### application/json body.attribution.approved_by

At least one alternative must match.

###### application/json body.attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "user" / "service" / "system" | Yes |  |
| `ref` | string | Yes | pattern: `^(users\|service-accounts\|platform-principals\|identity-providers)\/([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})$` |

Additional fields are not accepted.

###### application/json body.attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "user" / "service" / "system" | Yes |  |
| `ref` | string | Yes | pattern: `^(users\|service-accounts\|platform-principals\|identity-providers)\/([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})$` |

Additional fields are not accepted.

###### application/json body.attribution.initiated_by

At least one alternative must match.

###### application/json body.attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "user" / "service" / "system" | Yes |  |
| `ref` | string | Yes | pattern: `^(users\|service-accounts\|platform-principals\|identity-providers)\/([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})$` |

Additional fields are not accepted.

###### application/json body.attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.attribution.subject

At least one alternative must match.

###### application/json body.attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "user" / "service" / "system" | Yes |  |
| `ref` | string | Yes | pattern: `^(users\|service-accounts\|platform-principals\|identity-providers)\/([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})$` |

Additional fields are not accepted.

###### application/json body.attribution.subject: alternative 2

Type: `null`. 

##### application/json body.changed_fields

At least one alternative must match.

###### application/json body.changed_fields: alternative 1

Type: `object[]`. 

###### application/json body.changed_fields: alternative 1 item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1 |
| `after` | unspecified | Yes |  |
| `before` | unspecified | Yes |  |

Additional fields are not accepted.

###### application/json body.changed_fields: alternative 2

Type: `null`. 

##### application/json body.correlation_id

At least one alternative must match.

###### application/json body.correlation_id: alternative 1

Type: `string`. 

###### application/json body.correlation_id: alternative 2

Type: `null`. 

##### application/json body.detail

At least one alternative must match.

###### application/json body.detail: alternative 1

Type: `object`. 

###### application/json body.detail: alternative 2

Type: `null`. 

##### application/json body.event_id

At least one alternative must match.

###### application/json body.event_id: alternative 1

Type: `string`. 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)$`

###### application/json body.event_id: alternative 2

Type: `null`. 

##### application/json body.human_actor_id

At least one alternative must match.

###### application/json body.human_actor_id: alternative 1

Type: `string`. 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)$`

###### application/json body.human_actor_id: alternative 2

Type: `null`. 

##### application/json body.occurred_at_utc

At least one alternative must match.

###### application/json body.occurred_at_utc: alternative 1

Type: `string`. 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))$`

###### application/json body.occurred_at_utc: alternative 2

Type: `string`. format: date-time

##### application/json body.reason_code

At least one alternative must match.

###### application/json body.reason_code: alternative 1

Type: `string`. 

###### application/json body.reason_code: alternative 2

Type: `null`. 

##### application/json body.reason_text

At least one alternative must match.

###### application/json body.reason_text: alternative 1

Type: `string`. 

###### application/json body.reason_text: alternative 2

Type: `null`. 

##### application/json body.recorded_at_utc

At least one alternative must match.

###### application/json body.recorded_at_utc: alternative 1

Type: `string`. 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))$`

###### application/json body.recorded_at_utc: alternative 2

Type: `string`. format: date-time

##### application/json body.request_id

At least one alternative must match.

###### application/json body.request_id: alternative 1

Type: `string`. 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)$`

###### application/json body.request_id: alternative 2

Type: `null`. 

##### application/json body.resource_ref

At least one alternative must match.

###### application/json body.resource_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients|master-accounts|client-accounts|users|service-accounts|platform-principals|identity-providers|roles|role-assignments|system-principals|commercial-agreements|policy-rules|operations|compliance-assessments|webhook-subscriptions)\/([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})$`

###### application/json body.resource_ref: alternative 2

Type: `null`. 

##### application/json body.resource_type

At least one alternative must match.

###### application/json body.resource_type: alternative 1

Type: `string`. minLength: 1

###### application/json body.resource_type: alternative 2

Type: `null`. 

##### application/json body.scope

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `client_account_ref` | string or null | Yes |  |
| `client_ref` | string or null | Yes |  |
| `enterprise_ref` | string or null | Yes |  |
| `master_account_ref` | string or null | Yes |  |
| `platform_operator_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.scope.client_account_ref

At least one alternative must match.

###### application/json body.scope.client_account_ref: alternative 1

Type: `string`. pattern: `^(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})$`

###### application/json body.scope.client_account_ref: alternative 2

Type: `null`. 

###### application/json body.scope.client_ref

At least one alternative must match.

###### application/json body.scope.client_ref: alternative 1

Type: `string`. pattern: `^(clients)\/([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})$`

###### application/json body.scope.client_ref: alternative 2

Type: `null`. 

###### application/json body.scope.enterprise_ref

At least one alternative must match.

###### application/json body.scope.enterprise_ref: alternative 1

Type: `string`. pattern: `^(enterprises)\/([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})$`

###### application/json body.scope.enterprise_ref: alternative 2

Type: `null`. 

###### application/json body.scope.master_account_ref

At least one alternative must match.

###### application/json body.scope.master_account_ref: alternative 1

Type: `string`. pattern: `^(master-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})$`

###### application/json body.scope.master_account_ref: alternative 2

Type: `null`. 

###### application/json body.scope.platform_operator_ref

At least one alternative must match.

###### application/json body.scope.platform_operator_ref: alternative 1

Type: `string`. pattern: `^(platform-operators)\/([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})$`

###### application/json body.scope.platform_operator_ref: alternative 2

Type: `null`. 

##### application/json body.service_account_id

At least one alternative must match.

###### application/json body.service_account_id: alternative 1

Type: `string`. 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)$`

###### application/json body.service_account_id: alternative 2

Type: `null`. 

##### application/json body.trace_id

At least one alternative must match.

###### application/json body.trace_id: alternative 1

Type: `string`. 

###### application/json body.trace_id: alternative 2

Type: `null`.


### user-action-audit-entries-get 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.


### user-action-audit-entries-get Response 401 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.


### user-action-audit-entries-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#user-action-audit-entries-get-response-401-schema).


### user-action-audit-entries-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#user-action-audit-entries-get-response-401-schema).


### user-action-audit-entries-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#user-action-audit-entries-get-response-401-schema).


### user-action-audit-entries-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#user-action-audit-entries-get-response-400-schema).


### user-action-audit-entries-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#user-action-audit-entries-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "action_family": "tenant_governance",
    "approval_state": "not_required",
    "attribution": {
      "actor": null,
      "approved_by": null,
      "authenticated_principal": {
        "kind": "user",
        "ref": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "identity_source": "platform-managed",
      "initiated_by": null,
      "subject": {
        "kind": "user",
        "ref": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      }
    },
    "changed_fields": null,
    "correlation_id": null,
    "detail": null,
    "event_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "event_type": "tenant.enterprise.admitted.v1",
    "human_actor_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "occurred_at_utc": "2026-05-01T10:00:00Z",
    "reason_code": null,
    "reason_text": null,
    "recorded_at_utc": "2026-05-01T10:00:00Z",
    "request_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "resource_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "resource_type": "enterprise",
    "result_status": "succeeded",
    "scope": {
      "client_account_ref": null,
      "client_ref": null,
      "enterprise_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "master_account_ref": null,
      "platform_operator_ref": null
    },
    "service_account_id": null,
    "source_service": "edge-service",
    "trace_id": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /user-action-audit-entries/search

**Search audit log entries**

Queries the immutable audit trail. occurred_from_utc and occurred_to_utc are required and must form a strictly increasing range. Supply at least one enterprise_ref, master_account_ref, client_ref or client_account_ref covered by audit.read, or use cross_scope=true with platform-wide audit.read authority. Cross-scope searches cannot include those scope filters. Multi-value event_types, action_families, result_statuses and reason_codes accept repeated query values or a single comma-separated value. limit defaults to 100, with range 1..500; offset defaults to 0 and must be nonnegative.

**Required capability:** `audit.read`

**Authentication:** Bearer token required.

**Parameters:**

- `enterprise_ref` `string` (query)
- `master_account_ref` `string` (query)
- `client_ref` `string` (query)
- `client_account_ref` `string` (query)
- `authenticated_principal` `string` (query)
- `subject` `string` (query)
- `actor` `string` (query)
- `resource_ref` `string` (query)
- `subject_ref` `string` (query)
- `actor_ref` `string` (query)
- `cross_scope` `string` (query)
- `source_service` `string` (query)
- `event_types` `string` (query)
- `action_families` `string` (query)
- `result_statuses` `string` (query)
- `reason_codes` `string` (query)
- `occurred_from_utc` `string` (query) *(required)*
- `occurred_to_utc` `string` (query) *(required)*
- `limit` `integer` (query)
- `offset` `integer` (query)

### user-action-audit-entries-search Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `limit` | integer | Yes | maximum: 9007199254740991; exclusiveMinimum: 0 |
| `offset` | integer | Yes | minimum: 0; maximum: 9007199254740991 |
| `total` | integer | Yes | minimum: 0; maximum: 9007199254740991 |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `action_family` | "human_actor_lifecycle" / "role_assignment" / "policy_change" / "service_account_governance" / "webhook_subscription_governance" / "financial_operation_audit" / "tenant_governance" / "approval_decision" / "authentication" / "other" or null | Yes |  |
| `approval_state` | "not_required" / "pending" / "approved" / "rejected" / "cancelled" / "expired" or null | Yes |  |
| `attribution` | object | Yes | No additional fields |
| `changed_fields` | object[] or null | Yes |  |
| `correlation_id` | string or null | Yes |  |
| `detail` | object or null | Yes |  |
| `event_id` | string or null | Yes |  |
| `event_type` | string | Yes | pattern: `^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){2,3}$` |
| `human_actor_id` | string or null | Yes |  |
| `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)$` |
| `occurred_at_utc` | string or string | Yes |  |
| `reason_code` | string or null | Yes |  |
| `reason_text` | string or null | Yes |  |
| `recorded_at_utc` | string or string | Yes |  |
| `request_id` | string or null | Yes |  |
| `resource_ref` | string or null | Yes |  |
| `resource_type` | string or null | Yes |  |
| `result_status` | "succeeded" / "failed" / "denied" / "rejected" / "cancelled" | Yes |  |
| `scope` | object | Yes | No additional fields |
| `service_account_id` | string or null | Yes |  |
| `source_service` | string | Yes | minLength: 1 |
| `trace_id` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.action_family

At least one alternative must match.

###### application/json body.items item.action_family: alternative 1

Type: `"human_actor_lifecycle" / "role_assignment" / "policy_change" / "service_account_governance" / "webhook_subscription_governance" / "financial_operation_audit" / "tenant_governance" / "approval_decision" / "authentication" / "other"`. 

###### application/json body.items item.action_family: alternative 2

Type: `null`. 

###### application/json body.items item.approval_state

At least one alternative must match.

###### application/json body.items item.approval_state: alternative 1

Type: `"not_required" / "pending" / "approved" / "rejected" / "cancelled" / "expired"`. 

###### application/json body.items item.approval_state: alternative 2

Type: `null`. 

###### application/json body.items item.attribution

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `actor` | object or null | Yes |  |
| `approved_by` | object or null | Yes |  |
| `authenticated_principal` | object | Yes | No additional fields |
| `identity_source` | "platform-managed" / "federated" / "system" | Yes |  |
| `initiated_by` | object or null | Yes |  |
| `subject` | object or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.attribution.actor

At least one alternative must match.

###### application/json body.items item.attribution.actor: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "user" / "service" / "system" | Yes |  |
| `ref` | string | Yes | pattern: `^(users\|service-accounts\|platform-principals\|identity-providers)\/([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})$` |

Additional fields are not accepted.

###### application/json body.items item.attribution.actor: alternative 2

Type: `null`. 

###### application/json body.items item.attribution.approved_by

At least one alternative must match.

###### application/json body.items item.attribution.approved_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "user" / "service" / "system" | Yes |  |
| `ref` | string | Yes | pattern: `^(users\|service-accounts\|platform-principals\|identity-providers)\/([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})$` |

Additional fields are not accepted.

###### application/json body.items item.attribution.approved_by: alternative 2

Type: `null`. 

###### application/json body.items item.attribution.authenticated_principal

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "user" / "service" / "system" | Yes |  |
| `ref` | string | Yes | pattern: `^(users\|service-accounts\|platform-principals\|identity-providers)\/([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})$` |

Additional fields are not accepted.

###### application/json body.items item.attribution.initiated_by

At least one alternative must match.

###### application/json body.items item.attribution.initiated_by: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "user" / "service" / "system" | Yes |  |
| `ref` | string | Yes | pattern: `^(users\|service-accounts\|platform-principals\|identity-providers)\/([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})$` |

Additional fields are not accepted.

###### application/json body.items item.attribution.initiated_by: alternative 2

Type: `null`. 

###### application/json body.items item.attribution.subject

At least one alternative must match.

###### application/json body.items item.attribution.subject: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "user" / "service" / "system" | Yes |  |
| `ref` | string | Yes | pattern: `^(users\|service-accounts\|platform-principals\|identity-providers)\/([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})$` |

Additional fields are not accepted.

###### application/json body.items item.attribution.subject: alternative 2

Type: `null`. 

###### application/json body.items item.changed_fields

At least one alternative must match.

###### application/json body.items item.changed_fields: alternative 1

Type: `object[]`. 

###### application/json body.items item.changed_fields: alternative 1 item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1 |
| `after` | unspecified | Yes |  |
| `before` | unspecified | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.changed_fields: alternative 2

Type: `null`. 

###### application/json body.items item.correlation_id

At least one alternative must match.

###### application/json body.items item.correlation_id: alternative 1

Type: `string`. 

###### application/json body.items item.correlation_id: alternative 2

Type: `null`. 

###### application/json body.items item.detail

At least one alternative must match.

###### application/json body.items item.detail: alternative 1

Type: `object`. 

###### application/json body.items item.detail: alternative 2

Type: `null`. 

###### application/json body.items item.event_id

At least one alternative must match.

###### application/json body.items item.event_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item.event_id: alternative 2

Type: `null`. 

###### application/json body.items item.human_actor_id

At least one alternative must match.

###### application/json body.items item.human_actor_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item.human_actor_id: alternative 2

Type: `null`. 

###### application/json body.items item.occurred_at_utc

At least one alternative must match.

###### application/json body.items item.occurred_at_utc: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.occurred_at_utc: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.reason_code

At least one alternative must match.

###### application/json body.items item.reason_code: alternative 1

Type: `string`. 

###### application/json body.items item.reason_code: alternative 2

Type: `null`. 

###### application/json body.items item.reason_text

At least one alternative must match.

###### application/json body.items item.reason_text: alternative 1

Type: `string`. 

###### application/json body.items item.reason_text: alternative 2

Type: `null`. 

###### application/json body.items item.recorded_at_utc

At least one alternative must match.

###### application/json body.items item.recorded_at_utc: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.recorded_at_utc: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.request_id

At least one alternative must match.

###### application/json body.items item.request_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item.request_id: alternative 2

Type: `null`. 

###### application/json body.items item.resource_ref

At least one alternative must match.

###### application/json body.items item.resource_ref: alternative 1

Type: `string`. pattern: `^(enterprises|platform-operators|clients|master-accounts|client-accounts|users|service-accounts|platform-principals|identity-providers|roles|role-assignments|system-principals|commercial-agreements|policy-rules|operations|compliance-assessments|webhook-subscriptions)\/([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})$`

###### application/json body.items item.resource_ref: alternative 2

Type: `null`. 

###### application/json body.items item.resource_type

At least one alternative must match.

###### application/json body.items item.resource_type: alternative 1

Type: `string`. minLength: 1

###### application/json body.items item.resource_type: alternative 2

Type: `null`. 

###### application/json body.items item.scope

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `client_account_ref` | string or null | Yes |  |
| `client_ref` | string or null | Yes |  |
| `enterprise_ref` | string or null | Yes |  |
| `master_account_ref` | string or null | Yes |  |
| `platform_operator_ref` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.scope.client_account_ref

At least one alternative must match.

###### application/json body.items item.scope.client_account_ref: alternative 1

Type: `string`. pattern: `^(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})$`

###### application/json body.items item.scope.client_account_ref: alternative 2

Type: `null`. 

###### application/json body.items item.scope.client_ref

At least one alternative must match.

###### application/json body.items item.scope.client_ref: alternative 1

Type: `string`. pattern: `^(clients)\/([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})$`

###### application/json body.items item.scope.client_ref: alternative 2

Type: `null`. 

###### application/json body.items item.scope.enterprise_ref

At least one alternative must match.

###### application/json body.items item.scope.enterprise_ref: alternative 1

Type: `string`. pattern: `^(enterprises)\/([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})$`

###### application/json body.items item.scope.enterprise_ref: alternative 2

Type: `null`. 

###### application/json body.items item.scope.master_account_ref

At least one alternative must match.

###### application/json body.items item.scope.master_account_ref: alternative 1

Type: `string`. pattern: `^(master-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})$`

###### application/json body.items item.scope.master_account_ref: alternative 2

Type: `null`. 

###### application/json body.items item.scope.platform_operator_ref

At least one alternative must match.

###### application/json body.items item.scope.platform_operator_ref: alternative 1

Type: `string`. pattern: `^(platform-operators)\/([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})$`

###### application/json body.items item.scope.platform_operator_ref: alternative 2

Type: `null`. 

###### application/json body.items item.service_account_id

At least one alternative must match.

###### application/json body.items item.service_account_id: alternative 1

Type: `string`. 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)$`

###### application/json body.items item.service_account_id: alternative 2

Type: `null`. 

###### application/json body.items item.trace_id

At least one alternative must match.

###### application/json body.items item.trace_id: alternative 1

Type: `string`. 

###### application/json body.items item.trace_id: alternative 2

Type: `null`.


### user-action-audit-entries-search 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.


### user-action-audit-entries-search Response 401 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.


### user-action-audit-entries-search Response 403 schema

Content type: `application/json`.

See [response 401 schema](#user-action-audit-entries-search-response-401-schema).


### user-action-audit-entries-search Response 500 schema

Content type: `application/json`.

See [response 401 schema](#user-action-audit-entries-search-response-401-schema).


### user-action-audit-entries-search Response 502 schema

Content type: `application/json`.

See [response 400 schema](#user-action-audit-entries-search-response-400-schema).


### user-action-audit-entries-search Response 503 schema

Content type: `application/json`.

See [response 400 schema](#user-action-audit-entries-search-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "action_family": "tenant_governance",
        "approval_state": "not_required",
        "attribution": {
          "actor": null,
          "approved_by": null,
          "authenticated_principal": {
            "kind": "user",
            "ref": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
          },
          "identity_source": "platform-managed",
          "initiated_by": null,
          "subject": {
            "kind": "user",
            "ref": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
          }
        },
        "changed_fields": null,
        "correlation_id": null,
        "detail": null,
        "event_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "event_type": "tenant.enterprise.admitted.v1",
        "human_actor_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "occurred_at_utc": "2026-05-01T10:00:00Z",
        "reason_code": null,
        "reason_text": null,
        "recorded_at_utc": "2026-05-01T10:00:00Z",
        "request_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "resource_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "resource_type": "enterprise",
        "result_status": "succeeded",
        "scope": {
          "client_account_ref": null,
          "client_ref": null,
          "enterprise_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
          "master_account_ref": null,
          "platform_operator_ref": null
        },
        "service_account_id": null,
        "source_service": "edge-service",
        "trace_id": null
      }
    ],
    "limit": 100,
    "offset": 0,
    "total": 1
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## User Action Audit Exports

### GET /user-action-audit-exports

**List audit exports**

Lists exports created by the current actor that remain covered by audit.read, with an optional status filter. limit defaults to 50 and is bounded 1..200. The response is an items array without cursor pagination.

**Required capability:** `audit.read`

**Authentication:** Bearer token required.

**Parameters:**

- `status` `string` (query)
- `limit` `integer` (query)

### user-action-audit-exports-list Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `format` | "csv" / "json" | Yes |  |
| `byte_size` | integer or null | Yes |  |
| `download_path` | string or null | Yes |  |
| `expires_at_utc` | string or string or null | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `filter_criteria` | object | Yes | No additional fields |
| `finished_at_utc` | string or string or null | Yes |  |
| `generated_at_utc` | string or string | Yes |  |
| `generated_by` | string | Yes | pattern: `^(users\|service-accounts\|platform-principals\|identity-providers)\/([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})$` |
| `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)$` |
| `requested_scope` | object or object or object or object or object | Yes |  |
| `row_count` | integer or null | Yes |  |
| `status` | "queued" / "running" / "ready" / "failed" / "expired" | Yes |  |
| `storage_location` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.byte_size

At least one alternative must match.

###### application/json body.items item.byte_size: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### application/json body.items item.byte_size: alternative 2

Type: `null`. 

###### application/json body.items item.download_path

At least one alternative must match.

###### application/json body.items item.download_path: alternative 1

Type: `string`. 

###### application/json body.items item.download_path: alternative 2

Type: `null`. 

###### application/json body.items item.expires_at_utc

At least one alternative must match.

###### application/json body.items item.expires_at_utc: alternative 1

At least one alternative must match.

###### application/json body.items item.expires_at_utc: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.expires_at_utc: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.expires_at_utc: alternative 2

Type: `null`. 

###### application/json body.items item.failure_reason

At least one alternative must match.

###### application/json body.items item.failure_reason: alternative 1

Type: `string`. 

###### application/json body.items item.failure_reason: alternative 2

Type: `null`. 

###### application/json body.items item.filter_criteria

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `action_families` | "human_actor_lifecycle" / "role_assignment" / "policy_change" / "service_account_governance" / "webhook_subscription_governance" / "financial_operation_audit" / "tenant_governance" / "approval_decision" / "authentication" / "other"[] | No |  |
| `actor` | string | No | pattern: `^(users\|service-accounts\|platform-principals\|identity-providers)\/([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})$` |
| `authenticated_principal` | string | No | pattern: `^(users\|service-accounts\|platform-principals\|identity-providers)\/([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})$` |
| `event_types` | string[] | No |  |
| `occurred_from_utc` | string or string | Yes |  |
| `occurred_to_utc` | string or string | Yes |  |
| `reason_codes` | string[] | No |  |
| `resource_ref` | string | No | pattern: `^(enterprises\|platform-operators\|clients\|master-accounts\|client-accounts\|users\|service-accounts\|platform-principals\|identity-providers\|roles\|role-assignments\|system-principals\|commercial-agreements\|policy-rules\|operations\|compliance-assessments\|webhook-subscriptions)\/([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})$` |
| `result_statuses` | "succeeded" / "failed" / "denied" / "rejected" / "cancelled"[] | No |  |
| `subject` | string | No | pattern: `^(users\|service-accounts\|platform-principals\|identity-providers)\/([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})$` |

Additional fields are not accepted.

###### application/json body.items item.filter_criteria.action_families

Type: `"human_actor_lifecycle" / "role_assignment" / "policy_change" / "service_account_governance" / "webhook_subscription_governance" / "financial_operation_audit" / "tenant_governance" / "approval_decision" / "authentication" / "other"[]`. 

###### application/json body.items item.filter_criteria.action_families item

Type: `"human_actor_lifecycle" / "role_assignment" / "policy_change" / "service_account_governance" / "webhook_subscription_governance" / "financial_operation_audit" / "tenant_governance" / "approval_decision" / "authentication" / "other"`. 

###### application/json body.items item.filter_criteria.event_types

Type: `string[]`. 

###### application/json body.items item.filter_criteria.event_types item

Type: `string`. pattern: `^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){2,3}$`

###### application/json body.items item.filter_criteria.occurred_from_utc

At least one alternative must match.

###### application/json body.items item.filter_criteria.occurred_from_utc: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.filter_criteria.occurred_from_utc: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.filter_criteria.occurred_to_utc

At least one alternative must match.

###### application/json body.items item.filter_criteria.occurred_to_utc: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.filter_criteria.occurred_to_utc: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.filter_criteria.reason_codes

Type: `string[]`. 

###### application/json body.items item.filter_criteria.reason_codes item

Type: `string`. minLength: 1

###### application/json body.items item.filter_criteria.result_statuses

Type: `"succeeded" / "failed" / "denied" / "rejected" / "cancelled"[]`. 

###### application/json body.items item.filter_criteria.result_statuses item

Type: `"succeeded" / "failed" / "denied" / "rejected" / "cancelled"`. 

###### application/json body.items item.finished_at_utc

At least one alternative must match.

###### application/json body.items item.finished_at_utc: alternative 1

At least one alternative must match.

###### application/json body.items item.finished_at_utc: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.finished_at_utc: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.finished_at_utc: alternative 2

Type: `null`. 

###### application/json body.items item.generated_at_utc

At least one alternative must match.

###### application/json body.items item.generated_at_utc: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.generated_at_utc: alternative 2

Type: `string`. format: date-time

###### application/json body.items item.requested_scope

Exactly one alternative must match.

###### application/json body.items item.requested_scope: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "enterprise" | Yes |  |
| `ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |

Additional fields are not accepted.

###### application/json body.items item.requested_scope: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "master_account" | Yes |  |
| `ref` | string | Yes | pattern: `^(master-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})$` |

Additional fields are not accepted.

###### application/json body.items item.requested_scope: alternative 3

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "client" | Yes |  |
| `ref` | string | Yes | pattern: `^(clients)\/([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})$` |

Additional fields are not accepted.

###### application/json body.items item.requested_scope: alternative 4

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "client_account" | Yes |  |
| `ref` | string | Yes | pattern: `^(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})$` |

Additional fields are not accepted.

###### application/json body.items item.requested_scope: alternative 5

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "platform_operator" | Yes |  |
| `ref` | string | Yes | pattern: `^(platform-operators)\/([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})$` |

Additional fields are not accepted.

###### application/json body.items item.row_count

At least one alternative must match.

###### application/json body.items item.row_count: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### application/json body.items item.row_count: alternative 2

Type: `null`. 

###### application/json body.items item.storage_location

At least one alternative must match.

###### application/json body.items item.storage_location: alternative 1

Type: `string`. 

###### application/json body.items item.storage_location: alternative 2

Type: `null`.


### user-action-audit-exports-list 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.


### user-action-audit-exports-list Response 401 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.


### user-action-audit-exports-list Response 403 schema

Content type: `application/json`.

See [response 401 schema](#user-action-audit-exports-list-response-401-schema).


### user-action-audit-exports-list Response 500 schema

Content type: `application/json`.

See [response 401 schema](#user-action-audit-exports-list-response-401-schema).


### user-action-audit-exports-list Response 502 schema

Content type: `application/json`.

See [response 400 schema](#user-action-audit-exports-list-response-400-schema).


### user-action-audit-exports-list Response 503 schema

Content type: `application/json`.

See [response 400 schema](#user-action-audit-exports-list-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "format": "csv",
        "byte_size": 8192,
        "download_path": "/user-action-audit-exports/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b/download",
        "expires_at_utc": "2026-05-02T10:00:00Z",
        "failure_reason": null,
        "filter_criteria": {
          "occurred_from_utc": "2026-04-01T00:00:00Z",
          "occurred_to_utc": "2026-04-30T23:59:59Z"
        },
        "finished_at_utc": "2026-05-01T10:00:00Z",
        "generated_at_utc": "2026-05-01T10:00:00Z",
        "generated_by": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "requested_scope": {
          "kind": "enterprise",
          "ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
        },
        "row_count": 42,
        "status": "ready",
        "storage_location": null
      }
    ]
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /user-action-audit-exports

**Create audit export**

Creates a scope-bound audit export with format csv or json. The json format streams newline-delimited JSON. Inspect status and download_path for readiness; storage_location is always null and clients download through the relative gateway path. Export list, get and download are limited to the creating actor and current audit.read coverage of the stored requested_scope.

**Required capability:** `audit.create_export`

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `format` | "csv" / "json" | Yes |  |
| `filter_criteria` | object | Yes | No additional fields |
| `requested_scope` | object or object or object or object or object | Yes |  |

Additional fields are not accepted.

#### Request body schema.filter_criteria

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `action_families` | "human_actor_lifecycle" / "role_assignment" / "policy_change" / "service_account_governance" / "webhook_subscription_governance" / "financial_operation_audit" / "tenant_governance" / "approval_decision" / "authentication" / "other"[] | No |  |
| `actor` | string | No | pattern: `^(users\|service-accounts\|platform-principals\|identity-providers)\/([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})$` |
| `authenticated_principal` | string | No | pattern: `^(users\|service-accounts\|platform-principals\|identity-providers)\/([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})$` |
| `event_types` | string[] | No |  |
| `occurred_from_utc` | string or string | Yes |  |
| `occurred_to_utc` | string or string | Yes |  |
| `reason_codes` | string[] | No |  |
| `resource_ref` | string | No | pattern: `^(enterprises\|platform-operators\|clients\|master-accounts\|client-accounts\|users\|service-accounts\|platform-principals\|identity-providers\|roles\|role-assignments\|system-principals\|commercial-agreements\|policy-rules\|operations\|compliance-assessments\|webhook-subscriptions)\/([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})$` |
| `result_statuses` | "succeeded" / "failed" / "denied" / "rejected" / "cancelled"[] | No |  |
| `subject` | string | No | pattern: `^(users\|service-accounts\|platform-principals\|identity-providers)\/([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})$` |

Additional fields are not accepted.

##### Request body schema.filter_criteria.action_families

Type: `"human_actor_lifecycle" / "role_assignment" / "policy_change" / "service_account_governance" / "webhook_subscription_governance" / "financial_operation_audit" / "tenant_governance" / "approval_decision" / "authentication" / "other"[]`. 

###### Request body schema.filter_criteria.action_families item

Type: `"human_actor_lifecycle" / "role_assignment" / "policy_change" / "service_account_governance" / "webhook_subscription_governance" / "financial_operation_audit" / "tenant_governance" / "approval_decision" / "authentication" / "other"`. 

##### Request body schema.filter_criteria.event_types

Type: `string[]`. 

###### Request body schema.filter_criteria.event_types item

Type: `string`. pattern: `^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){2,3}$`

##### Request body schema.filter_criteria.occurred_from_utc

At least one alternative must match.

###### Request body schema.filter_criteria.occurred_from_utc: alternative 1

Type: `string`. 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))$`

###### Request body schema.filter_criteria.occurred_from_utc: alternative 2

Type: `string`. format: date-time

##### Request body schema.filter_criteria.occurred_to_utc

At least one alternative must match.

###### Request body schema.filter_criteria.occurred_to_utc: alternative 1

Type: `string`. 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))$`

###### Request body schema.filter_criteria.occurred_to_utc: alternative 2

Type: `string`. format: date-time

##### Request body schema.filter_criteria.reason_codes

Type: `string[]`. 

###### Request body schema.filter_criteria.reason_codes item

Type: `string`. minLength: 1

##### Request body schema.filter_criteria.result_statuses

Type: `"succeeded" / "failed" / "denied" / "rejected" / "cancelled"[]`. 

###### Request body schema.filter_criteria.result_statuses item

Type: `"succeeded" / "failed" / "denied" / "rejected" / "cancelled"`. 

#### Request body schema.requested_scope

Exactly one alternative must match.

##### Request body schema.requested_scope: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "enterprise" | Yes |  |
| `ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |

Additional fields are not accepted.

##### Request body schema.requested_scope: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "master_account" | Yes |  |
| `ref` | string | Yes | pattern: `^(master-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})$` |

Additional fields are not accepted.

##### Request body schema.requested_scope: alternative 3

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "client" | Yes |  |
| `ref` | string | Yes | pattern: `^(clients)\/([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})$` |

Additional fields are not accepted.

##### Request body schema.requested_scope: alternative 4

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "client_account" | Yes |  |
| `ref` | string | Yes | pattern: `^(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})$` |

Additional fields are not accepted.

##### Request body schema.requested_scope: alternative 5

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "platform_operator" | Yes |  |
| `ref` | string | Yes | pattern: `^(platform-operators)\/([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})$` |

Additional fields are not accepted.

**Request example:**

```json
{
  "format": "csv",
  "filter_criteria": {
    "occurred_from_utc": "2026-04-01T00:00:00Z",
    "occurred_to_utc": "2026-04-30T23:59:59Z"
  },
  "requested_scope": {
    "kind": "enterprise",
    "ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
  }
}
```

### user-action-audit-exports-create Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `format` | "csv" / "json" | Yes |  |
| `byte_size` | integer or null | Yes |  |
| `download_path` | string or null | Yes |  |
| `expires_at_utc` | string or string or null | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `filter_criteria` | object | Yes | No additional fields |
| `finished_at_utc` | string or string or null | Yes |  |
| `generated_at_utc` | string or string | Yes |  |
| `generated_by` | string | Yes | pattern: `^(users\|service-accounts\|platform-principals\|identity-providers)\/([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})$` |
| `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)$` |
| `requested_scope` | object or object or object or object or object | Yes |  |
| `row_count` | integer or null | Yes |  |
| `status` | "queued" / "running" / "ready" / "failed" / "expired" | Yes |  |
| `storage_location` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.byte_size

At least one alternative must match.

###### application/json body.byte_size: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### application/json body.byte_size: alternative 2

Type: `null`. 

##### application/json body.download_path

At least one alternative must match.

###### application/json body.download_path: alternative 1

Type: `string`. 

###### application/json body.download_path: alternative 2

Type: `null`. 

##### application/json body.expires_at_utc

At least one alternative must match.

###### application/json body.expires_at_utc: alternative 1

At least one alternative must match.

###### application/json body.expires_at_utc: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.expires_at_utc: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.expires_at_utc: alternative 2

Type: `null`. 

##### application/json body.failure_reason

At least one alternative must match.

###### application/json body.failure_reason: alternative 1

Type: `string`. 

###### application/json body.failure_reason: alternative 2

Type: `null`. 

##### application/json body.filter_criteria

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `action_families` | "human_actor_lifecycle" / "role_assignment" / "policy_change" / "service_account_governance" / "webhook_subscription_governance" / "financial_operation_audit" / "tenant_governance" / "approval_decision" / "authentication" / "other"[] | No |  |
| `actor` | string | No | pattern: `^(users\|service-accounts\|platform-principals\|identity-providers)\/([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})$` |
| `authenticated_principal` | string | No | pattern: `^(users\|service-accounts\|platform-principals\|identity-providers)\/([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})$` |
| `event_types` | string[] | No |  |
| `occurred_from_utc` | string or string | Yes |  |
| `occurred_to_utc` | string or string | Yes |  |
| `reason_codes` | string[] | No |  |
| `resource_ref` | string | No | pattern: `^(enterprises\|platform-operators\|clients\|master-accounts\|client-accounts\|users\|service-accounts\|platform-principals\|identity-providers\|roles\|role-assignments\|system-principals\|commercial-agreements\|policy-rules\|operations\|compliance-assessments\|webhook-subscriptions)\/([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})$` |
| `result_statuses` | "succeeded" / "failed" / "denied" / "rejected" / "cancelled"[] | No |  |
| `subject` | string | No | pattern: `^(users\|service-accounts\|platform-principals\|identity-providers)\/([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})$` |

Additional fields are not accepted.

###### application/json body.filter_criteria.action_families

Type: `"human_actor_lifecycle" / "role_assignment" / "policy_change" / "service_account_governance" / "webhook_subscription_governance" / "financial_operation_audit" / "tenant_governance" / "approval_decision" / "authentication" / "other"[]`. 

###### application/json body.filter_criteria.action_families item

Type: `"human_actor_lifecycle" / "role_assignment" / "policy_change" / "service_account_governance" / "webhook_subscription_governance" / "financial_operation_audit" / "tenant_governance" / "approval_decision" / "authentication" / "other"`. 

###### application/json body.filter_criteria.event_types

Type: `string[]`. 

###### application/json body.filter_criteria.event_types item

Type: `string`. pattern: `^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){2,3}$`

###### application/json body.filter_criteria.occurred_from_utc

At least one alternative must match.

###### application/json body.filter_criteria.occurred_from_utc: alternative 1

Type: `string`. 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))$`

###### application/json body.filter_criteria.occurred_from_utc: alternative 2

Type: `string`. format: date-time

###### application/json body.filter_criteria.occurred_to_utc

At least one alternative must match.

###### application/json body.filter_criteria.occurred_to_utc: alternative 1

Type: `string`. 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))$`

###### application/json body.filter_criteria.occurred_to_utc: alternative 2

Type: `string`. format: date-time

###### application/json body.filter_criteria.reason_codes

Type: `string[]`. 

###### application/json body.filter_criteria.reason_codes item

Type: `string`. minLength: 1

###### application/json body.filter_criteria.result_statuses

Type: `"succeeded" / "failed" / "denied" / "rejected" / "cancelled"[]`. 

###### application/json body.filter_criteria.result_statuses item

Type: `"succeeded" / "failed" / "denied" / "rejected" / "cancelled"`. 

##### application/json body.finished_at_utc

At least one alternative must match.

###### application/json body.finished_at_utc: alternative 1

At least one alternative must match.

###### application/json body.finished_at_utc: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.finished_at_utc: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.finished_at_utc: alternative 2

Type: `null`. 

##### application/json body.generated_at_utc

At least one alternative must match.

###### application/json body.generated_at_utc: alternative 1

Type: `string`. 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))$`

###### application/json body.generated_at_utc: alternative 2

Type: `string`. format: date-time

##### application/json body.requested_scope

Exactly one alternative must match.

###### application/json body.requested_scope: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "enterprise" | Yes |  |
| `ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |

Additional fields are not accepted.

###### application/json body.requested_scope: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "master_account" | Yes |  |
| `ref` | string | Yes | pattern: `^(master-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})$` |

Additional fields are not accepted.

###### application/json body.requested_scope: alternative 3

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "client" | Yes |  |
| `ref` | string | Yes | pattern: `^(clients)\/([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})$` |

Additional fields are not accepted.

###### application/json body.requested_scope: alternative 4

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "client_account" | Yes |  |
| `ref` | string | Yes | pattern: `^(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})$` |

Additional fields are not accepted.

###### application/json body.requested_scope: alternative 5

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "platform_operator" | Yes |  |
| `ref` | string | Yes | pattern: `^(platform-operators)\/([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})$` |

Additional fields are not accepted.

##### application/json body.row_count

At least one alternative must match.

###### application/json body.row_count: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### application/json body.row_count: alternative 2

Type: `null`. 

##### application/json body.storage_location

At least one alternative must match.

###### application/json body.storage_location: alternative 1

Type: `string`. 

###### application/json body.storage_location: alternative 2

Type: `null`.


### user-action-audit-exports-create 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.


### user-action-audit-exports-create Response 401 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.


### user-action-audit-exports-create Response 403 schema

Content type: `application/json`.

See [response 401 schema](#user-action-audit-exports-create-response-401-schema).


### user-action-audit-exports-create Response 409 schema

Content type: `application/json`.

See [response 401 schema](#user-action-audit-exports-create-response-401-schema).


### user-action-audit-exports-create Response 500 schema

Content type: `application/json`.

See [response 401 schema](#user-action-audit-exports-create-response-401-schema).


### user-action-audit-exports-create Response 502 schema

Content type: `application/json`.

See [response 400 schema](#user-action-audit-exports-create-response-400-schema).


### user-action-audit-exports-create Response 503 schema

Content type: `application/json`.

See [response 400 schema](#user-action-audit-exports-create-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "format": "csv",
    "byte_size": 8192,
    "download_path": "/user-action-audit-exports/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b/download",
    "expires_at_utc": "2026-05-02T10:00:00Z",
    "failure_reason": null,
    "filter_criteria": {
      "occurred_from_utc": "2026-04-01T00:00:00Z",
      "occurred_to_utc": "2026-04-30T23:59:59Z"
    },
    "finished_at_utc": "2026-05-01T10:00:00Z",
    "generated_at_utc": "2026-05-01T10:00:00Z",
    "generated_by": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "requested_scope": {
      "kind": "enterprise",
      "ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
    },
    "row_count": 42,
    "status": "ready",
    "storage_location": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /user-action-audit-exports/{export_id}

**Get audit export**

Reads an export belonging to the current actor and covered by audit.read. A hidden or missing export returns 404. download_path is null until ready and after expiry.

**Required capability:** `audit.read`

**Authentication:** Bearer token required.

**Parameters:**

- `export_id` `string` (path) *(required)*

### user-action-audit-exports-get Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `format` | "csv" / "json" | Yes |  |
| `byte_size` | integer or null | Yes |  |
| `download_path` | string or null | Yes |  |
| `expires_at_utc` | string or string or null | Yes |  |
| `failure_reason` | string or null | Yes |  |
| `filter_criteria` | object | Yes | No additional fields |
| `finished_at_utc` | string or string or null | Yes |  |
| `generated_at_utc` | string or string | Yes |  |
| `generated_by` | string | Yes | pattern: `^(users\|service-accounts\|platform-principals\|identity-providers)\/([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})$` |
| `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)$` |
| `requested_scope` | object or object or object or object or object | Yes |  |
| `row_count` | integer or null | Yes |  |
| `status` | "queued" / "running" / "ready" / "failed" / "expired" | Yes |  |
| `storage_location` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.byte_size

At least one alternative must match.

###### application/json body.byte_size: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### application/json body.byte_size: alternative 2

Type: `null`. 

##### application/json body.download_path

At least one alternative must match.

###### application/json body.download_path: alternative 1

Type: `string`. 

###### application/json body.download_path: alternative 2

Type: `null`. 

##### application/json body.expires_at_utc

At least one alternative must match.

###### application/json body.expires_at_utc: alternative 1

At least one alternative must match.

###### application/json body.expires_at_utc: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.expires_at_utc: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.expires_at_utc: alternative 2

Type: `null`. 

##### application/json body.failure_reason

At least one alternative must match.

###### application/json body.failure_reason: alternative 1

Type: `string`. 

###### application/json body.failure_reason: alternative 2

Type: `null`. 

##### application/json body.filter_criteria

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `action_families` | "human_actor_lifecycle" / "role_assignment" / "policy_change" / "service_account_governance" / "webhook_subscription_governance" / "financial_operation_audit" / "tenant_governance" / "approval_decision" / "authentication" / "other"[] | No |  |
| `actor` | string | No | pattern: `^(users\|service-accounts\|platform-principals\|identity-providers)\/([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})$` |
| `authenticated_principal` | string | No | pattern: `^(users\|service-accounts\|platform-principals\|identity-providers)\/([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})$` |
| `event_types` | string[] | No |  |
| `occurred_from_utc` | string or string | Yes |  |
| `occurred_to_utc` | string or string | Yes |  |
| `reason_codes` | string[] | No |  |
| `resource_ref` | string | No | pattern: `^(enterprises\|platform-operators\|clients\|master-accounts\|client-accounts\|users\|service-accounts\|platform-principals\|identity-providers\|roles\|role-assignments\|system-principals\|commercial-agreements\|policy-rules\|operations\|compliance-assessments\|webhook-subscriptions)\/([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})$` |
| `result_statuses` | "succeeded" / "failed" / "denied" / "rejected" / "cancelled"[] | No |  |
| `subject` | string | No | pattern: `^(users\|service-accounts\|platform-principals\|identity-providers)\/([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})$` |

Additional fields are not accepted.

###### application/json body.filter_criteria.action_families

Type: `"human_actor_lifecycle" / "role_assignment" / "policy_change" / "service_account_governance" / "webhook_subscription_governance" / "financial_operation_audit" / "tenant_governance" / "approval_decision" / "authentication" / "other"[]`. 

###### application/json body.filter_criteria.action_families item

Type: `"human_actor_lifecycle" / "role_assignment" / "policy_change" / "service_account_governance" / "webhook_subscription_governance" / "financial_operation_audit" / "tenant_governance" / "approval_decision" / "authentication" / "other"`. 

###### application/json body.filter_criteria.event_types

Type: `string[]`. 

###### application/json body.filter_criteria.event_types item

Type: `string`. pattern: `^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){2,3}$`

###### application/json body.filter_criteria.occurred_from_utc

At least one alternative must match.

###### application/json body.filter_criteria.occurred_from_utc: alternative 1

Type: `string`. 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))$`

###### application/json body.filter_criteria.occurred_from_utc: alternative 2

Type: `string`. format: date-time

###### application/json body.filter_criteria.occurred_to_utc

At least one alternative must match.

###### application/json body.filter_criteria.occurred_to_utc: alternative 1

Type: `string`. 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))$`

###### application/json body.filter_criteria.occurred_to_utc: alternative 2

Type: `string`. format: date-time

###### application/json body.filter_criteria.reason_codes

Type: `string[]`. 

###### application/json body.filter_criteria.reason_codes item

Type: `string`. minLength: 1

###### application/json body.filter_criteria.result_statuses

Type: `"succeeded" / "failed" / "denied" / "rejected" / "cancelled"[]`. 

###### application/json body.filter_criteria.result_statuses item

Type: `"succeeded" / "failed" / "denied" / "rejected" / "cancelled"`. 

##### application/json body.finished_at_utc

At least one alternative must match.

###### application/json body.finished_at_utc: alternative 1

At least one alternative must match.

###### application/json body.finished_at_utc: alternative 1: alternative 1

Type: `string`. 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))$`

###### application/json body.finished_at_utc: alternative 1: alternative 2

Type: `string`. format: date-time

###### application/json body.finished_at_utc: alternative 2

Type: `null`. 

##### application/json body.generated_at_utc

At least one alternative must match.

###### application/json body.generated_at_utc: alternative 1

Type: `string`. 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))$`

###### application/json body.generated_at_utc: alternative 2

Type: `string`. format: date-time

##### application/json body.requested_scope

Exactly one alternative must match.

###### application/json body.requested_scope: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "enterprise" | Yes |  |
| `ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |

Additional fields are not accepted.

###### application/json body.requested_scope: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "master_account" | Yes |  |
| `ref` | string | Yes | pattern: `^(master-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})$` |

Additional fields are not accepted.

###### application/json body.requested_scope: alternative 3

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "client" | Yes |  |
| `ref` | string | Yes | pattern: `^(clients)\/([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})$` |

Additional fields are not accepted.

###### application/json body.requested_scope: alternative 4

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "client_account" | Yes |  |
| `ref` | string | Yes | pattern: `^(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})$` |

Additional fields are not accepted.

###### application/json body.requested_scope: alternative 5

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `kind` | "platform_operator" | Yes |  |
| `ref` | string | Yes | pattern: `^(platform-operators)\/([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})$` |

Additional fields are not accepted.

##### application/json body.row_count

At least one alternative must match.

###### application/json body.row_count: alternative 1

Type: `integer`. minimum: 0; maximum: 9007199254740991

###### application/json body.row_count: alternative 2

Type: `null`. 

##### application/json body.storage_location

At least one alternative must match.

###### application/json body.storage_location: alternative 1

Type: `string`. 

###### application/json body.storage_location: alternative 2

Type: `null`.


### user-action-audit-exports-get 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.


### user-action-audit-exports-get Response 401 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.


### user-action-audit-exports-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#user-action-audit-exports-get-response-401-schema).


### user-action-audit-exports-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#user-action-audit-exports-get-response-401-schema).


### user-action-audit-exports-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#user-action-audit-exports-get-response-401-schema).


### user-action-audit-exports-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#user-action-audit-exports-get-response-400-schema).


### user-action-audit-exports-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#user-action-audit-exports-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "format": "csv",
    "byte_size": 8192,
    "download_path": "/user-action-audit-exports/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b/download",
    "expires_at_utc": "2026-05-02T10:00:00Z",
    "failure_reason": null,
    "filter_criteria": {
      "occurred_from_utc": "2026-04-01T00:00:00Z",
      "occurred_to_utc": "2026-04-30T23:59:59Z"
    },
    "finished_at_utc": "2026-05-01T10:00:00Z",
    "generated_at_utc": "2026-05-01T10:00:00Z",
    "generated_by": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "requested_scope": {
      "kind": "enterprise",
      "ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
    },
    "row_count": 42,
    "status": "ready",
    "storage_location": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /user-action-audit-exports/{export_id}/download

**Download audit export file**

Streams the ready export through edge. csv yields text/csv and json yields application/x-ndjson: one JSON object per line, with UTF-8 encoding. Content-Type, Content-Disposition and optional Content-Length are forwarded from the download service. Unavailable, expired or hidden exports return 404; an unsuccessful upstream response other than 404 returns 502.

**Required capability:** `audit.read`

**Authentication:** Bearer token required.

**Parameters:**

- `export_id` `string` (path) *(required)*

### user-action-audit-exports-download Response 200 schema

Content type: `application/x-ndjson`.

#### application/x-ndjson body

UTF-8 newline-delimited JSON, one ActionAuditEntry object per line.

Type: `string`.

Content type: `text/csv`.

#### text/csv body

UTF-8 CSV file with a header row.

Type: `string`.


| Response header | Type | Description |
| --- | --- | --- |
| `Content-Disposition` | string |  |
| `Content-Length` | string |  |

### user-action-audit-exports-download 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.


### user-action-audit-exports-download Response 401 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.


### user-action-audit-exports-download Response 403 schema

Content type: `application/json`.

See [response 401 schema](#user-action-audit-exports-download-response-401-schema).


### user-action-audit-exports-download Response 404 schema

Content type: `application/json`.

See [response 401 schema](#user-action-audit-exports-download-response-401-schema).


### user-action-audit-exports-download Response 500 schema

Content type: `application/json`.

See [response 401 schema](#user-action-audit-exports-download-response-401-schema).


### user-action-audit-exports-download Response 502 schema

Content type: `application/json`.

See [response 400 schema](#user-action-audit-exports-download-response-400-schema).


### user-action-audit-exports-download Response 503 schema

Content type: `application/json`.

See [response 400 schema](#user-action-audit-exports-download-response-400-schema).


**Responses:**

- `200` — Operation succeeded.
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## External Funding

### GET /client-accounts/{client_account_id}/external-settlement-balances

**List client-account external funding balances**

Returns current external funding spend authority for a client account. This endpoint is separate from ledger balances, is informational, and provider unavailability is surfaced as provider_unavailable (503) instead of a zero balance. The read resolves the external_source_spend binding. Currency is optional; unsupported currency returns unsupported_currency (422). Missing binding, external-funding mode, or client mapping returns 404. The caller needs accounts.read coverage on the client account. available, held, and total are decimal strings in the item currency; held and total may be absent. This snapshot neither reserves funds nor guarantees later execution.

**Required capability:** `accounts.read`

**Authentication:** Bearer token required.

**Parameters:**

- `client_account_id` `string` (path) *(required)*
- `currency` `string` (query)

### client-accounts-external-settlement-balances Response 200 schema

Content type: `application/json`.

#### application/json body

External settlement balance reads are informational spend-authority reads. Provider unavailability is surfaced as a typed error and is not mapped to zero balance.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

External settlement balance reads are informational spend-authority reads. Provider unavailability is surfaced as a typed error and is not mapped to zero balance.

| 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})$` |
| `as_of` | string or string | Yes |  |
| `available` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |
| `currency` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `held` | string | No | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |
| `source` | "external_settlement" | Yes |  |
| `total` | string | No | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |

Additional fields are not accepted.

###### application/json body.items item.as_of

At least one alternative must match.

###### application/json body.items item.as_of: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.as_of: alternative 2

Type: `string`. format: date-time


### client-accounts-external-settlement-balances 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.


### client-accounts-external-settlement-balances Response 401 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.


### client-accounts-external-settlement-balances Response 403 schema

Content type: `application/json`.

See [response 401 schema](#client-accounts-external-settlement-balances-response-401-schema).


### client-accounts-external-settlement-balances Response 404 schema

Content type: `application/json`.

See [response 401 schema](#client-accounts-external-settlement-balances-response-401-schema).


### client-accounts-external-settlement-balances Response 422 schema

Content type: `application/json`.

See [response 401 schema](#client-accounts-external-settlement-balances-response-401-schema).


### client-accounts-external-settlement-balances Response 500 schema

Content type: `application/json`.

See [response 401 schema](#client-accounts-external-settlement-balances-response-401-schema).


### client-accounts-external-settlement-balances Response 502 schema

Content type: `application/json`.

See [response 400 schema](#client-accounts-external-settlement-balances-response-400-schema).


### client-accounts-external-settlement-balances Response 503 schema

Content type: `application/json`.

See [response 400 schema](#client-accounts-external-settlement-balances-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "account_ref": "client-accounts/00000000-0000-4000-8000-000000000001",
        "as_of": "2026-05-01T10:00:00Z",
        "available": "950.00",
        "currency": "EUR",
        "held": "50.00",
        "source": "external_settlement",
        "total": "1000.00"
      }
    ]
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `422` — The request cannot be processed under the resource or route contract. Depending on the endpoint, code can be not_admissible or unsupported_currency; inspect the documented code and data.reason.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## KYC

### POST /kyc/access-token

**Issue verification access token**

Mints a short-lived WebSDK access token for the authenticated enterprise on the given verification stage (defaults to the first stage of the resolved flow). A stage behind the one the applicant is already on is refused with `flow_unresolved`: opening it would move the applicant back to a stage it has passed. The stage the applicant is on can always be opened again, for a resubmission.

**Required capability:** `kyc.verify`

**Authentication:** Bearer token required.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `stage` | "identity" / "company" / "signatories" / "form_k" / "international_account_intake" | No |  |

Additional fields are not accepted.

**Request example:**

```json
{
  "stage": "company"
}
```

### kyc-access-token Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `external_user_id` | string | Yes | minLength: 1; maxLength: 255 |
| `token` | string | Yes | minLength: 1 |

Additional fields are not accepted.


| Response header | Type | Description |
| --- | --- | --- |
| `Cache-Control` | "no-store" |  |

### kyc-access-token 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.


### kyc-access-token Response 401 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.


### kyc-access-token Response 403 schema

Content type: `application/json`.

See [response 401 schema](#kyc-access-token-response-401-schema).


### kyc-access-token Response 409 schema

Content type: `application/json`.

See [response 401 schema](#kyc-access-token-response-401-schema).


### kyc-access-token Response 500 schema

Content type: `application/json`.

See [response 401 schema](#kyc-access-token-response-401-schema).


### kyc-access-token Response 502 schema

Content type: `application/json`.

See [response 400 schema](#kyc-access-token-response-400-schema).


### kyc-access-token Response 503 schema

Content type: `application/json`.

See [response 400 schema](#kyc-access-token-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "external_user_id": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "token": "_act-sbx-jwt-eyJhbGciOiJub25lIn0..."
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /kyc/clients/{client_id}/sessions

**Start client verification session**

Initiates KYC/KYB onboarding for an End Client owned by the caller enterprise. Returns an embeddable WebSDK access token, a provider-hosted verification link, and the resolved stage flow. `legal_form` is required for company onboarding in legal-form jurisdictions (AR).

**Required capability:** `kyc.verify`

**Authentication:** Bearer token required.

**Parameters:**

- `client_id` `string` (path) *(required)*

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `applicant_type` | "individual" / "company" | Yes |  |
| `country` | string | Yes | minLength: 2; maxLength: 2 |
| `legal_form` | "SA" / "SRL" / "SAS" / "SH" / "CH1_SEC_IV" / "ASSOC_FOUND" / "COOP" / "SCS" / "SCA" / "TRUST" | No |  |

Additional fields are not accepted.

**Request example:**

```json
{
  "applicant_type": "company",
  "country": "AR",
  "legal_form": "SA"
}
```

### kyc-clients-sessions Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `access_token` | string | Yes | minLength: 1 |
| `external_user_id` | string | Yes | minLength: 1; maxLength: 255 |
| `flow` | object | Yes | No additional fields |
| `verification_link` | string | Yes | minLength: 1; maxLength: 2048 |

Additional fields are not accepted.

##### application/json body.flow

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `jurisdiction` | string or null | Yes |  |
| `legal_form_required` | boolean | Yes |  |
| `legal_form_supported` | boolean | Yes |  |
| `stages` | object[] | Yes |  |

Additional fields are not accepted.

###### application/json body.flow.jurisdiction

At least one alternative must match.

###### application/json body.flow.jurisdiction: alternative 1

Type: `string`. 

###### application/json body.flow.jurisdiction: alternative 2

Type: `null`. 

###### application/json body.flow.stages

Type: `object[]`. 

###### application/json body.flow.stages item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `id` | "identity" / "company" / "signatories" / "form_k" | Yes |  |

Additional fields are not accepted.


| Response header | Type | Description |
| --- | --- | --- |
| `Cache-Control` | "no-store" |  |

### kyc-clients-sessions 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.


### kyc-clients-sessions Response 401 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.


### kyc-clients-sessions Response 403 schema

Content type: `application/json`.

See [response 401 schema](#kyc-clients-sessions-response-401-schema).


### kyc-clients-sessions Response 404 schema

Content type: `application/json`.

See [response 401 schema](#kyc-clients-sessions-response-401-schema).


### kyc-clients-sessions Response 409 schema

Content type: `application/json`.

See [response 401 schema](#kyc-clients-sessions-response-401-schema).


### kyc-clients-sessions Response 500 schema

Content type: `application/json`.

See [response 401 schema](#kyc-clients-sessions-response-401-schema).


### kyc-clients-sessions Response 502 schema

Content type: `application/json`.

See [response 400 schema](#kyc-clients-sessions-response-400-schema).


### kyc-clients-sessions Response 503 schema

Content type: `application/json`.

See [response 400 schema](#kyc-clients-sessions-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "access_token": "_act-sbx-jwt-eyJhbGciOiJub25lIn0...",
    "external_user_id": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "flow": {
      "jurisdiction": "AR",
      "legal_form_required": false,
      "legal_form_supported": true,
      "stages": [
        {
          "id": "company"
        }
      ]
    },
    "verification_link": "https://in.sumsub.com/websdk/p/sbx_AbCdEf123456"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /kyc/clients/{client_id}/status

**Get client verification status**

Reads an End Client applicant's onboarding progress (stage, case status, review outcome), after asserting the caller enterprise owns the client.

**Required capability:** `kyc.verify`

**Authentication:** Bearer token required.

**Parameters:**

- `client_id` `string` (path) *(required)*

### kyc-clients-status Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `outcome` | "approved" / "rejected" / "resubmission_required" or null | Yes |  |
| `stage` | "identity" / "company" / "signatories" / "form_k" / "international_account_intake" or null | Yes |  |
| `status` | "not_started" / "pending" / "in_review" / "completed" | Yes |  |

Additional fields are not accepted.

##### application/json body.outcome

At least one alternative must match.

###### application/json body.outcome: alternative 1

Type: `"approved" / "rejected" / "resubmission_required"`. 

###### application/json body.outcome: alternative 2

Type: `null`. 

##### application/json body.stage

At least one alternative must match.

###### application/json body.stage: alternative 1

Type: `"identity" / "company" / "signatories" / "form_k" / "international_account_intake"`. 

###### application/json body.stage: alternative 2

Type: `null`.


### kyc-clients-status 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.


### kyc-clients-status Response 401 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.


### kyc-clients-status Response 403 schema

Content type: `application/json`.

See [response 401 schema](#kyc-clients-status-response-401-schema).


### kyc-clients-status Response 404 schema

Content type: `application/json`.

See [response 401 schema](#kyc-clients-status-response-401-schema).


### kyc-clients-status Response 500 schema

Content type: `application/json`.

See [response 401 schema](#kyc-clients-status-response-401-schema).


### kyc-clients-status Response 502 schema

Content type: `application/json`.

See [response 400 schema](#kyc-clients-status-response-400-schema).


### kyc-clients-status Response 503 schema

Content type: `application/json`.

See [response 400 schema](#kyc-clients-status-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "outcome": "approved",
    "stage": "company",
    "status": "completed"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /kyc/flow

**Get KYB onboarding flow**

Returns the ordered verification stages the authenticated enterprise walks through, resolved from its jurisdiction. `legal_form_required` signals the frontend must capture the company legal form (AR) before the company stage can open. After an Argentine legal form is captured, the AR flow contains a single `company` stage; it does not include `signatories` or `form_k`. Drive onboarding from the returned stages.

**Required capability:** `kyc.verify`

**Authentication:** Bearer token required.

### kyc-flow Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `jurisdiction` | string or null | Yes |  |
| `jurisdiction_selected` | boolean | Yes |  |
| `legal_form_required` | boolean | Yes |  |
| `legal_form_supported` | boolean | Yes |  |
| `stages` | object[] | Yes |  |

Additional fields are not accepted.

##### application/json body.jurisdiction

At least one alternative must match.

###### application/json body.jurisdiction: alternative 1

Type: `string`. 

###### application/json body.jurisdiction: alternative 2

Type: `null`. 

##### application/json body.stages

Type: `object[]`. 

###### application/json body.stages item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `id` | "identity" / "company" / "signatories" / "form_k" | Yes |  |

Additional fields are not accepted.


### kyc-flow 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.


### kyc-flow Response 401 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.


### kyc-flow Response 403 schema

Content type: `application/json`.

See [response 401 schema](#kyc-flow-response-401-schema).


### kyc-flow Response 500 schema

Content type: `application/json`.

See [response 401 schema](#kyc-flow-response-401-schema).


### kyc-flow Response 502 schema

Content type: `application/json`.

See [response 400 schema](#kyc-flow-response-400-schema).


### kyc-flow Response 503 schema

Content type: `application/json`.

See [response 400 schema](#kyc-flow-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "jurisdiction": "CH",
    "jurisdiction_selected": true,
    "legal_form_required": false,
    "legal_form_supported": false,
    "stages": [
      {
        "id": "company"
      },
      {
        "id": "signatories"
      },
      {
        "id": "form_k"
      }
    ]
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /kyc/form-k/prepare

**Prepare Form K**

Pre-fills the Form K questionnaire with data collected during earlier KYB stages and advances the applicant to the `form_k` stage. Call before launching the WebSDK on the Form K stage, and only when `form_k` appears in the resolved `GET /kyc/flow` stages. The Argentine company flow does not require Form K. `fields_set: 0` means the applicant is already past Form K (on the international-account intake): nothing was moved or prefilled, and the Form K stage must not be opened.

**Required capability:** `kyc.verify`

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

### kyc-prepare Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `applicant_id` | string | Yes |  |
| `fields_set` | integer | Yes | minimum: -9007199254740991; maximum: 9007199254740991 |

Additional fields are not accepted.


### kyc-prepare 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.


### kyc-prepare Response 401 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.


### kyc-prepare Response 403 schema

Content type: `application/json`.

See [response 401 schema](#kyc-prepare-response-401-schema).


### kyc-prepare Response 409 schema

Content type: `application/json`.

See [response 401 schema](#kyc-prepare-response-401-schema).


### kyc-prepare Response 500 schema

Content type: `application/json`.

See [response 401 schema](#kyc-prepare-response-401-schema).


### kyc-prepare Response 502 schema

Content type: `application/json`.

See [response 400 schema](#kyc-prepare-response-400-schema).


### kyc-prepare Response 503 schema

Content type: `application/json`.

See [response 400 schema](#kyc-prepare-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "applicant_id": "68b1a2c3d4e5f60718293a4b",
    "fields_set": 5
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### POST /kyc/international-intake/prepare

**Prepare international-account intake**

Sends the authenticated enterprise to the additional questionnaire an international account needs: website, industry, regulated activities, operating address, the tax-id registration (CUIT certificate in Argentina), the gross-income tax registration (Ingresos Brutos in Argentina), the certificate of good standing and the designation of authorities. Available only once KYB verification is complete (verified by the provider, and since then neither reopened for review, rejected nor restricted) and only in jurisdictions with an intake; never part of the KYB flow and never changes the verification status. Forward only: an applicant already on the intake is not moved again. Then launch the WebSDK on the `international_account_intake` stage. The response names the stage the applicant sits on afterwards.

**Required capability:** `kyc.verify`

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

### kyc-international-intake-prepare Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `stage` | "identity" / "company" / "signatories" / "form_k" / "international_account_intake" or null | Yes |  |

Additional fields are not accepted.

##### application/json body.stage

At least one alternative must match.

###### application/json body.stage: alternative 1

Type: `"identity" / "company" / "signatories" / "form_k" / "international_account_intake"`. 

###### application/json body.stage: alternative 2

Type: `null`.


### kyc-international-intake-prepare 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.


### kyc-international-intake-prepare Response 401 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.


### kyc-international-intake-prepare Response 403 schema

Content type: `application/json`.

See [response 401 schema](#kyc-international-intake-prepare-response-401-schema).


### kyc-international-intake-prepare Response 409 schema

Content type: `application/json`.

See [response 401 schema](#kyc-international-intake-prepare-response-401-schema).


### kyc-international-intake-prepare Response 500 schema

Content type: `application/json`.

See [response 401 schema](#kyc-international-intake-prepare-response-401-schema).


### kyc-international-intake-prepare Response 502 schema

Content type: `application/json`.

See [response 400 schema](#kyc-international-intake-prepare-response-400-schema).


### kyc-international-intake-prepare Response 503 schema

Content type: `application/json`.

See [response 400 schema](#kyc-international-intake-prepare-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "stage": "international_account_intake"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### PUT /kyc/jurisdiction

**Set KYB registration jurisdiction**

Captures the registration jurisdiction the enterprise picks at the start of onboarding (ISO 3166-1 alpha-2). The flow endpoint prefers this over the placeholder jurisdiction stamped at admission, so the entry step decides which SumSub chain opens: 'AR' routes to the Argentine legal-form flow (then a legal form is required), any other code to the GLOBAL flow.

**Required capability:** `kyc.verify`

**Authentication:** Bearer token required.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `jurisdiction` | string | Yes | pattern: `^[A-Z]{2}$`; minLength: 2; maxLength: 2 |

Additional fields are not accepted.

**Request example:**

```json
{
  "jurisdiction": "AR"
}
```

### kyc-jurisdiction Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `jurisdiction` | string | Yes |  |

Additional fields are not accepted.


### kyc-jurisdiction 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.


### kyc-jurisdiction Response 401 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.


### kyc-jurisdiction Response 403 schema

Content type: `application/json`.

See [response 401 schema](#kyc-jurisdiction-response-401-schema).


### kyc-jurisdiction Response 500 schema

Content type: `application/json`.

See [response 401 schema](#kyc-jurisdiction-response-401-schema).


### kyc-jurisdiction Response 502 schema

Content type: `application/json`.

See [response 400 schema](#kyc-jurisdiction-response-400-schema).


### kyc-jurisdiction Response 503 schema

Content type: `application/json`.

See [response 400 schema](#kyc-jurisdiction-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "jurisdiction": "AR"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### PUT /kyc/legal-form

**Set company legal form**

Captures the enterprise's company legal form (e.g. SA/SRL/SAS for Argentina) so the flow endpoint can resolve the matching company verification level.

**Required capability:** `kyc.verify`

**Authentication:** Bearer token required.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `legal_form` | "SA" / "SRL" / "SAS" / "SH" / "CH1_SEC_IV" / "ASSOC_FOUND" / "COOP" / "SCS" / "SCA" / "TRUST" | Yes |  |

Additional fields are not accepted.

**Request example:**

```json
{
  "legal_form": "SA"
}
```

### kyc-legal-form Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `legal_form` | "SA" / "SRL" / "SAS" / "SH" / "CH1_SEC_IV" / "ASSOC_FOUND" / "COOP" / "SCS" / "SCA" / "TRUST" | Yes |  |

Additional fields are not accepted.


### kyc-legal-form 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.


### kyc-legal-form Response 401 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.


### kyc-legal-form Response 403 schema

Content type: `application/json`.

See [response 401 schema](#kyc-legal-form-response-401-schema).


### kyc-legal-form Response 500 schema

Content type: `application/json`.

See [response 401 schema](#kyc-legal-form-response-401-schema).


### kyc-legal-form Response 502 schema

Content type: `application/json`.

See [response 400 schema](#kyc-legal-form-response-400-schema).


### kyc-legal-form Response 503 schema

Content type: `application/json`.

See [response 400 schema](#kyc-legal-form-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "legal_form": "SA"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /kyc/status

**Get verification status**

Reads the authenticated enterprise applicant's onboarding progress: the current verification stage, case status, and latest review outcome.

**Required capability:** `kyc.verify`

**Authentication:** Bearer token required.

### kyc-status Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `outcome` | "approved" / "rejected" / "resubmission_required" or null | Yes |  |
| `stage` | "identity" / "company" / "signatories" / "form_k" / "international_account_intake" or null | Yes |  |
| `status` | "not_started" / "pending" / "in_review" / "completed" | Yes |  |

Additional fields are not accepted.

##### application/json body.outcome

At least one alternative must match.

###### application/json body.outcome: alternative 1

Type: `"approved" / "rejected" / "resubmission_required"`. 

###### application/json body.outcome: alternative 2

Type: `null`. 

##### application/json body.stage

At least one alternative must match.

###### application/json body.stage: alternative 1

Type: `"identity" / "company" / "signatories" / "form_k" / "international_account_intake"`. 

###### application/json body.stage: alternative 2

Type: `null`.


### kyc-status 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.


### kyc-status Response 401 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.


### kyc-status Response 403 schema

Content type: `application/json`.

See [response 401 schema](#kyc-status-response-401-schema).


### kyc-status Response 500 schema

Content type: `application/json`.

See [response 401 schema](#kyc-status-response-401-schema).


### kyc-status Response 502 schema

Content type: `application/json`.

See [response 400 schema](#kyc-status-response-400-schema).


### kyc-status Response 503 schema

Content type: `application/json`.

See [response 400 schema](#kyc-status-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "outcome": "approved",
    "stage": "signatories",
    "status": "completed"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Legal

### POST /legal/acceptances

**Record that the caller accepted legal documents**

Idempotent per document revision. Accepting a revision that is no longer published is rejected, because the caller displayed text that is not in force. Only human principals can record consent; the session determines subject and optional client scope. Re-accepting keeps the original evidence timestamp.

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `documents` | object[] | Yes | minItems: 1; maxItems: 20 |
| `locale` | string | No | pattern: `^[a-z]{2}(-[A-Z]{2})?$` |

Additional fields are not accepted.

#### Request body schema.documents

Type: `object[]`. minItems: 1; maxItems: 20

##### Request body schema.documents item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `code` | string | Yes | pattern: `^[a-z][a-z0-9_]{2,63}$` |
| `version` | string | Yes | pattern: `^\d{4}-\d{2}-\d{2}(\.\d+)?$` |

Additional fields are not accepted.

**Request example:**

```json
{
  "documents": [
    {
      "code": "ar_cvu_terms",
      "version": "2025-12-30"
    }
  ]
}
```

### legal-acceptances Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `accepted_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))$` |
| `code` | string | Yes | pattern: `^[a-z][a-z0-9_]{2,63}$` |
| `locale` | string | Yes | pattern: `^[a-z]{2}(-[A-Z]{2})?$` |
| `scope_ref` | string or null | Yes |  |
| `subject_ref` | string | Yes | pattern: `^(users\|service-accounts\|platform-principals\|identity-providers)\/([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})$` |
| `version` | string | Yes | pattern: `^\d{4}-\d{2}-\d{2}(\.\d+)?$` |

Additional fields are not accepted.

###### application/json body.items item.scope_ref

At least one alternative must match.

###### application/json body.items item.scope_ref: alternative 1

Type: `string`. pattern: `^(clients)\/([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})$`

###### application/json body.items item.scope_ref: alternative 2

Type: `null`.


### legal-acceptances 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.


### legal-acceptances Response 401 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.


### legal-acceptances Response 403 schema

Content type: `application/json`.

See [response 401 schema](#legal-acceptances-response-401-schema).


### legal-acceptances Response 409 schema

Content type: `application/json`.

See [response 401 schema](#legal-acceptances-response-401-schema).


### legal-acceptances Response 500 schema

Content type: `application/json`.

See [response 401 schema](#legal-acceptances-response-401-schema).


### legal-acceptances Response 502 schema

Content type: `application/json`.

See [response 400 schema](#legal-acceptances-response-400-schema).


### legal-acceptances Response 503 schema

Content type: `application/json`.

See [response 400 schema](#legal-acceptances-response-400-schema).


**Responses:**

- `201` — Resource created successfully.

  ```json
  {
    "items": [
      {
        "accepted_at": "2026-08-25T12:18:18.576Z",
        "code": "ar_cvu_terms",
        "locale": "es-AR",
        "scope_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "subject_ref": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "version": "2025-12-30"
      }
    ]
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /legal/documents/{code}

**Read the text of a legal document**

Returns the published revision by default. Pass `version` to read the exact revision an earlier acceptance points at. Content is Markdown. Locale defaults to the deployment setting; missing translations fall back to that locale.

**Authentication:** Bearer token required.

**Parameters:**

- `code` `string` (path) *(required)*
- `locale` `string` (query)
- `version` `string` (query)

### legal-documents-get Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `code` | string | Yes | pattern: `^[a-z][a-z0-9_]{2,63}$` |
| `content` | string | Yes | minLength: 1 |
| `content_format` | "markdown" | Yes |  |
| `jurisdiction` | string | Yes | pattern: `^[A-Z]{3}$` |
| `locale` | string | Yes | pattern: `^[a-z]{2}(-[A-Z]{2})?$` |
| `published_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))$` |
| `title` | string | Yes | minLength: 1; maxLength: 300 |
| `version` | string | Yes | pattern: `^\d{4}-\d{2}-\d{2}(\.\d+)?$` |

Additional fields are not accepted.


### legal-documents-get 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.


### legal-documents-get Response 401 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.


### legal-documents-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#legal-documents-get-response-401-schema).


### legal-documents-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#legal-documents-get-response-401-schema).


### legal-documents-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#legal-documents-get-response-401-schema).


### legal-documents-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#legal-documents-get-response-400-schema).


### legal-documents-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#legal-documents-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "code": "ar_cvu_terms",
    "content": "# TÉRMINOS Y CONDICIONES DEL SERVICIO DE CUENTA DE PAGO (CVU)\n\n…",
    "content_format": "markdown",
    "jurisdiction": "ARG",
    "locale": "es-AR",
    "published_at": "2025-12-30T00:00:00.000Z",
    "title": "Términos y Condiciones del Servicio de Cuenta de Pago (CVU)",
    "version": "2025-12-30"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /legal/requirements

**List the legal documents the caller must accept**

Resolved for the authenticated human actor against the documents published for the deployment default jurisdiction. Filter by `trigger` to answer "may this action proceed"; `pending_only=true` drops what is already accepted. A newer published revision makes an older acceptance pending again. Only human principals are supported; subject and optional client scope come from the session.

**Authentication:** Bearer token required.

**Parameters:**

- `trigger` `string` (query)
- `locale` `string` (query)
- `pending_only` `string` (query)

### legal-requirements Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `accepted_at` | string or null | Yes |  |
| `accepted_version` | string or null | Yes |  |
| `blocking` | boolean | Yes |  |
| `display_order` | integer | Yes | minimum: 0; maximum: 9007199254740991 |
| `document` | object | Yes | No additional fields |
| `state` | "pending" / "accepted" | Yes |  |
| `trigger` | "onboarding" / "post_verification" / "payment_account_cvu" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.accepted_at

At least one alternative must match.

###### application/json body.items item.accepted_at: alternative 1

Type: `string`. 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))$`

###### application/json body.items item.accepted_at: alternative 2

Type: `null`. 

###### application/json body.items item.accepted_version

At least one alternative must match.

###### application/json body.items item.accepted_version: alternative 1

Type: `string`. pattern: `^\d{4}-\d{2}-\d{2}(\.\d+)?$`

###### application/json body.items item.accepted_version: alternative 2

Type: `null`. 

###### application/json body.items item.document

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `code` | string | Yes | pattern: `^[a-z][a-z0-9_]{2,63}$` |
| `content_format` | "markdown" | Yes |  |
| `jurisdiction` | string | Yes | pattern: `^[A-Z]{3}$` |
| `locale` | string | Yes | pattern: `^[a-z]{2}(-[A-Z]{2})?$` |
| `published_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))$` |
| `title` | string | Yes | minLength: 1; maxLength: 300 |
| `version` | string | Yes | pattern: `^\d{4}-\d{2}-\d{2}(\.\d+)?$` |

Additional fields are not accepted.


### legal-requirements 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.


### legal-requirements Response 401 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.


### legal-requirements Response 403 schema

Content type: `application/json`.

See [response 401 schema](#legal-requirements-response-401-schema).


### legal-requirements Response 404 schema

Content type: `application/json`.

See [response 401 schema](#legal-requirements-response-401-schema).


### legal-requirements Response 500 schema

Content type: `application/json`.

See [response 401 schema](#legal-requirements-response-401-schema).


### legal-requirements Response 502 schema

Content type: `application/json`.

See [response 400 schema](#legal-requirements-response-400-schema).


### legal-requirements Response 503 schema

Content type: `application/json`.

See [response 400 schema](#legal-requirements-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "accepted_at": null,
        "accepted_version": null,
        "blocking": true,
        "display_order": 0,
        "document": {
          "code": "ar_cvu_terms",
          "content_format": "markdown",
          "jurisdiction": "ARG",
          "locale": "es-AR",
          "published_at": "2025-12-30T00:00:00.000Z",
          "title": "Términos y Condiciones del Servicio de Cuenta de Pago (CVU)",
          "version": "2025-12-30"
        },
        "state": "pending",
        "trigger": "payment_account_cvu"
      }
    ]
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Loans

### GET /loans/{loan_id}

**Get a loan**

Returns the caller's loan: its current debt split, its latest valuation and its obligations. The loans.read grant must cover the loan borrower account; otherwise the service returns 403.

**Required capability:** `loans.read`

**Authentication:** Bearer token required.

**Parameters:**

- `loan_id` `string` (path) *(required)*

### loans-get Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `arrears_since` | string or null | Yes |  |
| `close_reason` | "repaid" / "matured" / "ltv_breach" / "offboarding" or null | Yes |  |
| `collateral_amount` | object | Yes | No additional fields |
| `collateral_held` | object | Yes | No additional fields |
| `created_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))$` |
| `full_payoff_amount` | object | Yes | No additional fields |
| `last_ltv` | string or null | Yes |  |
| `last_valued_at` | string or null | Yes |  |
| `liquidation_threshold` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |
| `loan_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)$` |
| `margin_call_since` | string or null | Yes |  |
| `margin_call_threshold` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |
| `matures_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))$` |
| `next_charge_at` | string or null | Yes |  |
| `outstanding` | object | Yes | No additional fields |
| `outstanding_total` | object | Yes | No additional fields |
| `price` | string or null | Yes |  |
| `price_age_ms` | integer or null | Yes |  |
| `price_observed_at` | string or null | Yes |  |
| `price_source` | string or null | Yes |  |
| `principal_amount` | object | Yes | No additional fields |
| `status` | "requested" / "awaiting_approval" / "awaiting_compliance" / "active" / "denied" / "origination_failed" / "liquidating" / "liquidation_halted" / "liquidated" / "closed" | Yes |  |
| `updated_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))$` |

Additional fields are not accepted.

##### application/json body.arrears_since

At least one alternative must match.

###### application/json body.arrears_since: alternative 1

Type: `string`. 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))$`

###### application/json body.arrears_since: alternative 2

Type: `null`. 

##### application/json body.close_reason

At least one alternative must match.

###### application/json body.close_reason: alternative 1

Type: `"repaid" / "matured" / "ltv_breach" / "offboarding"`. 

###### application/json body.close_reason: alternative 2

Type: `null`. 

##### application/json body.collateral_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.

##### application/json body.collateral_held

| 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.

##### application/json body.full_payoff_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.

##### application/json body.last_ltv

At least one alternative must match.

###### application/json body.last_ltv: alternative 1

DecimalString

Type: `string`. pattern: `^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$`

###### application/json body.last_ltv: alternative 2

Type: `null`. 

##### application/json body.last_valued_at

At least one alternative must match.

###### application/json body.last_valued_at: alternative 1

Type: `string`. 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))$`

###### application/json body.last_valued_at: alternative 2

Type: `null`. 

##### application/json body.margin_call_since

At least one alternative must match.

###### application/json body.margin_call_since: alternative 1

Type: `string`. 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))$`

###### application/json body.margin_call_since: alternative 2

Type: `null`. 

##### application/json body.next_charge_at

At least one alternative must match.

###### application/json body.next_charge_at: alternative 1

Type: `string`. 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))$`

###### application/json body.next_charge_at: alternative 2

Type: `null`. 

##### application/json body.outstanding

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `fees` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |
| `interest` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |
| `penalty_interest` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |
| `principal` | string | Yes | DecimalString pattern: `^(0\|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$` |

Additional fields are not accepted.

##### application/json body.outstanding_total

| 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.

##### application/json body.price

At least one alternative must match.

###### application/json body.price: alternative 1

DecimalString

Type: `string`. pattern: `^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$`

###### application/json body.price: alternative 2

Type: `null`. 

##### application/json body.price_age_ms

At least one alternative must match.

###### application/json body.price_age_ms: alternative 1

Type: `integer`. minimum: -9007199254740991; maximum: 9007199254740991

###### application/json body.price_age_ms: alternative 2

Type: `null`. 

##### application/json body.price_observed_at

At least one alternative must match.

###### application/json body.price_observed_at: alternative 1

Type: `string`. 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))$`

###### application/json body.price_observed_at: alternative 2

Type: `null`. 

##### application/json body.price_source

At least one alternative must match.

###### application/json body.price_source: alternative 1

Type: `string`. 

###### application/json body.price_source: alternative 2

Type: `null`. 

##### application/json body.principal_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.


### loans-get 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.


### loans-get Response 401 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.


### loans-get Response 403 schema

Content type: `application/json`.

See [response 401 schema](#loans-get-response-401-schema).


### loans-get Response 404 schema

Content type: `application/json`.

See [response 401 schema](#loans-get-response-401-schema).


### loans-get Response 500 schema

Content type: `application/json`.

See [response 401 schema](#loans-get-response-401-schema).


### loans-get Response 502 schema

Content type: `application/json`.

See [response 400 schema](#loans-get-response-400-schema).


### loans-get Response 503 schema

Content type: `application/json`.

See [response 400 schema](#loans-get-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "arrears_since": null,
    "close_reason": null,
    "collateral_amount": {
      "currency": "BTC",
      "value": "2.00000000"
    },
    "collateral_held": {
      "currency": "BTC",
      "value": "2.00000000"
    },
    "created_at": "2026-04-01T00:00:00Z",
    "full_payoff_amount": {
      "currency": "USD",
      "value": "50170.6205"
    },
    "last_ltv": "0.5",
    "last_valued_at": "2026-05-01T10:00:00Z",
    "liquidation_threshold": "0.75",
    "loan_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "margin_call_since": null,
    "margin_call_threshold": "0.6",
    "matures_at": "2027-04-01T00:00:00Z",
    "next_charge_at": "2026-06-01T00:00:00Z",
    "outstanding": {
      "fees": "0",
      "interest": "120.50",
      "penalty_interest": "0",
      "principal": "50000.00"
    },
    "outstanding_total": {
      "currency": "USD",
      "value": "50120.50"
    },
    "price": "50000",
    "price_age_ms": 60000,
    "price_observed_at": "2026-05-01T09:59:00Z",
    "price_source": "internal-index",
    "principal_amount": {
      "currency": "USD",
      "value": "50000.00"
    },
    "status": "active",
    "updated_at": "2026-05-01T10:00:00Z"
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /loans/{loan_id}/history

**Get a loan's lifecycle history**

Returns a cursor-paginated page of the loan lifecycle history, ordered oldest first by occurrence time and transition id. page_size defaults to 50 and accepts 1–500. A malformed page_token returns 400. The loans.read grant must cover the loan borrower account.

**Required capability:** `loans.read`

**Authentication:** Bearer token required.

**Parameters:**

- `loan_id` `string` (path) *(required)*
- `page_size` `integer` (query) — Cursor pagination page size. The canonical contract accepts integers from 1 to 500.
- `page_token` `string` (query) — Opaque cursor returned by a previous page.

### loans-history Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `items` | object[] | Yes |  |
| `next_page_token` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.items

Type: `object[]`. 

###### application/json body.items item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `correlation_ref` | string or null | Yes |  |
| `from_status` | "requested" / "awaiting_approval" / "awaiting_compliance" / "active" / "denied" / "origination_failed" / "liquidating" / "liquidation_halted" / "liquidated" / "closed" or null | Yes |  |
| `occurred_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))$` |
| `reason` | "repaid" / "matured" / "ltv_breach" / "offboarding" or null | Yes |  |
| `to_status` | "requested" / "awaiting_approval" / "awaiting_compliance" / "active" / "denied" / "origination_failed" / "liquidating" / "liquidation_halted" / "liquidated" / "closed" | Yes |  |
| `trigger` | "borrower_command" / "operator_command" / "scheduler_tick" / "upstream_event" / "admissibility_verdict" | Yes |  |

Additional fields are not accepted.

###### application/json body.items item.correlation_ref

At least one alternative must match.

###### application/json body.items item.correlation_ref: alternative 1

Type: `string`. 

###### application/json body.items item.correlation_ref: alternative 2

Type: `null`. 

###### application/json body.items item.from_status

At least one alternative must match.

###### application/json body.items item.from_status: alternative 1

Type: `"requested" / "awaiting_approval" / "awaiting_compliance" / "active" / "denied" / "origination_failed" / "liquidating" / "liquidation_halted" / "liquidated" / "closed"`. 

###### application/json body.items item.from_status: alternative 2

Type: `null`. 

###### application/json body.items item.reason

At least one alternative must match.

###### application/json body.items item.reason: alternative 1

Type: `"repaid" / "matured" / "ltv_breach" / "offboarding"`. 

###### application/json body.items item.reason: alternative 2

Type: `null`. 

##### application/json body.next_page_token

At least one alternative must match.

###### application/json body.next_page_token: alternative 1

Type: `string`. 

###### application/json body.next_page_token: alternative 2

Type: `null`.


### loans-history 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.


### loans-history Response 401 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.


### loans-history Response 403 schema

Content type: `application/json`.

See [response 401 schema](#loans-history-response-401-schema).


### loans-history Response 404 schema

Content type: `application/json`.

See [response 401 schema](#loans-history-response-401-schema).


### loans-history Response 500 schema

Content type: `application/json`.

See [response 401 schema](#loans-history-response-401-schema).


### loans-history Response 502 schema

Content type: `application/json`.

See [response 400 schema](#loans-history-response-400-schema).


### loans-history Response 503 schema

Content type: `application/json`.

See [response 400 schema](#loans-history-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "items": [
      {
        "correlation_ref": null,
        "from_status": null,
        "occurred_at": "2026-04-01T00:00:00Z",
        "reason": null,
        "to_status": "requested",
        "trigger": "borrower_command"
      }
    ],
    "next_page_token": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

## Onboarding

### POST /production-access-requests

**Request production access**

Tells our compliance team that this sandbox tenant is ready to go live. Nothing is provisioned by the call and the sandbox tenant is unchanged: the two deployments are separate, so going live means a production account created for you by hand, and this is how we learn there is one to create. Requires a human user bound to an enterprise with a contact email. The company and contact address come from platform records; the optional note is the only body field, and the whole body may be omitted. A 200 means our team was reached; if they were not, the call fails with 503 and retrying is the right move. Asking again when you already have a request returns 409. The production deployment returns 409 with reason production_access_not_available.

**Required capability:** `kyc.verify`

**Authentication:** Bearer token required.

**Parameters:**

- `Idempotency-Key` `string` (header) — Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying.

**Request body** (`application/json`):

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `note` | string or null | No |  |

Additional fields are not accepted.

#### Request body schema.note

At least one alternative must match.

##### Request body schema.note: alternative 1

Type: `string`. maxLength: 2000

##### Request body schema.note: alternative 2

Type: `null`.

**Request example:**

```json
{
  "note": "We expect around 2,000 payouts a month across AR and BR, and we would like to be live before the end of the quarter."
}
```

### production-access-requests-create Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `created_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))$` |
| `enterprise_ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |
| `notified` | boolean or null | Yes |  |
| `production_access_request_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)$` |
| `provisioned_at` | string or null | Yes |  |

Additional fields are not accepted.

##### application/json body.notified

At least one alternative must match.

###### application/json body.notified: alternative 1

Type: `boolean`. 

###### application/json body.notified: alternative 2

Type: `null`. 

##### application/json body.provisioned_at

At least one alternative must match.

###### application/json body.provisioned_at: alternative 1

Type: `string`. 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))$`

###### application/json body.provisioned_at: alternative 2

Type: `null`.


### production-access-requests-create 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.


### production-access-requests-create Response 401 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.


### production-access-requests-create Response 403 schema

Content type: `application/json`.

See [response 401 schema](#production-access-requests-create-response-401-schema).


### production-access-requests-create Response 404 schema

Content type: `application/json`.

See [response 401 schema](#production-access-requests-create-response-401-schema).


### production-access-requests-create Response 409 schema

Content type: `application/json`.

See [response 401 schema](#production-access-requests-create-response-401-schema).


### production-access-requests-create Response 500 schema

Content type: `application/json`.

See [response 401 schema](#production-access-requests-create-response-401-schema).


### production-access-requests-create Response 502 schema

Content type: `application/json`.

See [response 400 schema](#production-access-requests-create-response-400-schema).


### production-access-requests-create Response 503 schema

Content type: `application/json`.

See [response 400 schema](#production-access-requests-create-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "created_at": "2026-04-19T12:00:00Z",
    "enterprise_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "notified": true,
    "production_access_request_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "provisioned_at": null
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `404` — Resource not found.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.

### GET /production-access-requests/current

**Read the current production access request**

Where your request to go live stands. `production_access_request: null` means no announcement has reached compliance; failed announcement attempts are not shown. A request with `provisioned_at: null` means production provisioning has not been recorded, and `created_at` is the day you asked. A request with `provisioned_at` set means your production account exists. Answers for your bound enterprise under kyc.verify. The production deployment returns 409 with reason production_access_not_available.

**Required capability:** `kyc.verify`

**Authentication:** Bearer token required.

### production-access-requests-current Response 200 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `production_access_request` | object or null | Yes |  |

Additional fields are not accepted.

##### application/json body.production_access_request

At least one alternative must match.

###### application/json body.production_access_request: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `created_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))$` |
| `enterprise_ref` | string | Yes | pattern: `^(enterprises)\/([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})$` |
| `notified` | boolean or null | Yes |  |
| `production_access_request_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)$` |
| `provisioned_at` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.production_access_request: alternative 1.notified

At least one alternative must match.

###### application/json body.production_access_request: alternative 1.notified: alternative 1

Type: `boolean`. 

###### application/json body.production_access_request: alternative 1.notified: alternative 2

Type: `null`. 

###### application/json body.production_access_request: alternative 1.provisioned_at

At least one alternative must match.

###### application/json body.production_access_request: alternative 1.provisioned_at: alternative 1

Type: `string`. 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))$`

###### application/json body.production_access_request: alternative 1.provisioned_at: alternative 2

Type: `null`. 

###### application/json body.production_access_request: alternative 2

Type: `null`.


### production-access-requests-current 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.


### production-access-requests-current Response 401 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.


### production-access-requests-current Response 403 schema

Content type: `application/json`.

See [response 401 schema](#production-access-requests-current-response-401-schema).


### production-access-requests-current Response 409 schema

Content type: `application/json`.

See [response 401 schema](#production-access-requests-current-response-401-schema).


### production-access-requests-current Response 500 schema

Content type: `application/json`.

See [response 401 schema](#production-access-requests-current-response-401-schema).


### production-access-requests-current Response 502 schema

Content type: `application/json`.

See [response 400 schema](#production-access-requests-current-response-400-schema).


### production-access-requests-current Response 503 schema

Content type: `application/json`.

See [response 400 schema](#production-access-requests-current-response-400-schema).


**Responses:**

- `200` — Operation succeeded.

  ```json
  {
    "production_access_request": {
      "created_at": "2026-04-19T12:00:00Z",
      "enterprise_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "notified": true,
      "production_access_request_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "provisioned_at": null
    }
  }
  ```
- `400` — Invalid request payload, query, or parameter shape.
- `401` — Caller is not authenticated or the bearer token is invalid.
- `403` — Caller lacks the required capability or permitted scope.
- `409` — State conflict — the request cannot be applied to the current resource state.
- `500` — An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.
- `502` — Upstream service returned an unexpected error.
- `503` — Service is temporarily unavailable; retry with backoff.
