Spending Policy API — MPPPal Docs

Operator-only endpoint. Policy endpoints require an operator API key. Agent-scoped keys return 403 Forbidden.

Policy object

Field	Type	Default	Description
`max_single_transfer`	number \| null	`null`	Maximum USDC per transfer or per-request MPP charge. `null` = no limit.
`max_daily_spend`	number \| null	`null`	Maximum USDC in a rolling 24-hour window across all transfers and session settlements. `null` = no limit.
`allowed_counterparties`	string[] \| null	`null`	Allowlist of Solana addresses or MPPPal account IDs. If set, all other recipients are blocked. `null` = all addresses allowed.
`categories`	string[] \| null	`null`	Allowlist of spend categories. MPP providers declare a category in their payment challenge; transfers without a matching category are rejected. `null` = all categories allowed. Example values: `"inference"`, `"data"`, `"search"`, `"agent-reward"`.
`require_memo`	boolean	`false`	If `true`, transfers without a `memo` field are rejected.
`escalation_threshold`	number \| null	`null`	If set, transfers at or above this USDC amount fire an `escalation.required` webhook event before executing. Allows human-in-the-loop approval for high-value payments. `null` = disabled.
`paused`	boolean	`false`	If `true`, all outgoing transfers are blocked immediately.

GET /v1/accounts/:id/policy

Get the current spending policy for an account.

Response — 200 OK

json

{
  "account_id": "acct_01j8k4x9p2qrst7yz",
  "max_single_transfer": 500,
  "max_daily_spend": 2000,
  "allowed_counterparties": [
    "9xTz4KqR8mYvPn3SdFgHj6WbCeAuLo1XkQi5NtZpMwV",
    "acct_03x1m7p9k2qrst4ab"
  ],
  "categories": ["inference", "data"],
  "require_memo": true,
  "escalation_threshold": 200,
  "paused": false,
  "updated_at": "2024-01-15T09:00:00Z"
}

PUT /v1/accounts/:id/policy

Update the spending policy for an account. This is a full replacement — omitted fields revert to their defaults.

On-chain update. Policy changes are written to the on-chain PDA state via the MPPPal Solana program. The change takes effect at the next transfer request, not retroactively.

Request body

json

{
  "max_single_transfer": 500,
  "max_daily_spend": 2000,
  "allowed_counterparties": [
    "9xTz4KqR8mYvPn3SdFgHj6WbCeAuLo1XkQi5NtZpMwV"
  ],
  "categories": ["inference", "data"],
  "require_memo": true,
  "escalation_threshold": 200,
  "paused": false
}

Pausing an account

To immediately halt all transfers from an account, send a partial update with only paused: true:

bash

curl -X PUT https://api.mpppal.com/v1/accounts/acct_01j8k4x9p2qrst7yz/policy \
  -H "Authorization: Bearer $MPPPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"paused": true}'

Note: when sending a partial update, only the fields you include are changed. Other policy fields are preserved.