Delegation Selection

Documentation Index

Fetch the complete documentation index at: https://docs.nevermined.app/llms.txt

Use this file to discover all available pages before exploring further.

​

The Problem

​

Three-Tier Resolution

const token = await payments.x402.getX402AccessToken(
  'plan_abc123',
  undefined, // agentId — pass when the plan has multiple agents
  {
    delegationConfig: {
      delegationId: 'deleg-8f14e45f-ce34-4797-b88e-968374b0d4b6',
    },
  },
)

from payments_py.x402 import DelegationConfig, X402TokenOptions

token = payments.x402.get_x402_access_token(
    plan_id="plan_abc123",
    token_options=X402TokenOptions(
        delegation_config=DelegationConfig(
            delegation_id="deleg-8f14e45f-ce34-4797-b88e-968374b0d4b6",
        ),
    ),
)

​

Decision Flowchart

SDK / CLI requests an x402 access token
  |
  |- delegationId in delegationConfig?
  |   |- YES -> Use that delegation (validate ownership, status, budget, usage, expiry)
  |   |- NO  -> Continue to auto-resolution (Stripe / Braintree only)
  |
  |- Collect all user's delegations across all cards
  |   |- Key-linked: delegation.apiKeyId === current key's skId
  |   |- Unlinked: delegation.apiKeyId is null
  |
  |- Filter each group: Active, not expired, remaining budget > 0, remaining transactions > 0
  |
  |- Key-linked delegations found?
  |   |- Exactly 1 -> Use it
  |   |- Multiple  -> Error: "Multiple active delegations found"
  |   |- None      -> Fall through to unlinked
  |
  |- Unlinked delegations found?
      |- Exactly 1 -> Use it
      |- Multiple  -> Error: "Multiple active delegations found"
      |- None      -> Error: "No active delegation found"

​

When to Use Each Mode

​

Linking an API Key

​

When Creating

​

When Updating

​

Error Handling

​

Multiple Delegations Found

"Multiple active delegations found.
 Pass a delegationId in delegationConfig, or link a delegation to your API key."

​

No Active Delegation Found

"No active delegation found (check remaining budget, expiry, status, and key restrictions)"

• All delegations are exhausted (amountSpentCents >= spendingLimitCents or transactionCount >= maxTransactions)
• All delegations have expired (createdAt + durationSecs in the past)
• Delegations are linked to a different API key

​

Delegation Linked to Different Key

"This delegation is linked to a different API key"

​

API Reference

​

Generate Access Token

POST /api/v1/x402/access-token
Authorization: Bearer <NVM_API_KEY>
Content-Type: application/json

{
  "planId": "plan_abc123",
  "agentId": "80918427023170428029540261117198154464497879145267720259488529685089104529015",
  "delegationConfig": {
    "delegationId": "deleg-8f14e45f-ce34-4797-b88e-968374b0d4b6"
  }
}

{
  "accessToken": "eyJ4NDAyVmVyc2lvbiI6Mi...",
  "permissionHash": "0x1a2b3c..."
}

​

Best Practices

1. Start simple. If you have one delegation, you don’t need to link API keys or pass explicit IDs. Just create the delegation and call the API.
2. Link keys for production. When you add a second delegation, link each API key to a specific delegation. This gives you deterministic routing without code changes.
3. Use explicit IDs for Visa or for complex setups. Visa delegations require delegationId in delegationConfig. The same pattern is useful when an agent works with multiple delegations dynamically (e.g., different delegations for different pricing tiers).
4. Monitor usage. Check amountSpentCents vs spendingLimitCents and transactionCount vs maxTransactions to know when delegations are close to exhaustion. Create new ones before the old ones run out.
5. Set reasonable expiration times. Don’t create delegations that last indefinitely. Set durationSecs aligned with your billing cycles. For Visa, the assuranceData ceremony scales with the duration shown in the approval prompt — keep it short for higher-trust use cases.