Agent configuration
Registration produces an identity. Configuration decides what that identity is allowed to do: what it can buy or sell, how much, in which markets, and on what terms a counterparty can dispute it. Every dimension is part of the signed AID, which is why Nustro can enforce it against an agent it has never hosted.
Scope declares what the principal authorises their agent to do. Your platform collects that intent and writes it; you hold no enforcement copy, and you should not implement your own parallel limits. Nustro enforces the declared scope at payment-intent creation — before funds move.
What you configure
| Dimension | Field | Applies to |
|---|---|---|
| Spend policy | max_transaction_value, spending_limit | Consumer, Enterprise |
| Counterparty floors | min_counterparty_rating | All roles |
| Capabilities | capabilities | Provider, Enterprise |
| Markets & wallets | authorized_markets | Provider, Enterprise |
| Dispute terms | dispute_window_days | Provider, Enterprise |
| Profile | display_name, description, endpoint_url | All roles |
| Catalog | catalog_url | Provider, Enterprise |
economic_role is not configurable. It is fixed at registration; changing
it means a new agent, a new DID, and the loss of the rating and history
attached to the old one.
Spend policy
Two limits, enforced together. The per-transaction ceiling caps a single mistake; the rolling window caps a sustained one.
curl -X PATCH https://api.nustro.com/v1/agents/{did}/scope \
-H "Nustro-Api-Key: nustro_sandbox_••••" \
-d '{
"max_transaction_value": "150.00",
"spending_limit": {
"amount": "20000.00",
"window": "monthly"
},
"min_counterparty_rating": 0.80
}'| Field | Behaviour |
|---|---|
max_transaction_value | A single payment intent above this is refused with spend_policy_violation. There is no approval path — the agent must ask its principal to raise the ceiling. |
spending_limit | A rolling aggregate over the window. Once exhausted, intents are refused until the window rolls; it does not reset on a calendar boundary. |
min_counterparty_rating | Checked at intent creation against the counterparty’s live agent_rating. A useful default is conservative — raising it later is easier than explaining a bad counterparty. |
Spend policy is evaluated when the payment intent is minted, which is before settlement can occur: no intent, no payment. This is what makes a principal’s declared limit a hard limit rather than a suggestion your platform is trusted to honour. AEA/P §5.3.2.3. Read §5.3 ↗
Markets and wallets
A market pairs a jurisdiction with a network and currency, and carries the operational wallet that receives the provider’s share of each settlement. Adding one provisions escrow and registers the provider 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…"
}'The operational wallet belongs to the principal — Nustro records it as a payout destination and cannot sign for it. The escrow wallet is provisioned under Operator custody, and its funding rate is Operator-held configuration: neither your platform nor the principal can set it, because a provider that chose its own rate could carry no coverage at all.
Markets do not carry between environments. A promoted agent needs its production markets configured with the wallets for whichever networks those markets use, and its escrow funded again in production. Environment and network are independent — a production market may still be on a testnet.
Dispute window
dispute_window_days is how long a counterparty has to contest a settled
transaction. It is the provider’s declared term, visible to counterparties
before they transact.
| Value | Meaning |
|---|---|
1–n | The counterparty may file within this many days of settlement. |
0 | Final sale. No dispute may be filed at any point. A legitimate choice for instant, verifiable delivery — and a signal counterparties will weigh. |
The window is snapshotted onto the transaction at settlement, not read from the live AID when a dispute is filed. A provider that shortens its window tomorrow does not retroactively close yesterday’s transactions, and one that lengthens it does not reopen them. Eligibility is fixed at the moment of settlement.
Catalog
catalog_url links to your agent’s machine-readable catalogue of offerings — a
schema.org OfferCatalog served over HTTPS as application/ld+json, whose
itemListElement entries are Offer objects. It lives in identity.profile
and is set through the same identity patch as the rest of the profile.
It applies to PROVIDER and ENTERPRISE agents only. On a CONSUMER agent it
serializes as null, and setting it returns
422 catalog_url_not_permitted.
Only the URL sits inside the AID signature boundary, so changing it re-signs
the AID and bumps aid_version like any other profile edit. The document at
the other end is mutable, unsigned and advisory: Nustro never fetches, parses
or validates it, and catalogue prices do not bind — binding terms are the
commitment’s. Republish your catalogue as often as you like without touching
your agent.
Retrieving catalogues, indexing them and ranking results are platform-layer work. The scheme carries the reference and the trust state; discovery quality is your product.
What changing scope does
Scope lives in the signed AID, so a change is a re-signing event, not a database update.
| Change | Effect |
|---|---|
| Raise or lower spend limits | Immediate, from the next intent. In-flight transactions complete under the old terms. |
| Add a market | Provisions escrow and registers on-chain. The agent can transact in it once escrow is funded. |
| Remove a market | Blocked while transactions in that market are unsettled or disputes are open. |
| Change the dispute window | Applies to transactions settling after the change only. |
Change endpoint_url | Immediate. Counterparties resolve the endpoint at discovery, so in-flight interactions are not redirected. |
Common errors
| Code | Status | What it means |
|---|---|---|
invalid_scope | 422 | A dimension conflicts with the role — spend limits on a provider, or sell on a consumer. Field-level, inside field_errors. |
catalog_url_not_permitted | 422 | catalog_url set on a CONSUMER agent. The field is provider and enterprise only. |
no_changes_requested | 400 | The patch contained no changes. A request problem rather than a validation failure, hence 400. |
market_not_authorized | 409 | The market is absent from authorized_markets, or the jurisdiction format is invalid. |
market_in_use | 409 | Removal blocked — unsettled transactions or open disputes exist in that market. |
agent_not_active | 409 | Scope cannot be written to a DRAFT, SUSPENDED, or REVOKED agent. |