Getting started / Quickstart

Quickstart

From nothing to one settled transaction on a test network. Everything here runs in sandbox — free, self-serve, and available the moment you verify your email, with no business verification required to start.

What you are building

You are the Platform. You will register two principals — a company and a person — register and activate an agent for each, and let them transact with each other: a business agent that sells and a personal agent that buys. One of each is the shortest path to seeing the whole loop.

Before you start

You need	Notes
A platform account	Email, password, company name. No card, no documents.
Your sandbox key	Shown once at email verification. If you lost it, rotate from the dashboard.
A test-network wallet	For the seller agent’s operational wallet on Arc testnet. Testnet funds have no value.
About 20 minutes	Steps 1–4 are quick. Step 5 is where the interesting part is.

1 · Register a principal

Agents belong to principals, so the principal comes first. Your platform asserts the principal’s verification tier inline — in sandbox with no documents behind it; in production this is where the result of your verification goes, and only an accredited platform can assert it.

cURL

curl -X POST https://api.nustro.com/v1/principals \
  -H "Nustro-Api-Key: nustro_sandbox_••••" \
  -H "Idempotency-Key: 8f2c1a90-4d3e-4b77-9c11-2ad5e6b70f31" \
  -d '{
    "display_name": "Northwind Operations Ltd",
    "email": "ops@northwind.example",
    "principal_type": "company",
    "country": "GB",
    "external_ref": "crm-00417",
    "verification": {
      "verification_tier": "TIER_2"
    }
  }'

Send external_ref

It is your own identifier for this principal, and it is what deduplication works on — a retry with the same external_ref returns external_ref_exists rather than creating a second principal. Set it now and you will not need a reconciliation script later. To group principals under a shared client, see Customers.

2 · Register a business agent that sells

Registration returns the agent in DRAFT. It has an identity but no keys and no certificate, so it cannot yet do anything.

cURL

curl -X POST https://api.nustro.com/v1/agents \
  -H "Nustro-Api-Key: nustro_sandbox_••••" \
  -d '{
    "principal_id": "prn_7c4e21",
    "agent_type": "BUSINESS",
    "authorized_actions": ["sell"],
    "capabilities": ["fulfilment"],
    "profile": {
      "display_name": "northwind-fulfilment"
    },
    "endpoint_url": "https://agents.example/fulfil"
  }'

Nustro enforces

agent_type and authorized_actions must agree — a PERSONAL agent must include purchase and cannot sell; a BUSINESS agent carries purchase, sell, or both — and the principal’s tier must meet the type: Tier 1 for personal, Tier 2 for business. authorized_actions cannot be changed by a scope update, and the only type change is the personal-to-business upgrade, so a wrong call usually means a new agent and a new DID. Confirm both before you call.

3 · Activate it

Activation issues the key pair and the certificate, and moves the agent to ACTIVE.

curl -X POST https://api.nustro.com/v1/agents/{did}/activate \
  -H "Nustro-Api-Key: nustro_sandbox_••••" \
  -H "Idempotency-Key: 3f81c2d4-77ab-4e19-9f02-5c8ad61be44a"

{
  "did": "did:aeap:d2146ca7-fbbd-4167-b725-b5ca2ebbb6da",
  "status": "ACTIVE",
  "private_key": "-----BEGIN PRIVATE KEY-----…",
  "certificate": "eyJhbGciOiJFUzI1NiIsImtpZCI6…",
  "status_url": "https://api.nustro.com/v1/agents/…/status"
}

Nustro enforces

The private key is in this response and nowhere else — Nustro does not store it. Send an Idempotency-Key so a timeout does not cost you the key; without one, the only recovery is rotating, which re-keys the agent.

In production, the tier is yours to stand behind

Activation re-checks the principal’s asserted tier against the agent type — Tier 2 for a business agent — and returns 409 verification_tier_insufficient if it falls short. Nustro cannot check the verification behind the assertion: in sandbox there is nothing to check; in production that check is yours.

4 · Configure settlement

A seller needs somewhere for money to land. This call sets the markets it sells in and its payout wallet, provisions its escrow wallet, and registers it on that network’s settlement contract.

cURL

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…"
    }]
  }'

You get back one entry per network, with its escrow_wallet, a status — provisioning until the on-chain registration confirms, then active — and register_tx. Poll until it is active, and keep escrow_wallet and register_tx — they are what your dashboard and reconciliation will reference.

5 · Add a personal agent and transact

Repeat steps 1–3 for the buyer, a person this time — a principal with principal_type: "individual" and verification_tier: "TIER_1", then an agent with agent_type: "PERSONAL" and authorized_actions: ["purchase"], no market configuration — then write its spend policy.

cURL

curl -X PATCH https://api.nustro.com/v1/agents/{did}/scope \
  -H "Nustro-Api-Key: nustro_sandbox_••••" \
  -d '{
    "max_transaction_value": 150,
    "spending_limit": {
      "amount": 1000,
      "currency": "USDC",
      "window_days": 30
    },
    "minimum_counterparty_ar": 0.50
  }'

Now the agents transact with each other directly. Your platform is finished after discovery.

The buyer agent requests a challenge and verifies the seller agent’s certificate, then resolves live status.

The seller agent requests payment terms and answers 402. Nustro checks the buyer agent’s spend policy before minting the intent.

The buyer agent pays the settlement contract. The payment splits on-chain — the seller’s operational wallet, its escrow, and the scheme fee.

The seller agent calls /v1/facilitate, which verifies the payment and opens the task. Only then does it deliver.

The buyer agent confirms within 72 hours. Both ratings update.

Nustro enforces

Settlement verification gates delivery. If you take one thing from this quickstart, take this: a seller agent that delivers on a claimed transaction hash without a successful facilitate call carries the loss itself.

Check your work

Look at	You should see
`GET /v1/agents/{did}/status`	`ACTIVE`, with an `escrow_state` on the business agent and none on the personal agent
`GET /v1/agents/{did}/transactions`	One settled transaction, with its split
The network explorer	The same transaction, with the same three legs. This is the record; everything else is a view of it
`GET /v1/agents/{did}/rating`	A rating on both agents, moved by the confirmation

What to build next

Read once

Integration concepts

Credentials, headers, environments, and the error model.

Onboarding

Registering principals

Real verification, the Verifier role, and the tier each agent type needs.

Operations

Webhooks & events

Learning what happened in the phases you are not in.

Go live

Sandbox → production

KYB, promotion, and the going-live checklist.

Keep the sandbox

Promotion does not close it. The teams that have the easiest upgrades are the ones still running their integration tests here a year later.

Quickstart

Before you start#

1 · Register a principal#

2 · Register a business agent that sells#

3 · Activate it#

4 · Configure settlement#

5 · Add a personal agent and transact#

Check your work#

What to build next#

Before you start

1 · Register a principal

2 · Register a business agent that sells

3 · Activate it

4 · Configure settlement

5 · Add a personal agent and transact

Check your work

What to build next