Admin Fee Subsidies
Manage per-agent fee discounts. Requires an admin API key (pva_ prefix).
Auth: Authorization: Bearer pva_...
Base URL: https://provenonce.io
Subsidies apply a discount (in basis points) to a specific fee type for a specific agent. The discount is applied on top of any fee configuration or environment-level defaults. A COGS floor (default 5,000 lamports) prevents discounts from going below cost.
POST /api/v1/admin/agent/subsidy
Create or update a subsidy for an agent.
curl -X POST https://provenonce.io/api/v1/admin/agent/subsidy \
-H "Content-Type: application/json" \
-H "Authorization: Bearer pva_..." \
-d '{
"agent_hash": "0xfd752396...",
"fee_type": "heartbeat",
"discount_bps": 5000,
"reason": "Early adopter program",
"floor_lamports": 5000,
"valid_until": "2026-06-01T00:00:00.000Z"
}'Request body
| Field | Type | Required | Description |
|---|---|---|---|
agent_hash | string | Yes | Target agent (0x + 64 hex) |
fee_type | string | Yes | sigil, heartbeat, or reissuance |
discount_bps | number | Yes | Discount in basis points (1-10000). 5000 = 50% off |
reason | string | Yes | Reason for the subsidy |
floor_lamports | number | No | Minimum fee in lamports (default 5000) |
valid_until | string | No | ISO 8601 expiry date |
Response
{
"ok": true,
"subsidy": {
"agent_hash": "0xfd752396...",
"fee_type": "heartbeat",
"discount_bps": 5000,
"floor_lamports": 5000,
"reason": "Early adopter program",
"valid_until": "2026-06-01T00:00:00.000Z"
}
}DELETE /api/v1/admin/agent/subsidy
Remove a subsidy.
curl -X DELETE https://provenonce.io/api/v1/admin/agent/subsidy \
-H "Content-Type: application/json" \
-H "Authorization: Bearer pva_..." \
-d '{
"agent_hash": "0xfd752396...",
"fee_type": "heartbeat"
}'Response
{
"ok": true,
"deleted": true,
"agent_hash": "0xfd752396...",
"fee_type": "heartbeat"
}Fee hierarchy
Fees are resolved in priority order:
- Per-agent subsidy (this endpoint)
- Fee configuration table
- Environment variable overrides
- Hardcoded defaults
Error responses
| Status | Body | Cause |
|---|---|---|
| 400 | {"error": "...", "code": "SUBSIDY_INVALID"} | Invalid fee_type or discount_bps |
| 401 | {"error": "...", "code": "AUTH_MISSING"} | Missing pva_ admin key |
| 401 | {"error": "...", "code": "AUTH_INVALID"} | Invalid or expired admin key |
| 404 | {"error": "...", "code": "AGENT_NOT_FOUND"} | Agent not found |
| 404 | {"error": "...", "code": "SUBSIDY_NOT_FOUND"} | No subsidy found (DELETE) |
| 429 | {"error": "...", "code": "RATE_LIMITED"} | Rate limit exceeded |