Spending Controls

Delegate keys let you grant machine-to-machine access with configurable spending limits. Perfect for bots, agents, and automated workflows that need to settle payments without a user session.

What are delegate keys?

A delegate key is a scoped API key that can settle payments on behalf of your account, subject to spending limits you define. Unlike your main API key, delegates have built-in guardrails.

Per-transaction cap

Maximum amount a single payment can be.

Daily amount limit

Total USDC the key can spend per day.

Daily tx count

Maximum number of transactions per day.

Create a delegate

POST /v1/delegates

Creates a new delegate key with the specified spending limits. The API key is returned once — store it securely.

create-delegate.js

// Create a delegate key with spending limits
const res = await fetch('https://api.apisettle.com/v1/delegates', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${JWT}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Production Bot',
    max_amount_per_tx: '5000000',     // $5.00 per transaction
    daily_amount_limit: '100000000',   // $100.00 per day
    daily_tx_limit: 500,               // 500 transactions per day
  }),
})

const delegate = await res.json()
// {
//   id: "del_...",
//   api_key: "dk_test_m3n8...",  ← save this, shown only once
//   name: "Production Bot",
//   max_amount_per_tx: "5000000",
//   daily_amount_limit: "100000000",
//   daily_tx_limit: 500
// }

Using delegate keys

Delegate keys work as Bearer tokens, just like service keys. Use them wherever you'd use a JWT for settling payments.

use-delegate.js

// Use the delegate key to settle payments (M2M)
const res = await fetch('https://api.apisettle.com/v1/settle', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer dk_test_m3n8...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    quote_token: quoteToken,
    payment_attempt_id: 'bot_run_2026_03_27_001',
  }),
})
// Works exactly like JWT auth, but with spending limits enforced

Update spending limits

PATCH /v1/delegates/:id

Adjust limits on the fly without creating a new key. Changes take effect immediately.

update-delegate.js

// Update spending limits on an existing delegate
const res = await fetch(
  `https://api.apisettle.com/v1/delegates/${delegateId}`,
  {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${JWT}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      daily_amount_limit: '200000000',  // raise to $200/day
    }),
  },
)

Check usage

GET /v1/delegates/me

Query current spending against limits. Useful for dashboards or pre-flight checks before settling.

check-usage.js

// Check current delegate usage
const res = await fetch('https://api.apisettle.com/v1/delegates/me', {
  headers: { 'Authorization': 'Bearer dk_test_m3n8...' },
})

const usage = await res.json()
// {
//   daily_amount_used: "45000000",
//   daily_amount_limit: "100000000",
//   daily_tx_used: 23,
//   daily_tx_limit: 500
// }

Key management

Action	Endpoint	Notes
List delegates	GET /delegates	Returns all delegates for your account.
Rotate key	POST /delegates/:id/key/rotate	Both keys work during grace period.
Reveal key	POST /delegates/:id/key/reveal	Sends one-time reveal link via email.
Revoke delegate	DELETE /delegates/:id	Immediately disables the key.

When to use delegates

Automated agents

Give each agent its own delegate key with a daily budget. If an agent misbehaves, revoke its key without affecting others.

CI/CD pipelines

Use a delegate key for test environments with low limits. Your production key stays separate with its own budget.

Multi-service architectures

Assign a delegate to each microservice. Track spending per service and enforce independent limits.

Refunds API Reference