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 | Agents that buy |
| Counterparty floors | minimum_counterparty_ar, minimum_counterparty_cert_tier | All agents |
| Capabilities | capabilities | Agents that sell |
| Markets & wallets | authorized_markets | Agents that sell |
| Dispute terms | dispute_window_days | Agents that sell |
| Profile | display_name, description, endpoint_url | All agents |
| Catalog | catalog_url | Agents that sell |
agent_type and authorized_actions are not configurable — a scope patch
that sends either is rejected. Both are fixed at registration; the one change is
the personal-to-business upgrade, POST /v1/agents/{did}/upgrade-type. Anything
else 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,
"spending_limit": {
"amount": 20000,
"currency": "USDC",
"window_days": 30
},
"minimum_counterparty_ar": 0.80
}'| Field | Behaviour |
|---|---|
max_transaction_value | A single payment intent above this is refused with spend_policy_violation; detail.failed_check names the check that failed. There is no approval path — the agent must ask its principal to raise the ceiling. |
spending_limit | A rolling aggregate over window_days, in one currency. Once exhausted, intents are refused until the window rolls; it does not reset on a calendar boundary. Applies to what the agent buys only — a business agent’s sales never count against it. |
minimum_counterparty_ar | Checked at intent creation against the counterparty’s live Agent Rating. Defaults to 0.75. A useful default is conservative — raising it later is easier than explaining a bad counterparty. |
minimum_counterparty_cert_tier | The lowest certificate tier a counterparty may hold — provisional, personal or business. Checked with the rating; both are reported as counterparty_floor. |
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 currency — GB-USDC, or GLOBAL-USDC for
everywhere. Wallets are set per network: the operational wallet on each network
receives the seller’s share of each settlement. One call sets both, and markets
is the full list — it replaces the current one. The first wallet on a network
provisions escrow there and registers the seller 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 '{
"markets": ["GB-USDC", "IE-USDC"],
"wallets": [{
"network": "arc-testnet", "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 seller 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 buyer has to contest a settled
transaction. It is the seller’s declared term, visible to counterparties
before they transact.
| Value | Meaning |
|---|---|
1–n | The buyer 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 seller 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 agents that sell only. On an agent that doesn’t sell 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 |
|---|---|---|
field_not_allowed_for_type | 422 | A dimension that does not fit the agent’s actions — authorized_markets on an agent that doesn’t sell, for example. Field-level, inside field_errors. |
validation_failed | 422 | authorized_actions sent in a scope patch. It is fixed at registration; named in field_errors. |
catalog_url_not_permitted | 422 | catalog_url set on an agent that doesn’t sell. The field is for agents that sell 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. |