Request an agent top-up approval

Requests Link approval to credit an owned agent. amountUsdCents is an integer 50–100000; reason must be 100–2000 chars. Optional intentId binds the top-up to a retained service intent. Agent tokens may only top up themselves (403 agent_mismatch). Typically invoked automatically by the gateway for retained intents.

POST/v1/payments/topups

Authorization

AuthorizationBearer token (JWT) · headerrequired

Clerk human owner session JWT; iss must equal the configured Clerk issuer and the identity must be a human (not agent) owner with a verified email.

AuthorizationBearer token (JWT) · headerrequired

Verified AgentID agent JWT (iss https://auth.agentid.com) or an agentsub OAuth access token (typ at+jwt, iss https://api.agentsub.dev, scope agentsub:agent). The agent's human owner must exist in Clerk with the same verified email.

AuthorizationOAuth2 access token · headerrequired

Scopes:agentsub:owner

Header parameters

Idempotency-Keystringrequired

Required only where this parameter is listed. Same payload/key recovers prior operation; secret replays omit plaintext.

matches ^[A-Za-z0-9._:-]{1,200}$

Request body

requiredapplication/json

agentIdstringrequired

min length 1 · max length 200

amountUsdCentsintegerrequired

min 50 · max 100000

reasonstringrequired

min length 100 · max length 2000

intentIdstring

min length 1 · max length 200

Responses

200

Top-up request (approval pending)

idstring

agentIdstring

amountUsdCentsinteger

statusstring

kindstring

Allowed:checkoutlink

approvalUrlstring<uri>

checkoutUrlstring<uri>

nextActionobject

Show properties

resolutionstring

actionUrlstring<uri>

intentIdstring

400

invalid_input or idempotency_required

codestringrequired

Allowed:owner_requiredagent_mismatchidempotency_requiredinvalid_inputstripe_signature_requiredpayment_unavailable

statusintegerrequired

403

agent_mismatch or owner_required

codestringrequired

Allowed:owner_requiredagent_mismatchidempotency_requiredinvalid_inputstripe_signature_requiredpayment_unavailable

statusintegerrequired

503

payment_unavailable

codestringrequired

Allowed:owner_requiredagent_mismatchidempotency_requiredinvalid_inputstripe_signature_requiredpayment_unavailable

statusintegerrequired

Request

curl -X POST 'https://api.agentsub.dev/v1/payments/topups' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Idempotency-Key: string' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "agentId": "string",
  "amountUsdCents": 50,
  "reason": "stringstringstringstringstringstringstringstringstringstringstringstringstringstringstringstringstri",
  "intentId": "string"
}'

const response = await fetch("https://api.agentsub.dev/v1/payments/topups", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Idempotency-Key": "string",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"agentId\": \"string\",\n  \"amountUsdCents\": 50,\n  \"reason\": \"stringstringstringstringstringstringstringstringstringstringstringstringstringstringstringstringstri\",\n  \"intentId\": \"string\"\n}"
});

import requests

response = requests.post(
    "https://api.agentsub.dev/v1/payments/topups",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Idempotency-Key": "string",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"agentId\": \"string\",\n  \"amountUsdCents\": 50,\n  \"reason\": \"stringstringstringstringstringstringstringstringstringstringstringstringstringstringstringstringstri\",\n  \"intentId\": \"string\"\n}",
)

Response

{
  "id": "string",
  "agentId": "string",
  "amountUsdCents": 0,
  "status": "string",
  "kind": "checkout",
  "approvalUrl": "http://example.com",
  "checkoutUrl": "http://example.com",
  "nextAction": {
    "resolution": "string",
    "actionUrl": "http://example.com"
  },
  "intentId": "string"
}

{
  "code": "owner_required",
  "status": 0
}

{
  "code": "owner_required",
  "status": 0
}

{
  "code": "owner_required",
  "status": 0
}