Organization settings API reference

Each organization keeps a set of key-value settings that configure how its platform behaves: the reporting base currency, the deployed system address, the fiat currencies that get on-chain price feeds, and whether account abstraction is enabled. Use these endpoints to read and write that store directly.

Reach for them when your integration manages organization configuration programmatically instead of through the Console. Each setting is scoped to the active organization, so you only ever see and change your own values.

The /settings path also hosts dedicated catalogs with richer schemas and their own pages: asset class definitions, instrument templates, and compliance templates. The endpoints below handle only the plain key-value store.

Endpoints

Read responses use the DALP single-resource envelope with data and links.self. List responses use the collection envelope with data, meta, and pagination links. Delete responses return { "data": null }.

Set the participant and wallet context with the standard request headers before calling these endpoints. See Request headers.

Required roles

Any authenticated member of the organization can read settings. Only administrators and owners can change or remove them.

Setting fields

List responses

GET /api/v2/settings returns a paginated collection. Each item in data contains these fields:

Values are always strings. A setting that holds a list, such as the set of target currencies, stores a JSON-encoded array in value.

Read and upsert responses

GET /api/v2/settings/{key} and POST /api/v2/settings return a single-resource envelope with only value inside data:

{
  "data": { "value": "EUR" },
  "links": { "self": "/v2/settings/BASE_CURRENCY" }
}

A key that has never been set returns "value": null.

Well-known keys

Some keys carry validation and behavior beyond a plain string write.

The write schema accepts only BASE_CURRENCY, SYSTEM_ADDRESS, TARGET_CURRENCIES, and AA_ENABLED. POSTing any other key fails validation. The read and delete parameters accept all six keys above, so a request for an unknown key still returns a validation error rather than a not-found response.

List settings

GET /api/v2/settings returns the active organization's settings. The list supports pagination, global search across key and value, sorting by key (default) or lastUpdated, and filtering by key, value, or an lastUpdated date range. The value field is filterable but not sortable.

curl --globoff "https://your-platform.example.com/api/v2/settings?filter[key]=CURRENC&sort=key" \
  -H "x-api-key: YOUR_API_KEY"

{
  "data": [
    {
      "key": "BASE_CURRENCY",
      "value": "EUR",
      "lastUpdated": "2026-01-01T00:00:00.000Z"
    },
    {
      "key": "TARGET_CURRENCIES",
      "value": "[\"EUR\",\"USD\"]",
      "lastUpdated": "2026-01-01T00:00:00.000Z"
    }
  ],
  "meta": {
    "total": 2,
    "facets": {}
  },
  "links": {
    "self": "/v2/settings?filter[key]=CURRENC&sort=key&page[offset]=0&page[limit]=50",
    "first": "/v2/settings?filter[key]=CURRENC&sort=key&page[offset]=0&page[limit]=50",
    "prev": null,
    "next": null,
    "last": "/v2/settings?filter[key]=CURRENC&sort=key&page[offset]=0&page[limit]=50"
  }
}

Read a setting

GET /api/v2/settings/{key} returns one value. A key that has never been set returns "value": null rather than an error, so a client can probe for a setting without handling a not-found case.

curl "https://your-platform.example.com/api/v2/settings/BASE_CURRENCY" \
  -H "x-api-key: YOUR_API_KEY"

{
  "data": { "value": "EUR" },
  "links": { "self": "/v2/settings/BASE_CURRENCY" }
}

Create or update a setting

POST /api/v2/settings writes a value, creating the key if it does not exist. Send a key and a value.

curl -X POST "https://your-platform.example.com/api/v2/settings" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "BASE_CURRENCY",
    "value": "EUR"
  }'

{
  "data": { "value": "EUR" },
  "links": { "self": "/v2/settings/BASE_CURRENCY" }
}

Target currencies are additive

TARGET_CURRENCIES drives on-chain price feeds, and a feed cannot be removed once it exists. Each write must therefore be a superset of the current set. You can add currencies, but a request that drops a previously enabled currency is rejected with DALP-0600. Every added currency must be supported by the configured exchange-rate provider. An unsupported code returns DALP-0601, which lists the offending codes. The active chain must also support currency feeds: a system with no feed directory returns DALP-0604, and a write that arrives before the directory is indexed returns the retryable DALP-0602. See Errors and retry behavior for the full set.

curl -X POST "https://your-platform.example.com/api/v2/settings" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "TARGET_CURRENCIES",
    "value": "[\"EUR\",\"USD\"]"
  }'

Account abstraction is one-way

AA_ENABLED can be turned on but not off. Once it is "true", a request to set it back to "false" returns DALP-0652. Enabling it also requires account abstraction to be enabled at the platform level first. Without that, the request returns DALP-0617.

Delete a setting

DELETE /api/v2/settings/{key} removes a setting. Deleting a key that does not exist returns DALP-0172.

curl -X DELETE "https://your-platform.example.com/api/v2/settings/SYSTEM_ADDRESS" \
  -H "x-api-key: YOUR_API_KEY"

{
  "data": null
}

Errors and retry behavior

A write or delete can fail for two different reasons, and your retry logic should treat them differently. A terminal failure means the request, the value, or the current state is wrong, so the same call fails the same way until you change it. A transient failure means the call was valid but a dependency was not ready, so a later attempt can succeed. One operational error reports that an internal write did not complete. For the full catalog of platform error codes, see the Platform API error reference.

The codes below are the ones specific to the key-value settings store. Two well-known keys reach further. A TARGET_CURRENCIES write that enables a feed, and an AA_ENABLED write that turns on account abstraction, run identity and on-chain steps with their own permission and state errors, such as a missing feed-manager role or an unsynced participant identity. When you write those keys, also handle the role and identity codes listed in the Platform API error reference.

Terminal errors

Fix the request, the value, or the setting state before you retry. Store the request ID from the API response when you escalate a repeated platform error.

Transient errors

Retry these after a short wait, or resolve the named cause first. The setting was not saved either way.

Operational write failure

Related references

• Asset class definitions
• Instrument templates
• Compliance templates
• Platform API error reference