GET /api/policies — List and Get Spending Policies

Fetch all active spending policies on your account. A spending policy defines the guardrails — daily budgets, per-transaction caps, manual approval thresholds, allowed assets, allowed actions, and session lifetimes — that govern what an AI session is permitted to do. Use this endpoint to inspect your existing policies before attaching one to a new session, or to audit your current configuration.

List all policies

Endpoint

GET /api/policies

Authentication

All requests must include a valid bearer token in the Authorization header, or a pay3_session cookie obtained during wallet authentication.

Authorization: Bearer <token>

Response

Returns an array of policy objects, ordered newest-first. Soft-deleted policies (isActive: false) are excluded.

Response fields

string

required

Unique UUID for this policy.

string

required

Display name you assigned when the policy was created.

string

required

The preset template this policy was created from. One of:

CONSERVATIVE — $100/day, $20/tx, approval above $15, 24-hour sessions
BALANCED — $500/day, $100/tx, approval above $250, 7-day sessions
DEFI — $1,000/day, $250/tx, approval above $500, 7-day sessions
CUSTOM — fully user-defined limits

string

required

Maximum total spend allowed per calendar day, in USD. Returned as a decimal string.

string

Optional monthly spend cap in USD as a decimal string. null if no monthly limit is configured.

string

required

Maximum amount allowed in a single transaction, in USD. Transactions exceeding this value are rejected outright.

string

required

Transactions above this USD amount (but at or below perTransactionMax) are sent to the approval queue rather than executed automatically.

number

required

How long sessions created with this policy remain active, in hours.

array

required

List of asset tickers the AI is permitted to transact with, e.g. ["USDC", "XLM"]. Transactions involving any other asset are rejected.

array

required

List of actions this policy permits the AI to perform. Possible values:

CHECK_BALANCE — read wallet and smart account balances
TRANSFER — send assets to a recipient
VIEW_TRANSACTION_HISTORY — list past transactions

array

required

Array of contact UUIDs from your Pay3 address book. When non-empty, the AI may only send funds to these contacts. An empty array means no recipient restriction is enforced.

number

Maximum number of transactions the AI may submit per minute under this policy. null if no rate limit is configured.

boolean

required

Whether this policy is currently active. Only active policies are returned by this endpoint.

string

required

ISO 8601 timestamp when the policy was created.

string

required

ISO 8601 timestamp when the policy was last modified.

Example request

curl https://api.pay3.dev/api/policies \
  -H "Authorization: Bearer <token>"

Example response

[
  {
    "id": "f9e8d7c6-dcba-4321-fedc-ba9876543210",
    "name": "My Custom Policy",
    "preset": "CUSTOM",
    "dailyBudget": "250.0000000",
    "monthlyBudget": null,
    "perTransactionMax": "75.0000000",
    "manualApprovalThreshold": "50.0000000",
    "sessionDurationHours": 72,
    "allowedAssets": ["USDC", "XLM"],
    "allowedActions": ["CHECK_BALANCE", "TRANSFER", "VIEW_TRANSACTION_HISTORY"],
    "allowedRecipientIds": [],
    "rateLimitPerMinute": null,
    "isActive": true,
    "createdAt": "2025-07-01T10:00:00.000Z",
    "updatedAt": "2025-07-01T10:00:00.000Z"
  },
  {
    "id": "c2d3e4f5-0000-1111-2222-333344445555",
    "name": "Balanced Preset",
    "preset": "BALANCED",
    "dailyBudget": "500.0000000",
    "monthlyBudget": null,
    "perTransactionMax": "100.0000000",
    "manualApprovalThreshold": "250.0000000",
    "sessionDurationHours": 168,
    "allowedAssets": ["USDC", "XLM"],
    "allowedActions": ["CHECK_BALANCE", "TRANSFER", "VIEW_TRANSACTION_HISTORY"],
    "allowedRecipientIds": [],
    "rateLimitPerMinute": null,
    "isActive": true,
    "createdAt": "2025-06-20T08:00:00.000Z",
    "updatedAt": "2025-06-20T08:00:00.000Z"
  }
]

Get a single policy

Retrieve one policy by its UUID. Useful when you need to verify the exact configuration before attaching the policy to a new AI session.

Endpoint

GET /api/policies/:id

Authentication

Authorization: Bearer <token>

Path parameters

string

required

The UUID of the policy to retrieve.

Response

Returns a single policy object with the same fields as the list response above. Returns 404 Not Found if the policy does not exist or does not belong to your account.

Error responses

Status	Meaning
`400 Bad Request`	The provided `id` is not a valid UUID.
`401 Unauthorized`	Missing or invalid bearer token.
`404 Not Found`	No active policy exists for the given `id` on your account.

Example request

curl https://api.pay3.dev/api/policies/f9e8d7c6-dcba-4321-fedc-ba9876543210 \
  -H "Authorization: Bearer <token>"

Example response

{
  "id": "f9e8d7c6-dcba-4321-fedc-ba9876543210",
  "name": "My Custom Policy",
  "preset": "CUSTOM",
  "dailyBudget": "250.0000000",
  "monthlyBudget": null,
  "perTransactionMax": "75.0000000",
  "manualApprovalThreshold": "50.0000000",
  "sessionDurationHours": 72,
  "allowedAssets": ["USDC", "XLM"],
  "allowedActions": ["CHECK_BALANCE", "TRANSFER", "VIEW_TRANSACTION_HISTORY"],
  "allowedRecipientIds": ["b5c6d7e8-1234-5678-abcd-ef0123456789"],
  "rateLimitPerMinute": 10,
  "isActive": true,
  "createdAt": "2025-07-01T10:00:00.000Z",
  "updatedAt": "2025-07-01T10:00:00.000Z"
}

Authentication

Wallet & Accounts

Sessions & Policies

Transactions

Contacts & Analytics

GET /api/policies — List and Get Spending Policies

List all policies

Endpoint

Authentication

Response

Response fields

Example request

Example response

Get a single policy

Endpoint

Authentication

Path parameters

Response

Error responses

Example request

Example response

​List all policies

​Endpoint

​Authentication

​Response

​Response fields

​Example request

​Example response

​Get a single policy

​Endpoint

​Authentication

​Path parameters

​Response

​Error responses

​Example request

​Example response

List all policies

Endpoint

Authentication

Response

Response fields

Example request

Example response

Get a single policy

Endpoint

Authentication

Path parameters

Response

Error responses

Example request

Example response