curl -X PUT "https://win.oneshotagent.com/v1/agents/me/budgets" \
-H "X-Agent-ID: 0xYourWalletAddress" \
-H "x-agent-proof: <base64 signed proof, scope=write>" \
-H "Content-Type: application/json" \
-d '{"daily": 50, "per_transaction": 5, "alert_at": 0.8, "alert_email": "[email protected]"}'
const agent = await OneShot.create({
cdp: true,
budgets: { daily: 50, perTransaction: 5, alertAt: 0.8, pauseAt: 1.0 },
alerts: { email: "[email protected]" },
});
client = OneShotClient(
"0x...",
budgets={"daily": 50, "per_transaction": 5, "alert_at": 0.8},
alert_email="[email protected]",
)
curl -X PUT "https://win.oneshotagent.com/v1/agents/me/budgets" \
-H "X-Agent-ID: 0x..." -H "x-agent-proof: <proof>" \
-H "Content-Type: application/json" \
-d '{"daily": null}'
{
"success": true,
"data": {
"daily_usdc": 50,
"per_transaction_usdc": 5,
"alert_at": 0.8,
"pause_at": 1
}
}
Budgets
Set Budget
Set, adjust, or clear the agent’s spend budget
PUT
/
v1
/
agents
/
me
/
budgets
curl -X PUT "https://win.oneshotagent.com/v1/agents/me/budgets" \
-H "X-Agent-ID: 0xYourWalletAddress" \
-H "x-agent-proof: <base64 signed proof, scope=write>" \
-H "Content-Type: application/json" \
-d '{"daily": 50, "per_transaction": 5, "alert_at": 0.8, "alert_email": "[email protected]"}'
const agent = await OneShot.create({
cdp: true,
budgets: { daily: 50, perTransaction: 5, alertAt: 0.8, pauseAt: 1.0 },
alerts: { email: "[email protected]" },
});
client = OneShotClient(
"0x...",
budgets={"daily": 50, "per_transaction": 5, "alert_at": 0.8},
alert_email="[email protected]",
)
curl -X PUT "https://win.oneshotagent.com/v1/agents/me/budgets" \
-H "X-Agent-ID: 0x..." -H "x-agent-proof: <proof>" \
-H "Content-Type: application/json" \
-d '{"daily": null}'
{
"success": true,
"data": {
"daily_usdc": 50,
"per_transaction_usdc": 5,
"alert_at": 0.8,
"pause_at": 1
}
}
Creates or updates the agent’s budget. Applies from the next paid call.
Every field is tri-state: an absent key keeps the stored value,
Strings with only a numeric prefix (
null clears it, and a value sets it. A partial update, such as raising only daily, leaves the other caps unchanged. alert_at and pause_at always have a value, so null resets them to the default (0.8 / 1.0).
Authentication
X-Agent-ID plus a signed x-agent-proof with scope: "write" (required). See Spend Budgets.
You rarely call this directly. Pass
budgets to the SDK client and it syncs once, before the first paid call. This works for a new wallet that has never made a call (the endpoint registers it). If the sync fails, the SDK refuses the paid call (BudgetSyncError) instead of running without a budget.Body
number | null
Max USDC per UTC day. Must be
> 0, or null to clear.number | null
Max USDC per call. Must be
> 0, or null to clear.number | null
default:"0.8"
Fraction of
daily in (0, 1] that fires a budget_warning notification. null resets to 0.8.number | null
default:"1.0"
Fraction of
daily in (0, 1] at which paid calls are rejected with 403 budget_exceeded. null resets to 1.0.string | null
Email for budget alerts, alongside in-app notifications.
null to clear."5oops") are rejected with 400 invalid_budget.
curl -X PUT "https://win.oneshotagent.com/v1/agents/me/budgets" \
-H "X-Agent-ID: 0xYourWalletAddress" \
-H "x-agent-proof: <base64 signed proof, scope=write>" \
-H "Content-Type: application/json" \
-d '{"daily": 50, "per_transaction": 5, "alert_at": 0.8, "alert_email": "[email protected]"}'
const agent = await OneShot.create({
cdp: true,
budgets: { daily: 50, perTransaction: 5, alertAt: 0.8, pauseAt: 1.0 },
alerts: { email: "[email protected]" },
});
client = OneShotClient(
"0x...",
budgets={"daily": 50, "per_transaction": 5, "alert_at": 0.8},
alert_email="[email protected]",
)
curl -X PUT "https://win.oneshotagent.com/v1/agents/me/budgets" \
-H "X-Agent-ID: 0x..." -H "x-agent-proof: <proof>" \
-H "Content-Type: application/json" \
-d '{"daily": null}'
{
"success": true,
"data": {
"daily_usdc": 50,
"per_transaction_usdc": 5,
"alert_at": 0.8,
"pause_at": 1
}
}
Errors
| Status | error | Meaning |
|---|---|---|
400 | invalid_budget | A field is out of range or not numeric |
401 | proof_required | Missing or invalid x-agent-proof |
500 | alert_email_update_failed | Budget saved but alert_email was not; retry |