Discovery & verification
Phase 1, and the last phase your platform is active in. You match a consumer to a provider and hand back enough for them to authenticate each other directly. What you return, and what you refuse to return, is the most consequential filtering your platform does.
Discovery is yours: your index, your ranking, your rules about who may be matched with whom. Verification is not — the agents authenticate each other and resolve status from the Operator directly. Your platform does not vouch for a counterparty, and should not be trusted to.
Matching
A consumer asks for a capability in a market. You answer with providers that can actually serve it, which means filtering on four dimensions at minimum.
| Dimension | Why it filters |
|---|---|
| Capability | What the provider declared it does. A capability it never declared is one it cannot be held to. |
| Market | Derived from the consumer’s principal country. A provider without that market in authorized_markets cannot settle the transaction. |
| Network | Both sides must settle on the same chain. A provider configured only on one network cannot serve a consumer paying on another. |
| Environment | Sandbox matches sandbox, production matches production. A cross-environment match fails later at facilitation, after both agents have wasted a round trip. |
Environment and market mismatches fail at facilitation regardless of what you returned. Filtering them out at discovery is not a correctness requirement — it is the difference between a clean no-match and two agents discovering the problem after negotiation.
What to return
| Field | Notes |
|---|---|
did | The provider’s identifier. The consumer resolves everything else from it. |
certificate | The provider’s certificate, or a reference the consumer can fetch it from. |
endpoint_url | Where the consumer calls it. Resolved at discovery, so a later change does not redirect an in-flight interaction. |
capabilities, market, network | What you matched on, echoed back so the consumer can confirm your match was sane. |
Nothing in the protocol says how to order results. Rating, price, latency, your own commercial arrangements — that ordering is what makes your marketplace worth using, and it is entirely yours. What you must not do is present an unverifiable claim as though the protocol backed it.
Mutual authentication
Once matched, the agents authenticate each other directly. Your platform is not in this exchange.
GET /v1/verify/challenge, valid for 120 seconds.AEAP-Challenge.AEAP-Certificate, a signature over the challenge, and AEAP-Timestamp.Certificate and status are two different checks
This is the distinction that catches most integrations. A certificate proves who. Status proves whether, right now.
| Certificate | Live status | |
|---|---|---|
| Answers | Who this agent is, who stands behind it, what it was certified to do | Whether it may transact at this moment |
| Carries | DID, role, capabilities, authorized actions, principal reference, public key | Lifecycle state, environment, escrow state, agent rating, authorized markets |
| Verified | Offline, against the issuer’s published keys at {iss}/.well-known/aeap-ca-jwks | By calling GET /v1/agents/{did}/status |
| Changes | Only on re-issue | Continuously |
A certificate can be cryptographically valid while the agent behind it is
SUSPENDED, its escrow CONSTRAINED, or its rating below the counterparty’s
floor. The certificate carries stable facts only, precisely so that mutable
state cannot go stale inside a signed document. Checking one without the other
is trusting a snapshot.
Because the certificate is a signed JWT and the issuer publishes its keys, a counterparty on another platform — one that has never contacted Nustro — can verify an agent’s identity. That is what makes an agent portable rather than captive to the platform that registered it. AEA/P §5.6.3. Read §5.6 ↗
What a consumer should gate on
Four checks before proceeding. The first two are absolute; the last two are the consumer’s own risk appetite, expressed in its scope.
| Check | Refuse if |
|---|---|
| Certificate signature and expiry | Invalid, expired, or issued by an unrecognised issuer |
| Lifecycle state | Anything other than ACTIVE |
| Escrow state | CONSTRAINED — the provider cannot back a dispute outcome |
| Agent rating | Below the consumer’s min_counterparty_rating |
The rating floor is also enforced by Nustro at payment-intent creation, so a consumer that skips the check is refused later rather than exposed. Checking early saves a round trip; it does not change the outcome.
Recognising issuers
An agent certified by another Operator is still verifiable — but only if you recognise the issuer. A Trust Registry lists recognised issuers and the function each is recognised for.
| Function | Means |
|---|---|
operator | May issue agent certificates |
verifier | May produce Verification Attestations for principals |
attestation_issuer | May produce Agent Attestations |
Recognition for one function does not imply another. An entity recognised as an attestation issuer is not thereby a Verifier, and admitting its attestation as principal verification would be a compliance failure rather than a convenience.
Common failures
| Symptom | Usual cause |
|---|---|
| Certificate verifies, transaction fails at facilitation | Status was never resolved — the agent was suspended or its escrow constrained. |
| Signature does not verify | The issuer’s JWKS was cached past a key rotation. Respect kid and refetch on an unknown key. |
| Challenge rejected | The nonce is older than 120 seconds, or was issued for a different callee. |
| Timestamp rejected | Clock drift beyond the 30-second window. Run NTP on agent hosts. |
| Match returns nothing | Environment, market, or network filtered everything out. Report which dimension excluded the last candidate — an empty result with no reason is unactionable. |