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.
You are the Platform. You will register a principal, register and activate two agents under it, and let them transact with each other. In production those two agents would belong to different principals on your platform; here, 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 provider’s operational wallet. 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. In sandbox you can register one with a placeholder attestation — in production this is where your Verifier’s attestation goes.
curl -X POST https://api.nustro.com/v1/principals \
-H "Nustro-Api-Key: nustro_sandbox_••••" \
-H "Idempotency-Key: 8f2c1a90-4d3e-4b77-9c11-2ad5e6b70f31" \
-d '{
"legal_name": "Northwind Operations Ltd",
"country": "GB",
"external_ref": "crm-00417"
}'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 provider agent
Registration returns the agent in DRAFT. It has an identity but no keys and no
certificate, so it cannot yet do anything.
curl -X POST https://api.nustro.com/v1/agents \
-H "Nustro-Api-Key: nustro_sandbox_••••" \
-d '{
"principal_id": "prn_7c4e21",
"economic_role": "PROVIDER",
"profile": {
"display_name": "northwind-fulfilment"
},
"endpoint_url": "https://agents.example/fulfil",
"scope": {
"authorized_actions": ["sell"],
"capabilities": ["fulfilment"],
"dispute_window_days": 7
}
}'economic_role is immutable, and role and authorized_actions must agree — a
PROVIDER must include sell and must not include purchase. Getting this
wrong means a new agent and a new DID, so confirm the role 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"
}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.
A compliant platform MUST NOT activate an agent whose principal’s attestation is below the role’s required tier — Tier 2 for a provider. Nustro will not reject the call for you. In sandbox there is nothing to gate; in production this check is yours.
4 · Configure settlement
Providers need somewhere for money to land. This call registers the market, provisions the escrow wallet, and registers the agent on that network’s settlement contract.
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…"
}'You get back escrow_wallet, settlement_contract, and register_tx. Keep all
three — they are what your dashboard and reconciliation will reference.
5 · Add a consumer and transact
Repeat steps 1–3 for a consumer agent — economic_role: "CONSUMER",
authorized_actions: ["purchase"], no market configuration — then write its
spend policy.
curl -X PATCH https://api.nustro.com/v1/agents/{did}/scope \
-H "Nustro-Api-Key: nustro_sandbox_••••" \
-d '{
"max_transaction_value": "150.00",
"min_counterparty_rating": 0.50
}'Now the agents transact with each other directly. Your platform is finished after discovery.
402. Nustro checks the consumer’s spend policy before minting the intent./v1/facilitate, which verifies the payment and opens the task. Only then does it deliver.Settlement verification gates delivery. If you take one thing from this
quickstart, take this: a provider 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 provider and none on the consumer |
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
Credentials, headers, environments, and the error model.
Real verification, the Verifier role, and the activation gate.
Learning what happened in the phases you are not in.
KYB, promotion, and the going-live checklist.
Promotion does not close it. The teams that have the easiest upgrades are the ones still running their integration tests here a year later.