Fees & Monetization

Configure how you monetize crypto activity — list, read, create, update, and delete monetization settings such as trading fees, flat fees, and spread adjustments.

Set how you earn on your users' crypto activity. A monetization setting ties a fee or spread (method) to a feature (feature) — spot trades, RFQ quotes, or withdrawals — and optionally scopes it to an instrument (pair). List your settings, read one by ID, create new ones, update amounts, or remove them. Each setting is created against the custody provider and cached locally, so reads stay fast.

Authentication: every endpoint on this page requires your Owner API Key in the x-api-key header. A missing or invalid key returns 401 Unauthorized.

x-api-key: YOUR_OWNER_API_KEY

All requests accept an optional x-trace-id header for request tracking; if omitted, one is generated.

A setting splits its fields between request and response. You send feature, method, amount, and optionally pair; the API returns richer fields — feature_code, method_code, amount, and pair — plus human-readable labels.

Enum	Values
`feature`	`RFQ`, `SPOT_TRADE`, `WITHDRAW`
`method`	`FEE_RATE`, `FEE_FLAT`, `SPREAD_ADJUSTMENT`

The setting object returned in responses:

Field	Type	Description
`id`	number	ID assigned by the custody provider.
`feature`	string	Human-readable feature name (e.g. `Spot Trading`).
`feature_code`	string	Feature code (`RFQ`/`SPOT_TRADE`/`WITHDRAW`).
`method`	string	Human-readable method name (e.g. `Fee Rate`).
`method_code`	string	Method code (`FEE_RATE`/`FEE_FLAT`/`SPREAD_ADJUSTMENT`).
`amount`	number	Amount in decimal form (e.g. `0.01` = 1%).
`customer_id`	string\|null	The account the setting applies to, scoped from your API key.
`currency`	string\|null	Currency code, or `null`.
`pair`	string\|null	Instrument (e.g. `BTCUSD`), or `null`.
`created_at`	string (ISO 8601)	Creation timestamp.
`updated_at`	string (ISO 8601)	Last update timestamp.

List Settings

GEThttps://api.sandbox.sovera.io/sovx/v1/monetization/settings

List your monetization settings, fetched live from the custody provider and refreshed into the local cache on every call. Narrow the results by feature, method, or currency. If the upstream API is unavailable, the cached copy answers instead.

Query Parameters

Parameter	Type	Required	Description
feature	string	No	Filter by feature code (e.g. `SPOT_TRADE`).
method	string	No	Filter by method code (e.g. `FEE_RATE`).
currency	string	No	Filter by currency code (e.g. `BTC`).

Results are already scoped to the account behind your API key, so there's no user filter.

GET https://api.sandbox.sovera.io/sovx/v1/monetization/settings?feature=SPOT_TRADE

Success Response (200 OK):

{
  "success": true,
  "data": [
    {
      "id": 1310717,
      "feature": "Spot Trading",
      "feature_code": "SPOT_TRADE",
      "method": "Fee Rate",
      "method_code": "FEE_RATE",
      "amount": 0.01,
      "customer_id": "client25",
      "currency": "BTC",
      "pair": "BTCUSD",
      "created_at": "2023-06-07T21:49:22.000Z",
      "updated_at": "2023-06-07T21:49:22.000Z"
    }
  ],
  "meta": {
    "timestamp": "2026-01-15T10:30:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
  }
}

curl -X GET "https://api.sandbox.sovera.io/sovx/v1/monetization/settings?feature=SPOT_TRADE" \
  -H "x-api-key: YOUR_OWNER_API_KEY"

Errors: 401 missing or invalid key · 500 server error.

Get Setting

GEThttps://api.sandbox.sovera.io/sovx/v1/monetization/settings/:id

Retrieve a single monetization setting by its numeric id, served from the local cache. If no cached setting matches the ID for your account, the request returns 404 Not Found.

GET https://api.sandbox.sovera.io/sovx/v1/monetization/settings/{{settingID}}

Success Response (200 OK):

{
  "success": true,
  "data": {
    "id": 1310717,
    "feature": "Spot Trading",
    "feature_code": "SPOT_TRADE",
    "method": "Fee Rate",
    "method_code": "FEE_RATE",
    "amount": 0.01,
    "customer_id": "client25",
    "currency": "BTC",
    "pair": "BTCUSD",
    "created_at": "2023-06-07T21:49:22.000Z",
    "updated_at": "2023-06-07T21:49:22.000Z"
  },
  "meta": {
    "timestamp": "2026-01-15T10:30:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
  }
}

curl -X GET "https://api.sandbox.sovera.io/sovx/v1/monetization/settings/{{settingID}}" \
  -H "x-api-key: YOUR_OWNER_API_KEY"

Errors: 401 missing or invalid key · 404 setting not found · 500 server error.

Create Setting

POSThttps://api.sandbox.sovera.io/sovx/v1/monetization/settings

Create a monetization setting. The custody provider assigns the id and returns the full record, which is cached locally. Use pair when a FEE_RATE or SPREAD_ADJUSTMENT should apply to a specific instrument.

Request Body

Field	Type	Required	Description
feature	string	Yes	Feature this setting monetizes. One of `RFQ`, `SPOT_TRADE`, `WITHDRAW`.
method	string	Yes	How the fee is applied. One of `FEE_RATE`, `FEE_FLAT`, `SPREAD_ADJUSTMENT`.
amount	number	Yes	Monetization amount in decimal form (e.g. `0.01` for a 1% fee rate).
pair	string	No	Instrument to scope the setting to (e.g. `BTCUSD`). Used with `FEE_RATE` or `SPREAD_ADJUSTMENT`.

Don't send the account ID — the gateway injects it from your API key and returns it as customer_id in the response.

{
  "feature": "SPOT_TRADE",
  "method": "FEE_RATE",
  "amount": 0.01,
  "pair": "BTCUSD"
}

Success Response (201 Created):

{
  "success": true,
  "data": {
    "id": 1310718,
    "feature": "Spot Trading",
    "feature_code": "SPOT_TRADE",
    "method": "Fee Rate",
    "method_code": "FEE_RATE",
    "amount": 0.01,
    "customer_id": "sovbs-b4cf3af1-d441-407b-918f-54179cd69f83",
    "currency": "BTC",
    "pair": "BTCUSD",
    "created_at": "2026-01-15T10:30:00.000Z",
    "updated_at": "2026-01-15T10:30:00.000Z"
  },
  "meta": {
    "timestamp": "2026-01-15T10:30:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
  }
}

curl -X POST "https://api.sandbox.sovera.io/sovx/v1/monetization/settings" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_OWNER_API_KEY" \
  -d '{
    "feature": "SPOT_TRADE",
    "method": "FEE_RATE",
    "amount": 0.01,
    "pair": "BTCUSD"
  }'

Errors: 400 missing or invalid fields, or feature/method outside the allowed enums · 401 missing or invalid key · 500 server error.

Update Setting

PUThttps://api.sandbox.sovera.io/sovx/v1/monetization/settings/:id

Update an existing monetization setting by its id. Send only the fields you want to change—omitted fields keep their current values. The change is applied at the custody provider and the local cache is refreshed. Returns the full updated record.

Request Body

All fields are optional. Include only the fields you want to change.

Field	Type	Required	Description
feature	string	No	Feature this setting monetizes. One of `RFQ`, `SPOT_TRADE`, `WITHDRAW`.
method	string	No	How the fee is applied. One of `FEE_RATE`, `FEE_FLAT`, `SPREAD_ADJUSTMENT`.
amount	number	No	Monetization amount in decimal form.
pair	string	No	Instrument to scope the setting to (e.g. `BTCUSD`).

Don't send the account ID — the gateway injects it from your API key and returns it as customer_id in the response.

{
  "amount": 0.02
}

Success Response (200 OK):

{
  "success": true,
  "data": {
    "id": 1310718,
    "feature": "Spot Trading",
    "feature_code": "SPOT_TRADE",
    "method": "Fee Rate",
    "method_code": "FEE_RATE",
    "amount": 0.02,
    "customer_id": "sovbs-b4cf3af1-d441-407b-918f-54179cd69f83",
    "currency": "BTC",
    "pair": "BTCUSD",
    "created_at": "2026-01-15T10:30:00.000Z",
    "updated_at": "2026-01-15T12:00:00.000Z"
  },
  "meta": {
    "timestamp": "2026-01-15T12:00:00.000Z",
    "version": "v1",
    "trace_id": "5b8f3a9d-2c7e-4a1b-9f6d-0e3c2b1a4d5f"
  }
}

curl -X PUT "https://api.sandbox.sovera.io/sovx/v1/monetization/settings/{{settingID}}" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_OWNER_API_KEY" \
  -d '{
    "amount": 0.02
  }'

Errors: 400 invalid fields or out-of-range enum · 401 missing or invalid key · 404 setting not found · 500 server error.

Delete Setting

DELETEhttps://api.sandbox.sovera.io/sovx/v1/monetization/settings/:id

Delete a monetization setting by its id. The setting is removed at the custody provider and dropped from the local cache. Once deleted, the fee or spread no longer applies to future activity.

DELETE https://api.sandbox.sovera.io/sovx/v1/monetization/settings/{{settingID}}

Success Response (204 No Content) — empty body, no JSON.

curl -X DELETE "https://api.sandbox.sovera.io/sovx/v1/monetization/settings/{{settingID}}" \
  -H "x-api-key: YOUR_OWNER_API_KEY"

Errors: 401 missing or invalid key · 404 setting not found · 500 server error.

Fees & Monetization

On this page