PolicyService

Create Subaccount Policy

Create a new sub-account policy template for the caller account or workspace.

Method

POST

Path

/v1/auth/policies/subaccounts

Visibility

Authentication required

Authentication

Session token

MFA Requirement

Fresh step-up required

POST

/v1/auth/policies/subaccounts

Request

Testnet

curl --request POST \ \
  --url 'https://api.testnet.polyester.com/v1/auth/policies/subaccounts' \
  --header 'Accept: */*' \
  --header 'X-API-KEY-ID: YOUR_API_KEY_ID' \
  --header 'X-API-TIMESTAMP: YOUR_API_TIMESTAMP' \
  --header 'X-API-SIGNATURE: YOUR_API_SIGNATURE' \
  --header 'Content-Type: application/json' \
  --data '{
  "policy": {
    "actions": [
      "TRADE_SPOT"
    ],
    "description": "Example configuration for the API playground.",
    "expiresAt": "2025-01-01T00:00:00Z",
    "locked": false,
    "maxOpenOrders": 1,
    "maxOrderNotional": "12345",
    "name": "value",
    "reviewAt": "2025-01-01T00:00:00Z",
    "spotMarketScope": "ALL",
    "spotMarkets": [
      {
        "symbolId": 1
      }
    ],
    "tradingHalted": false
  },
  "subaccountId": "6789012345678"
}'

Responses

{
  "policy": {
    "actions": [
      "TRADE_SPOT"
    ],
    "createdAt": "2025-01-01T00:00:00Z",
    "description": "Allow spot trading for selected markets.",
    "expiresAt": "2025-01-01T00:00:00Z",
    "id": "7gQY8okwBT",
    "isTemplate": false,
    "locked": false,
    "maxOpenOrders": 1,
    "maxOrderNotional": "12345",
    "name": "Market Maker Policy",
    "reviewAt": "2025-01-01T00:00:00Z",
    "revision": "1",
    "sourceTemplateId": "8gnKtjkL5A",
    "spotMarketScope": "ALL",
    "spotMarkets": [
      {
        "symbolId": 1
      }
    ],
    "tradingHalted": false,
    "updatedAt": "2025-01-01T00:00:00Z"
  }
}

policy string required

Complete mutable policy configuration.

subaccountId string (int64)

Optional target sub-account to attach atomically after creation.

17 fields

id string (fixed64)

Policy identifier (opaque ID).

Example 7gQY8okwBT

name string

Human-readable policy name.

Example Market Maker Policy

description string

Optional policy description for dashboards and audits.

Example Allow spot trading for selected markets.

1 field

spotMarketScope enum

Market-level scope for spot markets. When ALL, spot_markets is returned for display only and is not enforced.

ALL ALLOWLIST

Example ALL

actions enum[]

Effective high-level actions enabled for the sub-account. Mandatory read-only actions are always included.

TRADE_SPOT INTERNAL_TRANSFER EXTERNAL_WITHDRAW READ_BALANCES READ_SPOT READ_INTERNAL_TRANSFERS READ_ADDRESS_BOOK MANAGE_ADDRESS_BOOK

Example ["TRADE_SPOT"]

isTemplate boolean

True if this policy is a reusable template; false if it is a per-sub-account instance.

Example false

sourceTemplateId string (fixed64)

Optional source template this policy was copied from (opaque ID). This is audit metadata only and does not imply live linkage.

Example 8gnKtjkL5A

maxOrderNotional string (uint64)

Maximum notional size allowed for any single order on this sub-account, expressed in canonical quote microunits (one unit is 0.000001 USDT). A value of 0 means "no explicit cap".

Example 12345

maxOpenOrders integer (int32)

Maximum number of resting orders allowed on this sub-account at any time. A value of 0 means "no explicit cap".

Example 1

tradingHalted boolean

When true, new orders and exposure-increasing order or trigger changes are rejected regardless of other settings. Existing orders and triggers may still be canceled or paused by an otherwise authorized caller.

Example false

locked boolean

When true, this policy is write-protected and requires an elevated approval flow to modify it.

Example false

reviewAt string (date-time)

Optional review time in UTC. This is governance metadata and does not automatically disable the policy.

Example 2025-01-01T00:00:00Z

expiresAt string (date-time)

Optional expiry time in UTC. This is governance metadata and does not automatically disable the policy.

Example 2025-01-01T00:00:00Z

createdAt string (date-time)

Creation time in UTC.

Example 2025-01-01T00:00:00Z

updatedAt string (date-time)

Last update time in UTC.

Example 2025-01-01T00:00:00Z

revision string (uint64)

Monotonic resource revision used for conditional updates.

Example 1

Possible errors: 5

Key	Status	Error	When
unauthenticated	401	Unauthenticated	Authentication required.
permission-denied	403	Permission Denied	Permission denied.
invalid-argument	400	Invalid Argument	Invalid argument.
not-found	404	Not Found	Not found.
unavailable	503	Unavailable	Service unavailable.

POST

/v1/auth/policies/subaccounts

Request

Testnet

curl --request POST \ \
  --url 'https://api.testnet.polyester.com/v1/auth/policies/subaccounts' \
  --header 'Accept: */*' \
  --header 'X-API-KEY-ID: YOUR_API_KEY_ID' \
  --header 'X-API-TIMESTAMP: YOUR_API_TIMESTAMP' \
  --header 'X-API-SIGNATURE: YOUR_API_SIGNATURE' \
  --header 'Content-Type: application/json' \
  --data '{
  "policy": {
    "actions": [
      "TRADE_SPOT"
    ],
    "description": "Example configuration for the API playground.",
    "expiresAt": "2025-01-01T00:00:00Z",
    "locked": false,
    "maxOpenOrders": 1,
    "maxOrderNotional": "12345",
    "name": "value",
    "reviewAt": "2025-01-01T00:00:00Z",
    "spotMarketScope": "ALL",
    "spotMarkets": [
      {
        "symbolId": 1
      }
    ],
    "tradingHalted": false
  },
  "subaccountId": "6789012345678"
}'

Responses

{
  "policy": {
    "actions": [
      "TRADE_SPOT"
    ],
    "createdAt": "2025-01-01T00:00:00Z",
    "description": "Allow spot trading for selected markets.",
    "expiresAt": "2025-01-01T00:00:00Z",
    "id": "7gQY8okwBT",
    "isTemplate": false,
    "locked": false,
    "maxOpenOrders": 1,
    "maxOrderNotional": "12345",
    "name": "Market Maker Policy",
    "reviewAt": "2025-01-01T00:00:00Z",
    "revision": "1",
    "sourceTemplateId": "8gnKtjkL5A",
    "spotMarketScope": "ALL",
    "spotMarkets": [
      {
        "symbolId": 1
      }
    ],
    "tradingHalted": false,
    "updatedAt": "2025-01-01T00:00:00Z"
  }
}

Polyester is best experienced on desktop.

Request

Responses