Agent-initiated transactions

An autonomous agent is simply another way to originate instructions. It goes through the same clearing core, the same conformance model and the same compliance checks as a human participant.

Capability intersection

An agent's mandate is limited to the overlap with its principal's capabilities, so an agent can never do more than the participant that authorised it. Say the mandate allows initiateTransaction up to a GBP cap. If the agent tries a transaction above the cap, or asks for a capability its principal doesn't have, it's rejected in the same way an over-scoped API key would be. The engine enforces this itself, so it doesn't rely on the caller behaving.

The human calling the API doesn't need any new capability to initiate a transaction as an agent, because the mandate carries the authorisation. To mint and manage agents you need manageOwnAgents, which every tenant admin has (just like manageOwnTeam and runOwnConformancePack).

Endpoints

Method	Path	Purpose
`POST`	`/api/v1/sandbox/agents`	Mint a sandbox agent identity and mandate, scoped to your own participant.
`GET`	`/api/v1/sandbox/agents`	List your sandbox agents.
`GET`	`/api/v1/sandbox/agents/{id}`	Get one agent by ID.
`POST`	`/api/v1/sandbox/agents/{id}/revoke`	Revoke a mandate.

There's also an addition to the transaction initiation request. The agent field is optional, and leaving it out changes nothing:

Code sample

POST https://sandbox-api.nuvante.io/api/v1/transactions
{
  "useCase": "redeem",
  "paymentReference": "AGENT-DVP-0001",
  "source": { "amount": "500.00", "asset": { "code": "GBPC", "issuer": "…" } },
  "target": { "amount": "500.00", "asset": { "code": "GBP" } },
  "agent": {
    "agentId": "did:sandbox:agent:323e4567:lxk9m2r4f1",
    "mandateProof": "sandbox-mandate-proof"
  }
}

Worked example: mint an agent, transact, and see an over-scope rejection

Mint a sandbox agent with a GBP 1,000 cap that can only initiateTransaction:

Code sample

POST https://sandbox-api.nuvante.io/api/v1/sandbox/agents
{
  "capabilities": { "initiateTransaction": true, "cancelOwnTransaction": false },
  "amountCapGbp": "1000.00",
  "expiresAt": "2026-09-19T00:00:00.000Z"
}

Code sample

{
  "data": {
    "agentId": "did:sandbox:agent:323e4567:lxk9m2r4f1",
    "participantId": "323e4567-e89b-42d3-a456-426614174002",
    "capabilities": { "initiateTransaction": true, "cancelOwnTransaction": false },
    "amountCapGbp": "1000.00",
    "expiresAt": "2026-09-19T00:00:00.000Z",
    "createdAt": "2026-08-19T11:04:33.000Z",
    "revokedAt": null
  }
}

Initiate a transaction under the cap and it goes through as normal. Then try one over the cap:

Code sample

POST https://sandbox-api.nuvante.io/api/v1/transactions
{
  "useCase": "redeem",
  "paymentReference": "AGENT-OVER-SCOPE-001",
  "source": { "amount": "5000.00", "asset": { "code": "GBPC", "issuer": "…" } },
  "target": { "amount": "5000.00", "asset": { "code": "GBP" } },
  "agent": {
    "agentId": "did:sandbox:agent:323e4567:lxk9m2r4f1",
    "mandateProof": "sandbox-mandate-proof"
  }
}

Code sample

HTTP 400
{
  "errors": [{ "code": "mandate_rejected", "message": "amount_exceeded" }]
}

The mandate check rejects the request, so the transaction never enters the clearing saga. The error message names the exact rule that failed, so your integration can show it to the user.

Portal

Tenant admins can mint, inspect and revoke sandbox agents at /agents in the portal. The page includes an over-scope walkthrough: set an amount cap, submit a transaction above it, and watch the rejection from start to finish.