Create Delegation

Create a spending delegation and return a signed JWT token

curl --request POST \
  --url https://api.sandbox.nevermined.app/api/v1/delegation/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "provider": "stripe",
  "spendingLimitCents": 10000,
  "durationSecs": 604800,
  "currency": "usd",
  "providerPaymentMethodId": "pm_1Abc2Def3Ghi4Jkl",
  "consumerPrompt": "Allow up to USD 50.00 over 5 transactions",
  "assuranceData": {},
  "planId": "123456789",
  "merchantAccountId": "acct_1Abc2Def3Ghi",
  "maxTransactions": 50,
  "apiKeyId": "sk-abc123",
  "allowedRecipients": [
    "0x209693Bc6afc0C5328bA36FaF03C514EF312287C"
  ],
  "organizationWalletId": "orw-abc123"
}
'

import requests

url = "https://api.sandbox.nevermined.app/api/v1/delegation/create"

payload = {
    "provider": "stripe",
    "spendingLimitCents": 10000,
    "durationSecs": 604800,
    "currency": "usd",
    "providerPaymentMethodId": "pm_1Abc2Def3Ghi4Jkl",
    "consumerPrompt": "Allow up to USD 50.00 over 5 transactions",
    "assuranceData": {},
    "planId": "123456789",
    "merchantAccountId": "acct_1Abc2Def3Ghi",
    "maxTransactions": 50,
    "apiKeyId": "sk-abc123",
    "allowedRecipients": ["0x209693Bc6afc0C5328bA36FaF03C514EF312287C"],
    "organizationWalletId": "orw-abc123"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    provider: 'stripe',
    spendingLimitCents: 10000,
    durationSecs: 604800,
    currency: 'usd',
    providerPaymentMethodId: 'pm_1Abc2Def3Ghi4Jkl',
    consumerPrompt: 'Allow up to USD 50.00 over 5 transactions',
    assuranceData: {},
    planId: '123456789',
    merchantAccountId: 'acct_1Abc2Def3Ghi',
    maxTransactions: 50,
    apiKeyId: 'sk-abc123',
    allowedRecipients: ['0x209693Bc6afc0C5328bA36FaF03C514EF312287C'],
    organizationWalletId: 'orw-abc123'
  })
};

fetch('https://api.sandbox.nevermined.app/api/v1/delegation/create', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.nevermined.app/api/v1/delegation/create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'provider' => 'stripe',
    'spendingLimitCents' => 10000,
    'durationSecs' => 604800,
    'currency' => 'usd',
    'providerPaymentMethodId' => 'pm_1Abc2Def3Ghi4Jkl',
    'consumerPrompt' => 'Allow up to USD 50.00 over 5 transactions',
    'assuranceData' => [
        
    ],
    'planId' => '123456789',
    'merchantAccountId' => 'acct_1Abc2Def3Ghi',
    'maxTransactions' => 50,
    'apiKeyId' => 'sk-abc123',
    'allowedRecipients' => [
        '0x209693Bc6afc0C5328bA36FaF03C514EF312287C'
    ],
    'organizationWalletId' => 'orw-abc123'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.nevermined.app/api/v1/delegation/create"

	payload := strings.NewReader("{\n  \"provider\": \"stripe\",\n  \"spendingLimitCents\": 10000,\n  \"durationSecs\": 604800,\n  \"currency\": \"usd\",\n  \"providerPaymentMethodId\": \"pm_1Abc2Def3Ghi4Jkl\",\n  \"consumerPrompt\": \"Allow up to USD 50.00 over 5 transactions\",\n  \"assuranceData\": {},\n  \"planId\": \"123456789\",\n  \"merchantAccountId\": \"acct_1Abc2Def3Ghi\",\n  \"maxTransactions\": 50,\n  \"apiKeyId\": \"sk-abc123\",\n  \"allowedRecipients\": [\n    \"0x209693Bc6afc0C5328bA36FaF03C514EF312287C\"\n  ],\n  \"organizationWalletId\": \"orw-abc123\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sandbox.nevermined.app/api/v1/delegation/create")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"provider\": \"stripe\",\n  \"spendingLimitCents\": 10000,\n  \"durationSecs\": 604800,\n  \"currency\": \"usd\",\n  \"providerPaymentMethodId\": \"pm_1Abc2Def3Ghi4Jkl\",\n  \"consumerPrompt\": \"Allow up to USD 50.00 over 5 transactions\",\n  \"assuranceData\": {},\n  \"planId\": \"123456789\",\n  \"merchantAccountId\": \"acct_1Abc2Def3Ghi\",\n  \"maxTransactions\": 50,\n  \"apiKeyId\": \"sk-abc123\",\n  \"allowedRecipients\": [\n    \"0x209693Bc6afc0C5328bA36FaF03C514EF312287C\"\n  ],\n  \"organizationWalletId\": \"orw-abc123\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.nevermined.app/api/v1/delegation/create")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"provider\": \"stripe\",\n  \"spendingLimitCents\": 10000,\n  \"durationSecs\": 604800,\n  \"currency\": \"usd\",\n  \"providerPaymentMethodId\": \"pm_1Abc2Def3Ghi4Jkl\",\n  \"consumerPrompt\": \"Allow up to USD 50.00 over 5 transactions\",\n  \"assuranceData\": {},\n  \"planId\": \"123456789\",\n  \"merchantAccountId\": \"acct_1Abc2Def3Ghi\",\n  \"maxTransactions\": 50,\n  \"apiKeyId\": \"sk-abc123\",\n  \"allowedRecipients\": [\n    \"0x209693Bc6afc0C5328bA36FaF03C514EF312287C\"\n  ],\n  \"organizationWalletId\": \"orw-abc123\"\n}"

response = http.request(request)
puts response.read_body

{
  "delegationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "delegationToken": "eyJhbGciOiJIUzI1NiIsInR..."
}

POST

delegation

create

Create a spending delegation and return a signed JWT token

curl --request POST \
  --url https://api.sandbox.nevermined.app/api/v1/delegation/create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "provider": "stripe",
  "spendingLimitCents": 10000,
  "durationSecs": 604800,
  "currency": "usd",
  "providerPaymentMethodId": "pm_1Abc2Def3Ghi4Jkl",
  "consumerPrompt": "Allow up to USD 50.00 over 5 transactions",
  "assuranceData": {},
  "planId": "123456789",
  "merchantAccountId": "acct_1Abc2Def3Ghi",
  "maxTransactions": 50,
  "apiKeyId": "sk-abc123",
  "allowedRecipients": [
    "0x209693Bc6afc0C5328bA36FaF03C514EF312287C"
  ],
  "organizationWalletId": "orw-abc123"
}
'

import requests

url = "https://api.sandbox.nevermined.app/api/v1/delegation/create"

payload = {
    "provider": "stripe",
    "spendingLimitCents": 10000,
    "durationSecs": 604800,
    "currency": "usd",
    "providerPaymentMethodId": "pm_1Abc2Def3Ghi4Jkl",
    "consumerPrompt": "Allow up to USD 50.00 over 5 transactions",
    "assuranceData": {},
    "planId": "123456789",
    "merchantAccountId": "acct_1Abc2Def3Ghi",
    "maxTransactions": 50,
    "apiKeyId": "sk-abc123",
    "allowedRecipients": ["0x209693Bc6afc0C5328bA36FaF03C514EF312287C"],
    "organizationWalletId": "orw-abc123"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    provider: 'stripe',
    spendingLimitCents: 10000,
    durationSecs: 604800,
    currency: 'usd',
    providerPaymentMethodId: 'pm_1Abc2Def3Ghi4Jkl',
    consumerPrompt: 'Allow up to USD 50.00 over 5 transactions',
    assuranceData: {},
    planId: '123456789',
    merchantAccountId: 'acct_1Abc2Def3Ghi',
    maxTransactions: 50,
    apiKeyId: 'sk-abc123',
    allowedRecipients: ['0x209693Bc6afc0C5328bA36FaF03C514EF312287C'],
    organizationWalletId: 'orw-abc123'
  })
};

fetch('https://api.sandbox.nevermined.app/api/v1/delegation/create', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.nevermined.app/api/v1/delegation/create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'provider' => 'stripe',
    'spendingLimitCents' => 10000,
    'durationSecs' => 604800,
    'currency' => 'usd',
    'providerPaymentMethodId' => 'pm_1Abc2Def3Ghi4Jkl',
    'consumerPrompt' => 'Allow up to USD 50.00 over 5 transactions',
    'assuranceData' => [
        
    ],
    'planId' => '123456789',
    'merchantAccountId' => 'acct_1Abc2Def3Ghi',
    'maxTransactions' => 50,
    'apiKeyId' => 'sk-abc123',
    'allowedRecipients' => [
        '0x209693Bc6afc0C5328bA36FaF03C514EF312287C'
    ],
    'organizationWalletId' => 'orw-abc123'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.nevermined.app/api/v1/delegation/create"

	payload := strings.NewReader("{\n  \"provider\": \"stripe\",\n  \"spendingLimitCents\": 10000,\n  \"durationSecs\": 604800,\n  \"currency\": \"usd\",\n  \"providerPaymentMethodId\": \"pm_1Abc2Def3Ghi4Jkl\",\n  \"consumerPrompt\": \"Allow up to USD 50.00 over 5 transactions\",\n  \"assuranceData\": {},\n  \"planId\": \"123456789\",\n  \"merchantAccountId\": \"acct_1Abc2Def3Ghi\",\n  \"maxTransactions\": 50,\n  \"apiKeyId\": \"sk-abc123\",\n  \"allowedRecipients\": [\n    \"0x209693Bc6afc0C5328bA36FaF03C514EF312287C\"\n  ],\n  \"organizationWalletId\": \"orw-abc123\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sandbox.nevermined.app/api/v1/delegation/create")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"provider\": \"stripe\",\n  \"spendingLimitCents\": 10000,\n  \"durationSecs\": 604800,\n  \"currency\": \"usd\",\n  \"providerPaymentMethodId\": \"pm_1Abc2Def3Ghi4Jkl\",\n  \"consumerPrompt\": \"Allow up to USD 50.00 over 5 transactions\",\n  \"assuranceData\": {},\n  \"planId\": \"123456789\",\n  \"merchantAccountId\": \"acct_1Abc2Def3Ghi\",\n  \"maxTransactions\": 50,\n  \"apiKeyId\": \"sk-abc123\",\n  \"allowedRecipients\": [\n    \"0x209693Bc6afc0C5328bA36FaF03C514EF312287C\"\n  ],\n  \"organizationWalletId\": \"orw-abc123\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.nevermined.app/api/v1/delegation/create")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"provider\": \"stripe\",\n  \"spendingLimitCents\": 10000,\n  \"durationSecs\": 604800,\n  \"currency\": \"usd\",\n  \"providerPaymentMethodId\": \"pm_1Abc2Def3Ghi4Jkl\",\n  \"consumerPrompt\": \"Allow up to USD 50.00 over 5 transactions\",\n  \"assuranceData\": {},\n  \"planId\": \"123456789\",\n  \"merchantAccountId\": \"acct_1Abc2Def3Ghi\",\n  \"maxTransactions\": 50,\n  \"apiKeyId\": \"sk-abc123\",\n  \"allowedRecipients\": [\n    \"0x209693Bc6afc0C5328bA36FaF03C514EF312287C\"\n  ],\n  \"organizationWalletId\": \"orw-abc123\"\n}"

response = http.request(request)
puts response.read_body

{
  "delegationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "delegationToken": "eyJhbGciOiJIUzI1NiIsInR..."
}

Authorizations

Authorization

string

header

required

Your Nevermined API Key (starts with 'nvm:'). Get one at nevermined.app under Settings > API Keys.

Body

application/json

provider

enum<string>

required

Payment provider type. stripe / braintree / visa / erc4337 select that rail directly. vgs (epic #1958) is a unified VGS-Collect card: a PLAN-AGNOSTIC, portable delegation whose settlement PSP (stripe / braintree) is resolved AT CHARGE TIME from the plan being paid (fiatPaymentProvider), so ONE card can charge ANY PSP (#2082). delegation.provider is persisted as the portable vgs marker (the concrete charge never sees it — the handler derives the real PSP at settle). Requires a portable providerPaymentMethodId (the CRD… cardId, which must carry an active network token); planId is OPTIONAL — pass it only to BIND the delegation to a single plan.

Available options:

stripe,

erc4337,

braintree,

visa,

vgs

Example:

"stripe"

spendingLimitCents

number

required

Maximum spending limit in cents (smallest currency unit)

Example:

10000

durationSecs

number

required

Duration of the delegation in seconds

Example:

604800

currency

enum<string>

required

Currency code (lowercase)

Available options:

usd,

eur,

usdc,

eurc

Example:

"usd"

providerPaymentMethodId

string

Payment-method identifier from the provider. For stripe / braintree this is the saved card; for visa this is the VGS agentic-token id returned by enrollment; for vgs this is the CRD… canonical cardId from the unified VGS-Collect enroll. Required for these providers; ignored for erc4337.

Example:

"pm_1Abc2Def3Ghi4Jkl"

consumerPrompt

string

Visa-only: human-readable approval prompt shown to the user during VGS Agentic Auth device binding. Required when provider=visa.

Example:

"Allow up to USD 50.00 over 5 transactions"

assuranceData

object

Visa-only: opaque assurance payload from the VGS Agentic Auth browser SDK after FIDO/OTP device binding. Required when provider=visa.

planId

string

Plan ID to restrict this delegation to. Optional and plan-agnostic by default (#1534), INCLUDING provider=vgs (#2082): a unified VGS card delegation is plan-agnostic and the settlement PSP is resolved at charge time from the plan being paid, so one card can charge any PSP — pass planId only to BIND it to a single plan. EXCEPT provider=visa (the VGS mandate is merchant-scoped, derived from the plan owner; see BCK.VISA.0015), where it is REQUIRED.

Example:

"123456789"

merchantAccountId

string

Optional merchant Stripe account ID to restrict payments to

Example:

"acct_1Abc2Def3Ghi"

maxTransactions

number

Maximum number of transactions allowed (null = unlimited)

Example:

50

apiKeyId

string

Optional API Key ID (skId) to restrict this delegation to

Example:

"sk-abc123"

allowedRecipients

string[]

erc4337 / Router only: restrict spend to these pay-to addresses — the Router rejects payments to any other recipient. Omit for no recipient restriction.

Example:

[
  "0x209693Bc6afc0C5328bA36FaF03C514EF312287C"
]

organizationWalletId

string

erc4337 / Router only (#2230): fund this delegation from an ORGANIZATION wallet instead of the caller's own wallet. The caller must be an admin of the wallet's org. Spend is always capped by the SPENDING member's group budget (the wallet must be shared with the member's group).

Example:

"orw-abc123"

Response

The created delegation

delegationId

string

required

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

delegationToken

string | null

Signed JWT for fiat-backed delegations (stripe/braintree). Omitted for crypto (erc4337) flows where the signed delegation is held client-side.

Example:

"eyJhbGciOiJIUzI1NiIsInR..."

Overview

Versioning

API Errors

Agents

Plans

Access

x402

Credits

Delegation

Payment Methods

Authorizations

Body

Response