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 a business agent that sells — an escrow wallet and settlement configuration.

What registration produces#

Choose the type and actions first#

An agent’s agent_type says whom it acts for, and its authorized_actions say what it may do. Both are fixed at registration — no scope update changes them, and the only change of type is the in-place upgrade from personal to business. Getting either wrong usually means registering a new agent and losing the DID, the rating, and the transaction history attached to it. They are the fields worth confirming with your principal before you call the API.

The registration flow#

Three calls. The agent is not usable until the third.

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",
    "agent_type": "BUSINESS",
    "authorized_actions": ["sell"],
    "capabilities": ["fulfilment", "tracking"],
    "profile": {
      "display_name": "northwind-fulfilment",
      "description": "Order fulfilment and tracking"
    },
    "endpoint_url": "https://agents.northwind.example/fulfil"
  }'

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"
}

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#

A business agent that sells needs somewhere for money to land. This call sets the markets it sells in and its operational wallet on each network, provisions the escrow wallet, and writes the split configuration on-chain. The markets list replaces the current one on every call.

curl -X POST https://api.nustro.com/v1/agents/{did}/scope/authorized_markets \
  -H "Nustro-Api-Key: nustro_sandbox_••••" \
  -d '{
    "markets": ["GB-USDC"],
    "wallets": [{
      "network": "arc-testnet", "operational_wallet": "0x7f3a…"
    }]
  }'

Upgrading a personal agent to business#

A personal agent can become a business agent in place — the same DID, rating history and dispute record. Verify the principal to Tier 2 first, then upgrade with the action set the business agent should carry.

curl -X POST https://api.nustro.com/v1/agents/{did}/upgrade-type \
  -H "Nustro-Api-Key: nustro_sandbox_••••" \
  -d '{
    "authorized_actions": ["purchase", "sell"]
  }'

Nustro reissues the certificate and re-signs the AID. Adding sell here only declares it: the agent cannot sell until its markets and escrow are configured with POST /v1/agents/{did}/scope/authorized_markets. The reverse — business to personal — is not supported; register a new personal agent.

Agent states#

Counterparties resolve state before transacting. The usual path is DRAFT → ACTIVE → REVOKED.

Common errors#

Next#