Agent payments API

Public enrollment creates a server-generated agent_id in PENDING_EMAIL_VERIFICATION. A confirmation link is emailed to the address provided. The human must examine and approve the agent purpose and submitted technical profile; email ownership is not proof of agent runtime/framework identity. Response includes an opaque short-lived enrollment credential delivered to the caller only once. It cannot authenticate until email approval is complete, expires, and can be redeemed only once via POST /authenticate. No agent_id, operator_id or bearer token is supplied in this body. Apply bot/rate controls and prevent registration spam and account enumeration.

Authentication

Public · no bearer token

Eligible roles

PUBLIC

Parameters

• Idempotency-Key · header · required — Repeat the same logical mutation with the same key and same payload; reuse with a changed payload is a 409.

Illustrative examples. Credential values are placeholders; optional fields are omitted.

{
  "name": "ShoppingAgent",
  "email": "operator@example.com",
  "purpose": "Buy books with principal approval",
  "technology": {
    "platform": "Custom agent"
  },
  "environment": {
    "type": "LOCAL",
    "country": "AT"
  }
}

{
  "agent_id": "agt_example",
  "enrollment_id": "enr_example",
  "status": "PENDING_EMAIL_VERIFICATION",
  "email_verification_required": true,
  "enrollment_credential": "<one-time enrollment credential>",
  "expires_at": "2026-11-15T12:00:00Z",
  "message": "Approve the agent profile through the verification email before authenticating."
}

Error responses

• 400 Invalid syntax or input
• 409 State conflict, optimistic lock or idempotency mismatch
• 429 Too many requests

PRINCIPAL sees lightweight entries for agents bound to their principal account. AGENT sees its own registered entry unless granted a more specific delegation. ADMIN sees authorized tenant records, PARTNER sees portfolio-scoped entries. Always enforce row-level relationship checks and pagination.

Authentication

HTTP Bearer / JWT

Eligible roles

PRINCIPAL, AGENT, ADMIN, PARTNER

Only bound agents or explicitly authorized tenancy/portfolio agents.

Parameters

• limit · query · optional
• cursor · query · optional — Opaque server-generated pagination cursor
• status · query · optional

Illustrative examples. Credential values are placeholders; optional fields are omitted.

GET /agents

{
  "data": [
    {
      "agent_id": "agt_example",
      "name": "ShoppingAgent",
      "technology": "OpenClaw",
      "status": "PENDING_EMAIL_VERIFICATION"
    }
  ],
  "page": {
    "has_more": false
  }
}

Error responses

• 401 No valid authentication for this actor
• 403 Authenticated actor lacks rights to the resource

Read agent full profile and observed runtime metadata, access-filtered

Authentication

HTTP Bearer / JWT

Eligible roles

AGENT, PRINCIPAL, ADMIN, PARTNER

Agent itself, bound principal, or portfolio/tenant authority. Redact sensitive metadata by role.

Parameters

• agentId · path · required

Illustrative examples. Credential values are placeholders; optional fields are omitted.

GET /agents/{agentId}

{
  "agent_id": "agt_example",
  "name": "ShoppingAgent",
  "purpose": "Buy books with principal approval",
  "technology": {
    "platform": "Custom agent"
  },
  "status": "PENDING_EMAIL_VERIFICATION",
  "created_at": "2026-11-15T12:00:00Z",
  "updated_at": "2026-11-15T12:00:00Z"
}

Error responses

• 401 No valid authentication for this actor
• 404 Not found or deliberately hidden from this actor
• 403 Authenticated actor lacks rights to the resource

Update mutable profile settings. Sensitive verified fields (email, owner, trusted KYA state, runtime signing keys) require independent owner consent and a trusted key-rotation workflow. An AGENT may update its own nonprivileged claims, while owner/ADMIN/PARTNER can change fields allowed by their scope. PUT is treated as a replacement of the mutable agent profile; omission clears optional profile fields, never server-managed identity or trusted observations.

Authentication

HTTP Bearer / JWT

Eligible roles

AGENT, PRINCIPAL, ADMIN, PARTNER

Agent self-service only for declared metadata. Bound owner or privileged actor for owner-controlled fields.

Parameters

• agentId · path · required

Illustrative examples. Credential values are placeholders; optional fields are omitted.

{
  "name": "ShoppingAgent",
  "purpose": "Buy books with principal approval"
}

{
  "agent_id": "agt_example",
  "name": "ShoppingAgent",
  "purpose": "Buy books with principal approval",
  "technology": {
    "platform": "Custom agent"
  },
  "status": "PENDING_EMAIL_VERIFICATION",
  "created_at": "2026-11-15T12:00:00Z",
  "updated_at": "2026-11-15T12:00:00Z"
}

Error responses

• 400 Invalid syntax or input
• 403 Authenticated actor lacks rights to the resource
• 404 Not found or deliberately hidden from this actor
• 409 State conflict, optimistic lock or idempotency mismatch
• 401 No valid authentication for this actor

Blocks new tokens and capabilities; invalidates active agent sessions/capabilities where operationally possible. Does not unwind already authorized purchases.

Authentication

HTTP Bearer / JWT

Eligible roles

PRINCIPAL, ADMIN, PARTNER

Only verified agent owner or authorized administrator/partner.

Parameters

• agentId · path · required
• Idempotency-Key · header · required — Repeat the same logical mutation with the same key and same payload; reuse with a changed payload is a 409.

Illustrative examples. Credential values are placeholders; optional fields are omitted.

POST /agents/{agentId}/disable

{
  "agent_id": "agt_example",
  "name": "ShoppingAgent",
  "purpose": "Buy books with principal approval",
  "technology": {
    "platform": "Custom agent"
  },
  "status": "DISABLED",
  "created_at": "2026-11-15T12:00:00Z",
  "updated_at": "2026-11-15T12:00:00Z"
}

Error responses

• 403 Authenticated actor lacks rights to the resource
• 404 Not found or deliberately hidden from this actor
• 409 State conflict, optimistic lock or idempotency mismatch
• 401 No valid authentication for this actor

Re-enablement requires the original operator to remain verified; deleted/revoked agents cannot be re-enabled this way.

Authentication

HTTP Bearer / JWT

Eligible roles

PRINCIPAL, ADMIN, PARTNER

Only verified agent owner or authorized administrator/partner.

Parameters

• agentId · path · required
• Idempotency-Key · header · required — Repeat the same logical mutation with the same key and same payload; reuse with a changed payload is a 409.

Illustrative examples. Credential values are placeholders; optional fields are omitted.

POST /agents/{agentId}/enable

{
  "agent_id": "agt_example",
  "name": "ShoppingAgent",
  "purpose": "Buy books with principal approval",
  "technology": {
    "platform": "Custom agent"
  },
  "status": "ACTIVE",
  "created_at": "2026-11-15T12:00:00Z",
  "updated_at": "2026-11-15T12:00:00Z"
}

Error responses

• 403 Authenticated actor lacks rights to the resource
• 404 Not found or deliberately hidden from this actor
• 409 State conflict, optimistic lock or idempotency mismatch
• 401 No valid authentication for this actor

Soft delete (tombstone), revoke credentials, disable bindings and unused capabilities. Immutable payment and audit records must be retained where required. POST is retained as explicitly requested; this is not physical deletion and cannot be undone by /enable.

Authentication

HTTP Bearer / JWT

Eligible roles

PRINCIPAL, ADMIN, PARTNER

Only verified agent owner or authorized administrator/partner.

Parameters

• agentId · path · required
• Idempotency-Key · header · required — Repeat the same logical mutation with the same key and same payload; reuse with a changed payload is a 409.

Illustrative examples. Credential values are placeholders; optional fields are omitted.

POST /agents/{agentId}/delete

{
  "agent_id": "agt_example",
  "name": "ShoppingAgent",
  "purpose": "Buy books with principal approval",
  "technology": {
    "platform": "Custom agent"
  },
  "status": "DELETED",
  "created_at": "2026-11-15T12:00:00Z",
  "updated_at": "2026-11-15T12:00:00Z"
}

Error responses

• 403 Authenticated actor lacks rights to the resource
• 404 Not found or deliberately hidden from this actor
• 401 No valid authentication for this actor

Separate self-declared information, verified operator/key proofs and server-observed runtime/IP risk signals. Sensitive details may be redacted by role.

Authentication

HTTP Bearer / JWT

Eligible roles

AGENT, PRINCIPAL, ADMIN, PARTNER

Self, bound principal or administrative/partner scope.

Parameters

• agentId · path · required

Illustrative examples. Credential values are placeholders; optional fields are omitted.

GET /agents/{agentId}/kya

{
  "agent_id": "agt_example",
  "status": "VERIFIED",
  "declared": {
    "name": "ShoppingAgent",
    "purpose": "Buy books with principal approval",
    "technology": {
      "platform": "Custom agent"
    },
    "environment": {
      "type": "LOCAL",
      "country": "AT"
    }
  },
  "assurance_level": "EMAIL_VERIFIED"
}

Error responses

• 401 No valid authentication for this actor
• 403 Authenticated actor lacks rights to the resource
• 404 Not found or deliberately hidden from this actor

Limits are scoped to the authenticated principal's binding with this agent; a PARTNER or ADMIN must supply the permitted principal_reference where acting on behalf of a principal. Agent self-service cannot create or raise spending authority. All limits cap a separately authenticated principal spending mandate; they do not grant spending authority themselves. Weekly period is a rolling 7 days.

Authentication

HTTP Bearer / JWT

Eligible roles

PRINCIPAL, ADMIN, PARTNER

Bound principal or explicitly authorized principal portfolio.

Parameters

• agentId · path · required
• Idempotency-Key · header · required — Repeat the same logical mutation with the same key and same payload; reuse with a changed payload is a 409.

Illustrative examples. Credential values are placeholders; optional fields are omitted.

{
  "per_purchase": {
    "value": "24.00",
    "currency": "EUR"
  },
  "weekly": {
    "value": "24.00",
    "currency": "EUR"
  },
  "total": {
    "value": "24.00",
    "currency": "EUR"
  }
}

{
  "agent_id": "agt_example",
  "principal_reference": "pref_example",
  "per_purchase": {
    "value": "24.00",
    "currency": "EUR"
  },
  "weekly": {
    "value": "24.00",
    "currency": "EUR"
  },
  "total": {
    "value": "24.00",
    "currency": "EUR"
  },
  "weekly_window": "ROLLING_7_DAYS",
  "weekly_usage": {
    "spent": {
      "value": "0.00",
      "currency": "EUR"
    },
    "reserved": {
      "value": "0.00",
      "currency": "EUR"
    },
    "available": {
      "value": "24.00",
      "currency": "EUR"
    }
  },
  "total_usage": {
    "spent": {
      "value": "0.00",
      "currency": "EUR"
    },
    "reserved": {
      "value": "0.00",
      "currency": "EUR"
    },
    "available": {
      "value": "24.00",
      "currency": "EUR"
    }
  },
  "updated_at": "2026-11-15T12:00:00Z"
}

Error responses

• 400 Invalid syntax or input
• 401 No valid authentication for this actor
• 403 Authenticated actor lacks rights to the resource
• 404 Not found or deliberately hidden from this actor
• 409 State conflict, optimistic lock or idempotency mismatch

PRINCIPAL scope comes from bearer identity. AGENT must supply a bound principal_reference if bound to more than one principal; only authorized data returned. Outstanding reservations count against spend ceilings.

Authentication

HTTP Bearer / JWT

Eligible roles

AGENT, PRINCIPAL, ADMIN, PARTNER

Bound principal or approved portfolio; no cross-principal leakage.

Parameters

• agentId · path · required
• principal_reference · query · optional — Required for an agent with multiple principal bindings and for privileged delegated reads

Illustrative examples. Credential values are placeholders; optional fields are omitted.

GET /agents/{agentId}/limits

{
  "agent_id": "agt_example",
  "principal_reference": "pref_example",
  "per_purchase": {
    "value": "24.00",
    "currency": "EUR"
  },
  "weekly": {
    "value": "24.00",
    "currency": "EUR"
  },
  "total": {
    "value": "24.00",
    "currency": "EUR"
  },
  "weekly_window": "ROLLING_7_DAYS",
  "weekly_usage": {
    "spent": {
      "value": "0.00",
      "currency": "EUR"
    },
    "reserved": {
      "value": "0.00",
      "currency": "EUR"
    },
    "available": {
      "value": "24.00",
      "currency": "EUR"
    }
  },
  "total_usage": {
    "spent": {
      "value": "0.00",
      "currency": "EUR"
    },
    "reserved": {
      "value": "0.00",
      "currency": "EUR"
    },
    "available": {
      "value": "24.00",
      "currency": "EUR"
    }
  },
  "updated_at": "2026-11-15T12:00:00Z"
}

Error responses

• 400 Invalid syntax or input
• 403 Authenticated actor lacks rights to the resource
• 404 Not found or deliberately hidden from this actor
• 401 No valid authentication for this actor

A change to any limit does not authorize spending by itself. Concurrent reservations and already approved intents remain constrained; enforcement uses the strictest applicable principal/issuer/agent ceiling. All changes audited.

Authentication

HTTP Bearer / JWT

Eligible roles

PRINCIPAL, ADMIN, PARTNER

Bound principal or approved portfolio. Agent bearer cannot increase limits.

Parameters

• agentId · path · required
• Idempotency-Key · header · required — Repeat the same logical mutation with the same key and same payload; reuse with a changed payload is a 409.

Illustrative examples. Credential values are placeholders; optional fields are omitted.

{
  "per_purchase": {
    "value": "24.00",
    "currency": "EUR"
  },
  "weekly": {
    "value": "24.00",
    "currency": "EUR"
  },
  "total": {
    "value": "24.00",
    "currency": "EUR"
  }
}

{
  "agent_id": "agt_example",
  "principal_reference": "pref_example",
  "per_purchase": {
    "value": "24.00",
    "currency": "EUR"
  },
  "weekly": {
    "value": "24.00",
    "currency": "EUR"
  },
  "total": {
    "value": "24.00",
    "currency": "EUR"
  },
  "weekly_window": "ROLLING_7_DAYS",
  "weekly_usage": {
    "spent": {
      "value": "0.00",
      "currency": "EUR"
    },
    "reserved": {
      "value": "0.00",
      "currency": "EUR"
    },
    "available": {
      "value": "24.00",
      "currency": "EUR"
    }
  },
  "total_usage": {
    "spent": {
      "value": "0.00",
      "currency": "EUR"
    },
    "reserved": {
      "value": "0.00",
      "currency": "EUR"
    },
    "available": {
      "value": "24.00",
      "currency": "EUR"
    }
  },
  "updated_at": "2026-11-15T12:00:00Z"
}

Error responses

• 400 Invalid syntax or input
• 403 Authenticated actor lacks rights to the resource
• 404 Not found or deliberately hidden from this actor
• 409 State conflict, optimistic lock or idempotency mismatch
• 401 No valid authentication for this actor

Initial EMAIL_ENROLLMENT redemption accepts the one-time enrollment credential returned by POST /agents, but only after an owner has verified email and approved the requested profile via the trusted hosted link. Redemption is atomic and issues short-lived access_token, role=AGENT, plus an agent_api_key only once. Never send these credentials by email. Subsequent authentication uses API_KEY (rotatable, revocable and rate limited) or SIGNED_ASSERTION with a registered public key. credential is authentication proof, NEVER a private key. Signed assertions must be fresh, audience-bound and replay protected. A production sender-constrained access token (e.g. DPoP/mTLS) is preferable to a reusable bearer token alone.

Authentication

Public · no bearer token

Eligible roles

PUBLIC

Parameters

No path, query or header parameters defined.

Illustrative examples. Credential values are placeholders; optional fields are omitted.

{
  "agent_id": "agt_example",
  "authentication_method": "EMAIL_ENROLLMENT",
  "credential": "<one-time enrollment credential>"
}

{
  "access_token": "<short-lived access token>",
  "token_type": "Bearer",
  "expires_in": 1,
  "agent_id": "agt_example",
  "role": "AGENT"
}

Error responses

• 400 Invalid syntax or input
• 401 No valid authentication for this actor
• 429 Too many requests

Principal ID is server generated; it is NOT submitted. Idempotency-Key is a retry header, not a bearer credential. An authenticated principal session with explicit onboarding authority or trusted partner/admin channel can create a principal. principal_type selects either an individual or business profile, never both. A business must have a verified authorized representative; contact details do not establish that authority. KYC/KYB verification is a separate process and spending remains blocked where identity verification is required.

Authentication

HTTP Bearer / JWT

Eligible roles

PRINCIPAL, ADMIN, PARTNER

Individual self-onboarding, verified business-representative authority, or explicitly delegated administrative/partner onboarding.

Parameters

• Idempotency-Key · header · required — Repeat the same logical mutation with the same key and same payload; reuse with a changed payload is a 409.

Illustrative examples. Credential values are placeholders; optional fields are omitted.

{
  "principal_type": "INDIVIDUAL",
  "email": "person@example.com",
  "individual": {
    "first_name": "Example",
    "last_name": "Person"
  }
}

{
  "principal_id": "prn_example",
  "principal_type": "INDIVIDUAL",
  "email": "person@example.com",
  "individual": {
    "first_name": "Example",
    "last_name": "Person"
  },
  "verification_status": "PENDING",
  "created_at": "2026-11-15T12:00:00Z",
  "updated_at": "2026-11-15T12:00:00Z"
}

Business principal

Use a business profile instead of an individual profile. Declared registration details do not prove representative authority or grant spending permission.

{
  "principal_type": "BUSINESS",
  "email": "representative@example.com",
  "business": {
    "legal_name": "Example Business",
    "registration_country": "AT",
    "registration_number": "EXAMPLE-REGISTRATION"
  }
}

{
  "principal_id": "prn_example",
  "principal_type": "BUSINESS",
  "email": "representative@example.com",
  "business": {
    "legal_name": "Example Business",
    "registration_country": "AT",
    "registration_number": "EXAMPLE-REGISTRATION"
  },
  "verification_status": "PENDING",
  "created_at": "2026-11-15T12:00:00Z",
  "updated_at": "2026-11-15T12:00:00Z"
}

Error responses

• 400 Invalid syntax or input
• 401 No valid authentication for this actor
• 403 Authenticated actor lacks rights to the resource
• 409 State conflict, optimistic lock or idempotency mismatch

Only the individual, an authorized representative of the subject business, or an explicitly scoped administrative/partner channel may read sensitive profile fields. A contact email does not establish business authority.

Authentication

HTTP Bearer / JWT

Eligible roles

PRINCIPAL, ADMIN, PARTNER

Self or explicit tenant/portfolio access; no cross-principal read/write.

Parameters

• principalId · path · required

Illustrative examples. Credential values are placeholders; optional fields are omitted.

GET /principals/{principalId}

{
  "principal_id": "prn_example",
  "principal_type": "INDIVIDUAL",
  "email": "person@example.com",
  "individual": {
    "first_name": "Example",
    "last_name": "Person"
  },
  "verification_status": "PENDING",
  "created_at": "2026-11-15T12:00:00Z",
  "updated_at": "2026-11-15T12:00:00Z"
}

Error responses

• 401 No valid authentication for this actor
• 403 Authenticated actor lacks rights to the resource
• 404 Not found or deliberately hidden from this actor

Does not accept changes to principal_id, principal_type, verification_status, identity_verification_status, representative authority or externally approved consent. Only the profile matching the stored principal_type can be updated; profile changes may require renewed verification and do not silently update previously verified intents.

Authentication

HTTP Bearer / JWT

Eligible roles

PRINCIPAL, ADMIN, PARTNER

Self or explicit tenant/portfolio access; no cross-principal read/write.

Parameters

• principalId · path · required

Illustrative examples. Credential values are placeholders; optional fields are omitted.

{
  "individual": {
    "first_name": "Example",
    "last_name": "Person"
  }
}

{
  "principal_id": "prn_example",
  "principal_type": "INDIVIDUAL",
  "email": "person@example.com",
  "individual": {
    "first_name": "Example",
    "last_name": "Person"
  },
  "verification_status": "PENDING",
  "created_at": "2026-11-15T12:00:00Z",
  "updated_at": "2026-11-15T12:00:00Z"
}

Error responses

• 400 Invalid syntax or input
• 403 Authenticated actor lacks rights to the resource
• 404 Not found or deliberately hidden from this actor
• 409 State conflict, optimistic lock or idempotency mismatch
• 401 No valid authentication for this actor

Principal-controlled action performed through a trusted channel. Records an explicit consent to establish an association with the agent; it does NOT create carte blanche to spend. The server verifies the authenticated session is scoped to the requested principal and that the agent is eligible. For BUSINESS principals, independently verify the authenticated representative's authority and applicable business spending mandate. An agent cannot approve its own binding or nominate a business representative as proof of consent. A stable, opaque agent-scoped principal_reference is returned.

Authentication

HTTP Bearer / JWT

Eligible roles

PRINCIPAL, ADMIN, PARTNER

Principal consent mandatory; admins/partners cannot silently fabricate principal spend approval.

Parameters

• principalId · path · required
• Idempotency-Key · header · required — Repeat the same logical mutation with the same key and same payload; reuse with a changed payload is a 409.

Illustrative examples. Credential values are placeholders; optional fields are omitted.

{
  "agent_id": "agt_example",
  "consent_acknowledged": true
}

{
  "binding_id": "bnd_example",
  "principal_id": "prn_example",
  "principal_type": "INDIVIDUAL",
  "agent_id": "agt_example",
  "principal_reference": "pref_example",
  "status": "ACTIVE",
  "bound_at": "2026-11-15T12:00:00Z"
}

Error responses

• 400 Invalid syntax or input
• 403 Authenticated actor lacks rights to the resource
• 404 Not found or deliberately hidden from this actor
• 409 State conflict, optimistic lock or idempotency mismatch
• 401 No valid authentication for this actor

List the principal's agent bindings

Authentication

HTTP Bearer / JWT

Eligible roles

PRINCIPAL, ADMIN, PARTNER

Principal consent mandatory; admins/partners cannot silently fabricate principal spend approval.

Parameters

• principalId · path · required
• limit · query · optional
• cursor · query · optional — Opaque server-generated pagination cursor

Illustrative examples. Credential values are placeholders; optional fields are omitted.

GET /principals/{principalId}/bindings

{
  "data": [
    {
      "binding_id": "bnd_example",
      "principal_id": "prn_example",
      "principal_type": "INDIVIDUAL",
      "agent_id": "agt_example",
      "principal_reference": "pref_example",
      "status": "ACTIVE",
      "bound_at": "2026-11-15T12:00:00Z"
    }
  ],
  "page": {
    "has_more": false
  }
}

Error responses

• 403 Authenticated actor lacks rights to the resource
• 404 Not found or deliberately hidden from this actor
• 401 No valid authentication for this actor

Disables future intents and unused capabilities under this binding; already-authorized transactions may need separate reversal/refund steps. Audit and transaction records are retained as required.

Authentication

HTTP Bearer / JWT

Eligible roles

PRINCIPAL, ADMIN, PARTNER

Principal consent mandatory; admins/partners cannot silently fabricate principal spend approval.

Parameters

• principalId · path · required
• agentId · path · required

Illustrative examples. Credential values are placeholders; optional fields are omitted.

DELETE /principals/{principalId}/bindings/{agentId}

No response body.

Error responses

• 403 Authenticated actor lacks rights to the resource
• 404 Not found or deliberately hidden from this actor
• 409 State conflict, optimistic lock or idempotency mismatch
• 401 No valid authentication for this actor

Returns a short-lived hosted verification URL. The authenticated individual or authorized business representative completes verification with a trusted provider, not with the agent. The server selects KYC for INDIVIDUAL or KYB for BUSINESS from the stored principal_type. Business verification includes required representative/ownership checks; a passed KYB result is not a spending mandate. The service accepts verification decisions only from an authenticated provider integration; it must not accept agent-supplied VERIFIED flags. Do not expose PII or submitted identity-document images through these endpoints.

Authentication

HTTP Bearer / JWT

Eligible roles

PRINCIPAL, ADMIN, PARTNER

Subject principal or explicitly authorized onboarding partner.

Parameters

• principalId · path · required
• Idempotency-Key · header · required — Repeat the same logical mutation with the same key and same payload; reuse with a changed payload is a 409.

Illustrative examples. Credential values are placeholders; optional fields are omitted.

{
  "locale": "de-AT"
}

{
  "verification_id": "ver_123456",
  "principal_id": "prn_example",
  "verification_type": "KYC",
  "status": "PENDING",
  "verification_url": "https://verification.example/session",
  "expires_at": "2026-11-15T12:00:00Z"
}

{
  "verification_id": "ver_123456",
  "principal_id": "prn_example",
  "verification_type": "KYB",
  "status": "PENDING",
  "verification_url": "https://verification.example/session",
  "expires_at": "2026-11-15T12:00:00Z"
}

Error responses

• 400 Invalid syntax or input
• 401 No valid authentication for this actor
• 403 Authenticated actor lacks rights to the resource
• 404 Not found or deliberately hidden from this actor
• 409 State conflict, optimistic lock or idempotency mismatch

Read principal KYC/KYB status without disclosing underlying identity documents

Authentication

HTTP Bearer / JWT

Eligible roles

PRINCIPAL, ADMIN, PARTNER

Subject principal or authorized onboarding/compliance partner.

Parameters

• principalId · path · required

Illustrative examples. Credential values are placeholders; optional fields are omitted.

GET /principals/{principalId}/verification

{
  "principal_id": "prn_example",
  "verification_type": "KYC",
  "status": "NOT_STARTED"
}

{
  "principal_id": "prn_example",
  "verification_type": "KYB",
  "status": "NOT_STARTED"
}

Error responses

• 401 No valid authentication for this actor
• 403 Authenticated actor lacks rights to the resource
• 404 Not found or deliberately hidden from this actor

An agent submits its understanding of merchant, basket, prices, billing, shipping, checkout channel, PSP and principal authorization reference. Values in this request are agent-declared and must not be treated as verified merchant/issuer evidence. The agent identity is derived from the access token. Principal approval cannot be self-asserted by an agent. The server validates order arithmetic, currency consistency and ownership. Creating an intent neither approves it nor issues a card/token.

Authentication

HTTP Bearer / JWT

Eligible roles

AGENT, PRINCIPAL, ADMIN, PARTNER

Agent self and bound principal; ADMIN/PARTNER only within authorized scope. Verify cannot replace principal consent.

Parameters

• Idempotency-Key · header · required — Repeat the same logical mutation with the same key and same payload; reuse with a changed payload is a 409.

Illustrative examples. Credential values are placeholders; optional fields are omitted.

{
  "principal_reference": "pref_example",
  "binding_id": "bnd_example",
  "purpose": "Buy one book",
  "merchant": {
    "name": "Example Books",
    "domain": "books.example"
  },
  "cart": {
    "items": [
      {
        "title": "Example book",
        "quantity": 1,
        "unit_price": {
          "value": "24.00",
          "currency": "EUR"
        },
        "line_total": {
          "value": "24.00",
          "currency": "EUR"
        }
      }
    ],
    "subtotal": {
      "value": "24.00",
      "currency": "EUR"
    },
    "tax_total": {
      "value": "0.00",
      "currency": "EUR"
    },
    "shipping_total": {
      "value": "0.00",
      "currency": "EUR"
    },
    "discount_total": {
      "value": "0.00",
      "currency": "EUR"
    },
    "total": {
      "value": "24.00",
      "currency": "EUR"
    }
  },
  "checkout": {
    "mode": "CLASSIC",
    "merchant_checkout_url": "https://books.example/checkout"
  },
  "requested_constraints": {
    "amount_max": {
      "value": "24.00",
      "currency": "EUR"
    },
    "valid_until": "2026-11-15T12:00:00Z",
    "max_authorizations": 1
  }
}

{
  "intent_id": "int_example",
  "agent_id": "agt_example",
  "principal_reference": "pref_example",
  "binding_id": "bnd_example",
  "status": "DRAFT",
  "purchase": {
    "principal_reference": "pref_example",
    "binding_id": "bnd_example",
    "purpose": "Buy one book",
    "merchant": {
      "name": "Example Books",
      "domain": "books.example"
    },
    "cart": {
      "items": [
        {
          "title": "Example book",
          "quantity": 1,
          "unit_price": {
            "value": "24.00",
            "currency": "EUR"
          },
          "line_total": {
            "value": "24.00",
            "currency": "EUR"
          }
        }
      ],
      "subtotal": {
        "value": "24.00",
        "currency": "EUR"
      },
      "tax_total": {
        "value": "0.00",
        "currency": "EUR"
      },
      "shipping_total": {
        "value": "0.00",
        "currency": "EUR"
      },
      "discount_total": {
        "value": "0.00",
        "currency": "EUR"
      },
      "total": {
        "value": "24.00",
        "currency": "EUR"
      }
    },
    "checkout": {
      "mode": "CLASSIC",
      "merchant_checkout_url": "https://books.example/checkout"
    },
    "requested_constraints": {
      "amount_max": {
        "value": "24.00",
        "currency": "EUR"
      },
      "valid_until": "2026-11-15T12:00:00Z",
      "max_authorizations": 1
    }
  },
  "created_at": "2026-11-15T12:00:00Z",
  "updated_at": "2026-11-15T12:00:00Z"
}

Error responses

• 400 Invalid syntax or input
• 401 No valid authentication for this actor
• 403 Authenticated actor lacks rights to the resource
• 409 State conflict, optimistic lock or idempotency mismatch
• 422 Well-formed request fails domain or financial validation

Scoped to the agent and its explicitly delegated resources; no cross-principal enumeration.

Authentication

HTTP Bearer / JWT

Eligible roles

AGENT, PRINCIPAL, ADMIN, PARTNER

Agent self and bound principal; ADMIN/PARTNER only within authorized scope. Verify cannot replace principal consent.

Parameters

• limit · query · optional
• cursor · query · optional — Opaque server-generated pagination cursor
• status · query · optional
• principal_reference · query · optional

Illustrative examples. Credential values are placeholders; optional fields are omitted.

GET /intents

{
  "data": [
    {
      "intent_id": "int_example",
      "agent_id": "agt_example",
      "principal_reference": "pref_example",
      "binding_id": "bnd_example",
      "status": "DRAFT",
      "purchase": {
        "principal_reference": "pref_example",
        "binding_id": "bnd_example",
        "purpose": "Buy one book",
        "merchant": {
          "name": "Example Books",
          "domain": "books.example"
        },
        "cart": {
          "items": [
            {
              "title": "Example book",
              "quantity": 1,
              "unit_price": {
                "value": "24.00",
                "currency": "EUR"
              },
              "line_total": {
                "value": "24.00",
                "currency": "EUR"
              }
            }
          ],
          "subtotal": {
            "value": "24.00",
            "currency": "EUR"
          },
          "tax_total": {
            "value": "0.00",
            "currency": "EUR"
          },
          "shipping_total": {
            "value": "0.00",
            "currency": "EUR"
          },
          "discount_total": {
            "value": "0.00",
            "currency": "EUR"
          },
          "total": {
            "value": "24.00",
            "currency": "EUR"
          }
        },
        "checkout": {
          "mode": "CLASSIC",
          "merchant_checkout_url": "https://books.example/checkout"
        },
        "requested_constraints": {
          "amount_max": {
            "value": "24.00",
            "currency": "EUR"
          },
          "valid_until": "2026-11-15T12:00:00Z",
          "max_authorizations": 1
        }
      },
      "created_at": "2026-11-15T12:00:00Z",
      "updated_at": "2026-11-15T12:00:00Z"
    }
  ],
  "page": {
    "has_more": false
  }
}

Error responses

• 401 No valid authentication for this actor
• 403 Authenticated actor lacks rights to the resource

Retrieve intent, verification status and policy reasons

Authentication

HTTP Bearer / JWT

Eligible roles

AGENT, PRINCIPAL, ADMIN, PARTNER

Agent self and bound principal; ADMIN/PARTNER only within authorized scope. Verify cannot replace principal consent.

Parameters

• intentId · path · required

Illustrative examples. Credential values are placeholders; optional fields are omitted.

GET /intents/{intentId}

{
  "intent_id": "int_example",
  "agent_id": "agt_example",
  "principal_reference": "pref_example",
  "binding_id": "bnd_example",
  "status": "DRAFT",
  "purchase": {
    "principal_reference": "pref_example",
    "binding_id": "bnd_example",
    "purpose": "Buy one book",
    "merchant": {
      "name": "Example Books",
      "domain": "books.example"
    },
    "cart": {
      "items": [
        {
          "title": "Example book",
          "quantity": 1,
          "unit_price": {
            "value": "24.00",
            "currency": "EUR"
          },
          "line_total": {
            "value": "24.00",
            "currency": "EUR"
          }
        }
      ],
      "subtotal": {
        "value": "24.00",
        "currency": "EUR"
      },
      "tax_total": {
        "value": "0.00",
        "currency": "EUR"
      },
      "shipping_total": {
        "value": "0.00",
        "currency": "EUR"
      },
      "discount_total": {
        "value": "0.00",
        "currency": "EUR"
      },
      "total": {
        "value": "24.00",
        "currency": "EUR"
      }
    },
    "checkout": {
      "mode": "CLASSIC",
      "merchant_checkout_url": "https://books.example/checkout"
    },
    "requested_constraints": {
      "amount_max": {
        "value": "24.00",
        "currency": "EUR"
      },
      "valid_until": "2026-11-15T12:00:00Z",
      "max_authorizations": 1
    }
  },
  "created_at": "2026-11-15T12:00:00Z",
  "updated_at": "2026-11-15T12:00:00Z"
}

Error responses

• 403 Authenticated actor lacks rights to the resource
• 404 Not found or deliberately hidden from this actor
• 401 No valid authentication for this actor

Only allowed for DRAFT or CHANGES_REQUESTED; replaces the mutable purchase details. Any prior verification result is invalidated. Once verified, the signed purchase snapshot is immutable: create a new intent to change material merchant, amount, product, address or checkout fields.

Authentication

HTTP Bearer / JWT

Eligible roles

AGENT, PRINCIPAL, ADMIN, PARTNER

Agent self and bound principal; ADMIN/PARTNER only within authorized scope. Verify cannot replace principal consent.

Parameters

• intentId · path · required

Illustrative examples. Credential values are placeholders; optional fields are omitted.

{
  "principal_reference": "pref_example",
  "binding_id": "bnd_example",
  "purpose": "Buy one book",
  "merchant": {
    "name": "Example Books",
    "domain": "books.example"
  },
  "cart": {
    "items": [
      {
        "title": "Example book",
        "quantity": 1,
        "unit_price": {
          "value": "24.00",
          "currency": "EUR"
        },
        "line_total": {
          "value": "24.00",
          "currency": "EUR"
        }
      }
    ],
    "subtotal": {
      "value": "24.00",
      "currency": "EUR"
    },
    "tax_total": {
      "value": "0.00",
      "currency": "EUR"
    },
    "shipping_total": {
      "value": "0.00",
      "currency": "EUR"
    },
    "discount_total": {
      "value": "0.00",
      "currency": "EUR"
    },
    "total": {
      "value": "24.00",
      "currency": "EUR"
    }
  },
  "checkout": {
    "mode": "CLASSIC",
    "merchant_checkout_url": "https://books.example/checkout"
  },
  "requested_constraints": {
    "amount_max": {
      "value": "24.00",
      "currency": "EUR"
    },
    "valid_until": "2026-11-15T12:00:00Z",
    "max_authorizations": 1
  }
}

{
  "intent_id": "int_example",
  "agent_id": "agt_example",
  "principal_reference": "pref_example",
  "binding_id": "bnd_example",
  "status": "DRAFT",
  "purchase": {
    "principal_reference": "pref_example",
    "binding_id": "bnd_example",
    "purpose": "Buy one book",
    "merchant": {
      "name": "Example Books",
      "domain": "books.example"
    },
    "cart": {
      "items": [
        {
          "title": "Example book",
          "quantity": 1,
          "unit_price": {
            "value": "24.00",
            "currency": "EUR"
          },
          "line_total": {
            "value": "24.00",
            "currency": "EUR"
          }
        }
      ],
      "subtotal": {
        "value": "24.00",
        "currency": "EUR"
      },
      "tax_total": {
        "value": "0.00",
        "currency": "EUR"
      },
      "shipping_total": {
        "value": "0.00",
        "currency": "EUR"
      },
      "discount_total": {
        "value": "0.00",
        "currency": "EUR"
      },
      "total": {
        "value": "24.00",
        "currency": "EUR"
      }
    },
    "checkout": {
      "mode": "CLASSIC",
      "merchant_checkout_url": "https://books.example/checkout"
    },
    "requested_constraints": {
      "amount_max": {
        "value": "24.00",
        "currency": "EUR"
      },
      "valid_until": "2026-11-15T12:00:00Z",
      "max_authorizations": 1
    }
  },
  "created_at": "2026-11-15T12:00:00Z",
  "updated_at": "2026-11-15T12:00:00Z"
}

Error responses

• 400 Invalid syntax or input
• 403 Authenticated actor lacks rights to the resource
• 404 Not found or deliberately hidden from this actor
• 409 State conflict, optimistic lock or idempotency mismatch
• 401 No valid authentication for this actor

Separate explicit step from payment credential issuance. Looks up principal-agent binding and actual consent/mandate in a trusted system; a client-supplied consent reference is never independent proof. Performs deterministic hard-rule checks (agent, principal, amount, currency, merchant allowlist, goods/geography, validity, frequency and prior use). Probabilistic risk or AI-based signals may only inform a manual review or step-up decision, not override hard restrictions. If principal approval is missing, returns STEP_UP_REQUIRED with a secure principal action URL. VERIFIED is only set once all required consent and verification succeed. Product, address, and PSP claims can be assessed before checkout using independent evidence where available; they are not assumed observable during standard issuer authorization. Where identity verification is required, an unverified principal cannot receive spend authority; return STEP_UP_REQUIRED with a KYC/KYB verification action, or domain error identity_verification_required as appropriate. Agent KYA and principal/agent limits are independently enforced and untrusted agent profile mismatches inform risk.

Authentication

HTTP Bearer / JWT

Eligible roles

AGENT, PRINCIPAL, ADMIN, PARTNER

Agent self and bound principal; ADMIN/PARTNER only within authorized scope. Verify cannot replace principal consent.

Parameters

• intentId · path · required
• Idempotency-Key · header · required — Repeat the same logical mutation with the same key and same payload; reuse with a changed payload is a 409.

Illustrative examples. Credential values are placeholders; optional fields are omitted.

{
  "note": "Principal approval is available for review"
}

{
  "verification_id": "example",
  "intent_id": "int_example",
  "decision": "APPROVED",
  "intent_status": "VERIFIED",
  "policy_version": "example-policy",
  "reason_codes": [],
  "evidence_id": "example"
}

Error responses

• 400 Invalid syntax or input
• 403 Authenticated actor lacks rights to the resource
• 404 Not found or deliberately hidden from this actor
• 409 State conflict, optimistic lock or idempotency mismatch
• 503 Dependency unavailable; no implicit authorization or approval
• 401 No valid authentication for this actor

Creates one payment attempt for a previously VERIFIED purchase intent. No client TTL parameter. Server sets nominal 60-second one-use capability window. For VIRTUAL_CARD (existing EPHEMERAL_CARD rail) issuer processor issues one unique card identifier per attempt; Agent Pay stores immutable credential_id -> payment_id -> intent_id and issuer processor_card_id mappings. Agent may receive a ONE-TIME sensitive card object (PAN, CVV, expiry, sponsor-approved alphabetic cardholder name) in this POST response if issuance and PCI delivery permit it. All GET endpoints and idempotent replays provide redacted card metadata ONLY. Never log/store CVV after authorization. Network agentic rails can return a separate restricted token handoff; equivalent issuer-token-to-intent binding must be confirmed. Checkout/merchant charges happen outside this API; successful credential issuance does not imply authorization. One intent may have failed/expired payment attempts, but only one distinct successful purchase; issuer auth retries and lifecycle events are deduplicated atomically.

Authentication

HTTP Bearer / JWT

Eligible roles

AGENT, PRINCIPAL, ADMIN, PARTNER

Only authorized agent or specifically delegated permitted actor; principal approval and verified intent remain mandatory.

Parameters

• intentId · path · required
• Idempotency-Key · header · required — Repeat the same logical mutation with the same key and same payload; reuse with a changed payload is a 409.

Illustrative examples. Credential values are placeholders; optional fields are omitted.

{
  "requested_rail": "AUTO"
}

{
  "payment": {
    "payment_id": "pay_example",
    "intent_id": "int_example",
    "status": "CREDENTIAL_ISSUED",
    "decision": "APPROVED",
    "amount": {
      "value": "24.00",
      "currency": "EUR"
    },
    "correlation_id": "corr_example",
    "created_at": "2026-11-15T12:00:00Z",
    "updated_at": "2026-11-15T12:00:00Z",
    "rail": "EPHEMERAL_CARD"
  }
}

Error responses

• 403 Authenticated actor lacks rights to the resource
• 404 Not found or deliberately hidden from this actor
• 409 State conflict, optimistic lock or idempotency mismatch
• 422 Includes identity_verification_required when principal KYC/KYB is incomplete · identity_verification_required
• 503 Dependency unavailable; no implicit authorization or approval
• 401 No valid authentication for this actor

Card secrets, if issuance permits them, appear only in the initial issuance response. GET endpoints and idempotent replays remain redacted. The nominal 60-second initiation window is system controlled. Issuance does not confirm a purchase; outcome requires trusted processor events.

List payment IDs, rails, statuses and timestamps (no card secrets)

Authentication

HTTP Bearer / JWT

Eligible roles

AGENT, PRINCIPAL, ADMIN, PARTNER

Bound agent, principal or authorized portfolio. Never reveal another principal’s payment details.

Parameters

• intentId · path · required
• limit · query · optional
• cursor · query · optional — Opaque server-generated pagination cursor

Illustrative examples. Credential values are placeholders; optional fields are omitted.

GET /intents/{intentId}/pay

{
  "data": [
    {
      "payment_id": "pay_example",
      "intent_id": "int_example",
      "rail": "VISA_AGENTIC",
      "status": "CREATED",
      "created_at": "2026-11-15T12:00:00Z"
    }
  ],
  "page": {
    "has_more": false
  }
}

Error responses

• 403 Authenticated actor lacks rights to the resource
• 404 Not found or deliberately hidden from this actor
• 401 No valid authentication for this actor

Card secrets, if issuance permits them, appear only in the initial issuance response. GET endpoints and idempotent replays remain redacted. The nominal 60-second initiation window is system controlled. Issuance does not confirm a purchase; outcome requires trusted processor events.

Returns authorized payment metadata, rail, processor-confirmed status, issuer authorization references, safe card details (credential_id, last4 and scope-authorized PSP gateway token ID), but NEVER PAN, CVV or expiration date. The PSP token is not the canonical issuer correlation ID and may still be sensitive. Captured/settled status requires trusted processor events, not agent declaration.

Authentication

HTTP Bearer / JWT

Eligible roles

AGENT, PRINCIPAL, ADMIN, PARTNER

Bound agent, principal or authorized portfolio. Never reveal another principal’s payment details.

Parameters

• intentId · path · required
• paymentId · path · required

Illustrative examples. Credential values are placeholders; optional fields are omitted.

GET /intents/{intentId}/pay/{paymentId}

{
  "payment_id": "pay_example",
  "intent_id": "int_example",
  "status": "CREATED",
  "decision": "APPROVED",
  "amount": {
    "value": "24.00",
    "currency": "EUR"
  },
  "correlation_id": "corr_example",
  "created_at": "2026-11-15T12:00:00Z",
  "updated_at": "2026-11-15T12:00:00Z"
}

Error responses

• 403 Authenticated actor lacks rights to the resource
• 404 Not found or deliberately hidden from this actor
• 401 No valid authentication for this actor

Card secrets, if issuance permits them, appear only in the initial issuance response. GET endpoints and idempotent replays remain redacted. The nominal 60-second initiation window is system controlled. Issuance does not confirm a purchase; outcome requires trusted processor events.

An unused capability can be cancelled. Reversing an authorization depends on sponsor/issuer/processor support. A captured/settled transaction may require a separate merchant refund, not a card authorization reversal; REFUND_REQUEST is only offered where a permitted integration exists. A success here means a reversal operation was accepted, not that funds were returned. Use the returned status and check actual rail events. API retains /reverse as explicitly requested.

Authentication

HTTP Bearer / JWT

Eligible roles

AGENT, PRINCIPAL, ADMIN, PARTNER

Bound agent, principal or authorized portfolio. Never reveal another principal’s payment details.

Parameters

• intentId · path · required
• paymentId · path · required
• Idempotency-Key · header · required — Repeat the same logical mutation with the same key and same payload; reuse with a changed payload is a 409.

Illustrative examples. Credential values are placeholders; optional fields are omitted.

{
  "requested_action": "CANCEL_UNUSED_CAPABILITY",
  "reason": "PRINCIPAL_REQUEST"
}

{
  "operation_id": "example",
  "payment_id": "pay_example",
  "requested_action": "CANCEL_UNUSED_CAPABILITY",
  "status": "PENDING",
  "requested_at": "2026-11-15T12:00:00Z"
}

Error responses

• 400 Invalid syntax or input
• 403 Authenticated actor lacks rights to the resource
• 404 Not found or deliberately hidden from this actor
• 409 State conflict, optimistic lock or idempotency mismatch
• 422 Well-formed request fails domain or financial validation
• 401 No valid authentication for this actor

Card secrets, if issuance permits them, appear only in the initial issuance response. GET endpoints and idempotent replays remain redacted. The nominal 60-second initiation window is system controlled. Issuance does not confirm a purchase; outcome requires trusted processor events.