Skip to main content

Create or replace an exposure limit

PUT 
/v1/exposure-limits/:issuer_bank_id/:asset_id

Create the calling bank's exposure limit on one issuer's root asset, or replace it if one exists.

Who may call it. Only the holder: the limit is always stored under the authenticated bank as holder_bank_id. The issuer named in the path cannot set or see it.

Upsert semantics. The request is a full replacement, not a partial update: the new amount replaces the previous one, and the first call for an issuer and root asset creates the limit. reason is recorded with the change but is not returned by GET.

Request identity checks (rejected synchronously with 400):

  • data.attributes.asset_id must equal the path asset_id (INVALID_FIELD_FORMAT, pointer /data/attributes/asset_id).
  • data.id must be exactly v1:{your_bank_id}:{issuer_bank_id}:{asset_id} using the path values, for example v1:22222222-2222-7222-8222-222222222222:11111111-1111-7111-8111-111111111111:usd (RESOURCE_ID_MISMATCH). Note that GET returns an id built from the issued asset id (...:usd.bank-alpha); do not reuse that value here.

Amount. amount.value is a non-negative integer string in the asset's minor units ("10000000" is 100,000.00 for a 2-decimal asset). amount.scale must be a non-negative integer; set it to the asset's decimals. The value is not rescaled by scale. Values above 9223372036854775807 are rejected with 400.

Asynchronous completion. Returns 202 Accepted with an operation. The operation reaches SUCCEEDED once the new limit is published to the platform; from then on it applies to new inbound transfers, and GET shows it shortly after. Poll GET /v1/operations/{operation_id} for the outcome.

In-flight changes. Only one change per exposure limit can be in progress. A new PUT for the same issuer and root asset while an earlier change has not finished is rejected with 400 and the title an earlier change to this resource is unresolved. Lowering a limit below the current holding does not unwind anything already held, but blocks further inbound transfers from that issuer until the holding falls below the new cap.

Retries. Send an Idempotency-Key. Repeating the same key with the same body returns the original 202 document; the same key with a different body returns 409.

Request​

Responses​

Change accepted for asynchronous processing. data.id is the operation_id; data.relationships.resource identifies the exposure limit being changed.