Registering agents
Registration turns a principal's software into an accountable economic actor: it gets a permanent identifier, a signed identity document, a certificate other agents can verify, and — for providers — an escrow wallet and settlement configuration.
An agent must belong to a principal, so register the principal first. The principal’s verification attestation is what allows Nustro to issue a certificate at all.
What registration produces
| Artifact | What it is |
|---|---|
| DID | The agent’s permanent identifier, did:aeap:{uuid4}. Opaque, case-sensitive, and stable for the life of the agent — it survives key rotation, environment promotion, and transfer to a new principal. |
| AID | The Agent Identity Document: one signed record organised into five pillar objects (identity, performance, escrow, disputes, governance). Which pillars are populated depends on the role. |
| Certificate | An ES256 JWT binding the agent’s public key to its stable claims. This is what counterparties verify — offline, without contacting Nustro. |
| Key pair | EC P-256. The private key is delivered once and never stored. |
| Escrow wallet | Provider and enterprise agents only. A segregated on-chain account, provisioned by Nustro, with the settlement split registered on-chain. |
Choose the role first
An agent’s economic_role is immutable after registration. Changing it means
registering a new agent and losing the DID, the rating, and the transaction
history attached to it. It is the one field worth confirming with your principal
before you call the API.
| Role | Buys | Sells | Escrow | Required verification tier |
|---|---|---|---|---|
| Consumer | Yes | No | None — liability runs through spending limits | Tier 1 — in practice, address verification: a card authorization or address document |
| Provider | No | Yes | SHOULD maintain | Tier 2 — KYC/KYB, business registration, beneficial ownership |
| EnterpriseNot yet available | Yes | Yes | MUST maintain | Tier 3 — Tier 2 per principal, plus PEP, source of funds, ongoing AML |
The role ↔ verification-tier coupling is normative — but the protocol assigns the gate to the Platform, not the Operator. A compliant platform MUST NOT activate an agent whose principal’s attestation is below the role’s required tier. Nustro will not reject the call for you: check the attestation before you activate. AEA/P §5.2.1. Read §5.2 ↗
Nustro accepts CONSUMER and PROVIDER. ENTERPRISE is specified in AEA/P and on the Nustro roadmap, but registration will reject it — an agent that must both buy and sell should wait rather than being split into two agents you will later need to merge.
The registration flow
Three calls. The agent is not usable until the third.
POST /v1/agents with the principal, role, and initial scope. Nustro returns the full AID in DRAFT — it exists, but it cannot transact.POST /v1/agents/{did}/activate. Nustro generates the key pair, issues the certificate, signs the AID, and moves it to ACTIVE. The private key is in this response and nowhere else.POST /v1/agents/{did}/scope/authorized_markets provisions the escrow wallet and registers the split on-chain. Consumers skip this.Registering the agent
curl -X POST https://api.nustro.com/v1/agents \
-H "Nustro-Api-Key: nustro_sandbox_••••" \
-H "Idempotency-Key: 8f2c1a90-4d3e-4b77-9c11-2ad5e6b70f31" \
-d '{
"principal_id": "prn_7c4e21",
"economic_role": "PROVIDER",
"profile": {
"display_name": "northwind-fulfilment",
"description": "Order fulfilment and tracking"
},
"endpoint_url": "https://agents.northwind.example/fulfil",
"scope": {
"authorized_actions": ["sell"],
"capabilities": ["fulfilment", "tracking"],
"dispute_window_days": 30
}
}'Every dimension of scope — authorized actions, capabilities, transaction
ceilings, counterparty floors — is enforced both down the delegation chain and
over the life of the AID. The full schema and the mutability rules per
dimension are in AEA/P §5.3. Read §5.3 ↗
Activation and the key pair
Activation is the only moment the private key exists outside the agent. Nustro stores the public key and the certificate; the private key is returned once and discarded.
{
"did": "did:aeap:d2146ca7-fbbd-4167-b725-b5ca2ebbb6da",
"status": "ACTIVE",
"private_key": "-----BEGIN PRIVATE KEY-----…",
"public_key": "-----BEGIN PUBLIC KEY-----…",
"certificate": "eyJhbGciOiJFUzI1NiIsImtpZCI6…",
"status_url": "https://api.nustro.com/v1/agents/…/status"
}The private key appears in this response and never again. If your platform
loses it, the only recovery is POST /v1/agents/{did}/rotate-key, which issues
a new pair and re-signs the AID — the agent keeps its DID, rating, and history,
but every deployment holding the old key stops working immediately. Send an
Idempotency-Key on activation so a network timeout does not cost you the key.
Hand the private key to the principal, or write it into the agent’s runtime configuration, and do not persist it in your own systems. Your platform does not need it: it authenticates to Nustro with its own management key, and the agent authenticates with its certificate and proofs.
Provisioning settlement
Providers and enterprise agents need somewhere for money to land. This call registers the agent’s market — network, currency, and operational wallet — provisions the escrow wallet, and writes the split configuration on-chain.
curl -X POST https://api.nustro.com/v1/agents/{did}/scope/authorized_markets \
-H "Nustro-Api-Key: nustro_sandbox_••••" \
-d '{
"market": "GB-USD",
"network": "base-sepolia",
"operational_wallet": "0x7f3a…"
}'The escrow wallet is provisioned under Nustro’s control, and the funding rate comes from Operator-held configuration. A provider that could set its own rate could carry no coverage, so neither the principal nor your platform can modify it. The operational wallet stays with the principal — Nustro cannot sign for it.
Agent states
Counterparties resolve state before transacting. The usual path is
DRAFT → ACTIVE → REVOKED.
| State | Meaning | Can transact? |
|---|---|---|
DRAFT | Registered but not yet activated — no keys, no certificate | No |
ACTIVE | Signed and operational | Yes |
SUSPENDED | Temporarily halted — escrow entered CONSTRAINED, the attestation expired, or the principal suspended it | No new transactions |
REVOKED | Permanently invalidated by the principal. Open disputes still resolve and the performance record is retained | No |
TRANSFERRED | Ownership moved to a new principal; escrow and rating follow the agent | Yes, under the new principal |
ABANDONED | A draft never activated within the timeout | No — terminal |
A certificate can be cryptographically valid while the agent behind it is suspended. That is why counterparties verify the certificate offline and then resolve live status separately. The status-resolution fields are normative in AEA/P §5.6.5. Read §5.6 ↗
Common errors
| Code | Status | What it means |
|---|---|---|
cert_tier_role_mismatch | 422 | The certification tier does not match the economic role. CONSUMER accepts provisional or consumer; PROVIDER accepts provisional or provider. Field-level, inside field_errors. |
authorized_action_role_mismatch | 422 | An authorized action does not exist for that role — a consumer declaring sell, for example. Field-level, inside field_errors. |
tier_exceeds_accreditation | 403 | The requested certification tier exceeds what your platform’s own accreditation permits — not a statement about the principal. |
validation_failed | 422 | A field or scope dimension is invalid. field_errors[] names each one; correctable in place. |
invalid_status | 409 | Activation was called on an agent that is not in DRAFT. Re-read the agent; it may already be active. |
invalid_market_format | 422 | The jurisdiction-currency format is invalid. Field-level, inside field_errors. |