postCreate commercial agreement version

Required capabilitycommercial_agreements.create

Authentication: Send Authorization: Bearer <access_token>.

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.

Parameters

Name Location Type Required Description and constraints
Idempotency-Key header string No 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. minLength: 1; maxLength: 128

Request

Required request body.

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 URL

POST
POST /enterprise-commercial-agreements

Request Body

application/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"
    }
  ]
}

Responses

Response

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

Resource created successfully.

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.

Response 400 schema

Content type: application/json.

application/json body

Field Type Required Description and constraints
code string Yes
data object No No additional fields
details object No Additional fields allowed
message string Yes

Additional fields are not accepted.

application/json body.data
Field Type Required Description and constraints
acr_values string No RFC 9470 step-up challenge (insufficient_user_authentication).
blockers object[] No For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition.
code string No For legal refusals: the document code the refusal is about.
max_age string No RFC 9470 step-up challenge (insufficient_user_authentication).
max_source_amount object No For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum. No additional fields
min_source_amount object No For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included. No additional fields
published_version string No For document_version_superseded: the version currently published.
reason string No Typed refinement of code, from the failing service's contract.
resource string No Resource kind a resource_not_found refers to.
retry_after_ms integer No Suggested back-off in milliseconds for throttling or temporary unavailability; null means no delay is known. minimum: 0
source string No For not_admissible: the gate that denied (verification, lifecycle, policy, compliance).

Additional fields are not accepted.

application/json body.data.blockers

For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition.

Type: object[].

application/json body.data.blockers item
Field Type Required Description and constraints
description string Yes
type "non_zero_balance" / "active_sub_resources" / "pending_operations" / "active_users" / "active_service_accounts" / "active_role_assignments" Yes
assets object[] No minItems: 1
count integer No minimum: 0; maximum: 9007199254740991

Additional fields are not accepted.

application/json body.data.blockers item.assets

Type: object[]. minItems: 1

application/json body.data.blockers item.assets item
Field Type Required Description and constraints
asset string Yes Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$
kind "balance" / "held" / "owed" / "unsettled" Yes

Additional fields are not accepted.

application/json body.data.max_source_amount

For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum.

Field Type Required Description and constraints
currency string Yes
value string Yes

Additional fields are not accepted.

application/json body.data.min_source_amount

For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included.

Field Type Required Description and constraints
currency string Yes
value string Yes

Additional fields are not accepted.

Response 401 schema

Content type: application/json.

application/json body

Field Type Required Description and constraints
code string Yes
data object No No additional fields
details object No Additional fields allowed
message string Yes

Additional fields are not accepted.

application/json body.data
Field Type Required Description and constraints
acr_values string No RFC 9470 step-up challenge (insufficient_user_authentication).
blockers object[] No For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition.
code string No For legal refusals: the document code the refusal is about.
max_age string No RFC 9470 step-up challenge (insufficient_user_authentication).
max_source_amount object or null No For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum. No additional fields
min_source_amount object No For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included. No additional fields
published_version string No For document_version_superseded: the version currently published.
reason string No Typed refinement of code, from the failing service's contract.
resource string No Resource kind a resource_not_found refers to.
retry_after_ms integer or null No Suggested back-off in milliseconds for throttling or temporary unavailability; null means no delay is known. minimum: 0
source string No For not_admissible: the gate that denied (verification, lifecycle, policy, compliance).

Additional fields are not accepted.

application/json body.data.blockers

For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition.

Type: object[].

application/json body.data.blockers item
Field Type Required Description and constraints
description string Yes
type "non_zero_balance" / "active_sub_resources" / "pending_operations" / "active_users" / "active_service_accounts" / "active_role_assignments" Yes
assets object[] No minItems: 1
count integer No minimum: 0; maximum: 9007199254740991

Additional fields are not accepted.

application/json body.data.blockers item.assets

Type: object[]. minItems: 1

application/json body.data.blockers item.assets item
Field Type Required Description and constraints
asset string Yes Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$
kind "balance" / "held" / "owed" / "unsettled" Yes

Additional fields are not accepted.

application/json body.data.max_source_amount

For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum.

Field Type Required Description and constraints
currency string Yes
value string Yes

Additional fields are not accepted.

application/json body.data.min_source_amount

For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included.

Field Type Required Description and constraints
currency string Yes
value string Yes

Additional fields are not accepted.

Response 403 schema

Content type: application/json.

See response 401 schema.

Response 404 schema

Content type: application/json.

See response 401 schema.

Response 409 schema

Content type: application/json.

See response 401 schema.

Response 500 schema

Content type: application/json.

See response 401 schema.

Response 502 schema

Content type: application/json.

See response 400 schema.

Response 503 schema

Content type: application/json.

See response 400 schema.