feat(types): integrate risk_payload into mandates and add CREDENTIAL_CHECK condition

Incorporates two contributions from @ayushozha's work on PR google-agentic-commerce#187 and
their analysis on Issue google-agentic-commerce#163:

1. Wire risk_payload as an optional field into IntentMandate, CartMandate,
   and PaymentMandateContents, so risk signals travel with the mandate chain
   rather than as a separate DataPart. This closes the spec-implementation
   gap identified in Section 7.4 (lines 298-299, 321-322).

2. Add CREDENTIAL_CHECK as a new TripConditionType for static identity
   verification (e.g., on-chain wallet attestations, KYB credentials).
   This addresses the Section 7.4 gap between behavioral risk (what the
   agent does) and identity risk (what the agent is).

Includes Python tests, Go type updates, and documentation for both changes.

Refs: google-agentic-commerce#163, google-agentic-commerce#187

Co-Authored-By: ayushozha <7945279+ayushozha@users.noreply.github.com>

Author: ravyg

docs/topics/fiduciary-circuit-breaker.md

@@ -98,6 +98,32 @@ Trip conditions are predicate functions that evaluate agent behavior:
 | `TIME_BASED` | Action during restricted period | Trade outside market hours |
 | `DEVIATION` | Significant departure from baseline | Price 30% below historical average |
 | `VENDOR_TRUST` | Untrusted counterparty | New vendor in high-risk region |
+| `CREDENTIAL_CHECK` | Static identity/credential verification | Agent wallet holds KYB attestation |
+
+## Identity vs. Behavioral Risk
+
+AP2 Section 7.4 identifies two complementary dimensions of risk in agent transactions:
+
+### Behavioral Risk (Runtime)
+
+Most trip conditions (`VALUE_THRESHOLD`, `VELOCITY`, `ANOMALY`, etc.) evaluate **what the agent does** — its runtime behavior against predefined thresholds. These are dynamic checks that may change with every transaction.
+
+### Identity Risk (Static)
+
+The `CREDENTIAL_CHECK` trip condition evaluates **what the agent is** — its identity, credentials, and trust signals. This addresses the spec's call-out that "the Shopping Agent's ID becomes synonymous with a bot's identity, which requires new methods of verification and trust."
+
+Examples of credential checks:
+
+- Agent wallet holds governance tokens from a recognized DAO
+- Agent has a KYB (Know Your Business) attestation via [EAS](https://attest.org/) on Base
+- Agent presents a W3C Verifiable Credential from a trusted issuer
+- Agent identity is registered in a trust registry
+
+Credential check results use the standard `TripConditionResult` structure. The `message` field carries human-readable verification details, while implementation-specific data (attestation UIDs, chain references, credential schemas) should flow through `RiskPayload.custom_signals` to keep the core types ecosystem-agnostic.
+
+!!! note
+
+    Future versions may separate identity evaluation into its own dimension within `RiskPayload` (e.g., `identity_evaluation`) to provide richer type support for credential data shapes that differ from behavioral thresholds.
 
 ## Usage in AP2 Messages
 
@@ -279,6 +305,12 @@ riskPayload.AgentID = &agentID
 - Confidence that agents operate within guardrails
 - Human oversight for exceptional cases
 
+## Risk Payload in Mandates
+
+As of v0.1-alpha, `RiskPayload` can be included directly on `IntentMandate`, `CartMandate`, and `PaymentMandateContents` via the optional `risk_payload` field. This allows risk signals to travel with the mandate chain, giving networks and issuers structured visibility into the agent's governance state at mandate-signing time.
+
+The `risk_payload` field is fully optional — mandates without it remain valid, ensuring backward compatibility.
+
 ## References
 
 - [AP2 Specification Section 7.4: Risk Signals](../specification.md#74-risk-signals)

samples/go/pkg/ap2/types/risk.go

@@ -62,6 +62,9 @@ const (
 	// TripConditionVendorTrust - Transaction with untrusted counterparty.
 	TripConditionVendorTrust TripConditionType = "VENDOR_TRUST"
 
+	// TripConditionCredentialCheck - Static identity/credential verification (e.g., wallet attestation, KYB check).
+	TripConditionCredentialCheck TripConditionType = "CREDENTIAL_CHECK"
+
 	// TripConditionCustom - Implementation-specific trip condition.
 	TripConditionCustom TripConditionType = "CUSTOM"
 )

samples/go/pkg/ap2/types/risk_test.go

@@ -29,6 +29,7 @@ func TestTripConditionTypes(t *testing.T) {
 		TripConditionTimeBased,
 		TripConditionDeviation,
 		TripConditionVendorTrust,
+		TripConditionCredentialCheck,
 		TripConditionCustom,
 	}
 
@@ -45,6 +46,9 @@ func TestTripConditionTypes(t *testing.T) {
 	if TripConditionCumulativeThreshold != "CUMULATIVE_THRESHOLD" {
 		t.Errorf("Expected CUMULATIVE_THRESHOLD, got %s", TripConditionCumulativeThreshold)
 	}
+	if TripConditionCredentialCheck != "CREDENTIAL_CHECK" {
+		t.Errorf("Expected CREDENTIAL_CHECK, got %s", TripConditionCredentialCheck)
+	}
 }
 
 func TestFCBStates(t *testing.T) {

src/ap2/types/mandate.py

@@ -21,6 +21,7 @@
 from ap2.types.payment_request import PaymentItem
 from ap2.types.payment_request import PaymentRequest
 from ap2.types.payment_request import PaymentResponse
+from ap2.types.risk import RiskPayload
 from pydantic import BaseModel
 from pydantic import Field
 
@@ -74,6 +75,13 @@ class IntentMandate(BaseModel):
       ...,
       description="When the intent mandate expires, in ISO 8601 format.",
   )
+  risk_payload: Optional[RiskPayload] = Field(
+      None,
+      description=(
+          "Optional structured risk payload containing the current risk"
+          " assessment state as defined in Section 7.4."
+      ),
+  )
 
 
 class CartContents(BaseModel):
@@ -111,6 +119,13 @@ class CartMandate(BaseModel):
   """
 
   contents: CartContents = Field(..., description="The contents of the cart.")
+  risk_payload: Optional[RiskPayload] = Field(
+      None,
+      description=(
+          "Optional structured risk payload containing the current risk"
+          " assessment state as defined in Section 7.4."
+      ),
+  )
   merchant_authorization: Optional[str] = Field(
       None,
       description=(""" A base64url-encoded JSON Web Token (JWT) that digitally
@@ -154,6 +169,13 @@ class PaymentMandateContents(BaseModel):
       ),
   )
   merchant_agent: str = Field(..., description="Identifier for the merchant.")
+  risk_payload: Optional[RiskPayload] = Field(
+      None,
+      description=(
+          "Optional structured risk payload containing the current risk"
+          " assessment state as defined in Section 7.4."
+      ),
+  )
   timestamp: str = Field(
       description=(
           "The date and time the mandate was created, in ISO 8601 format."

src/ap2/types/risk.py

@@ -74,6 +74,9 @@ class TripConditionType(str, Enum):
     VENDOR_TRUST = "VENDOR_TRUST"
     """Transaction with unverified or untrusted counterparty."""
 
+    CREDENTIAL_CHECK = "CREDENTIAL_CHECK"
+    """Static identity/credential verification (e.g., wallet attestation, KYB check)."""
+
     CUSTOM = "CUSTOM"
     """Implementation-specific trip condition."""
 

tests/test_risk.py

@@ -47,6 +47,7 @@ def test_all_types_exist(self):
             "TIME_BASED",
             "DEVIATION",
             "VENDOR_TRUST",
+            "CREDENTIAL_CHECK",
             "CUSTOM",
         ]
         actual = [e.value for e in TripConditionType]
@@ -57,6 +58,18 @@ def test_string_values(self):
         assert TripConditionType.VALUE_THRESHOLD == "VALUE_THRESHOLD"
         assert TripConditionType.CUMULATIVE_THRESHOLD == "CUMULATIVE_THRESHOLD"
         assert TripConditionType.VELOCITY == "VELOCITY"
+        assert TripConditionType.CREDENTIAL_CHECK == "CREDENTIAL_CHECK"
+
+    def test_credential_check_in_trip_result(self):
+        """Test CREDENTIAL_CHECK can be used in a TripConditionResult."""
+        result = TripConditionResult(
+            condition_type=TripConditionType.CREDENTIAL_CHECK,
+            status=TripConditionStatus.PASS,
+            message="Agent wallet holds valid KYB attestation via EAS on Base",
+            suggestion=None,
+        )
+        assert result.condition_type == TripConditionType.CREDENTIAL_CHECK
+        assert result.status == TripConditionStatus.PASS
 
 
 class TestTripConditionStatus:
@@ -460,3 +473,109 @@ def test_b2b_quote_scenario(self):
         json_output = json.loads(payload.model_dump_json())
         assert json_output["fcb_evaluation"]["fcb_state"] == "HALF_OPEN"
         assert json_output["custom_signals"]["negotiation_rounds"] == 3
+
+
+class TestMandateRiskPayloadIntegration:
+    """Tests for risk_payload integration into mandate types."""
+
+    def test_intent_mandate_with_risk_payload(self):
+        """Test IntentMandate accepts optional risk_payload."""
+        from ap2.types.mandate import IntentMandate
+
+        payload = RiskPayload(
+            agent_modality=AgentModality.HUMAN_NOT_PRESENT,
+            agent_id="shopping-agent-001",
+        )
+        mandate = IntentMandate(
+            natural_language_description="Red basketball shoes under $200",
+            intent_expiry="2026-03-01T00:00:00Z",
+            risk_payload=payload,
+        )
+        assert mandate.risk_payload is not None
+        assert mandate.risk_payload.agent_id == "shopping-agent-001"
+
+    def test_intent_mandate_without_risk_payload(self):
+        """Test IntentMandate works without risk_payload (backward compat)."""
+        from ap2.types.mandate import IntentMandate
+
+        mandate = IntentMandate(
+            natural_language_description="Red basketball shoes",
+            intent_expiry="2026-03-01T00:00:00Z",
+        )
+        assert mandate.risk_payload is None
+
+    def test_cart_mandate_with_risk_payload(self):
+        """Test CartMandate accepts optional risk_payload."""
+        from ap2.types.mandate import CartContents, CartMandate
+        from ap2.types.payment_request import (
+            PaymentCurrencyAmount,
+            PaymentDetailsInit,
+            PaymentItem,
+            PaymentRequest,
+        )
+
+        payload = RiskPayload(
+            fcb_evaluation=FCBEvaluation(
+                fcb_state=FCBState.CLOSED,
+                trips_evaluated=3,
+                trips_triggered=0,
+            ),
+            agent_modality=AgentModality.HUMAN_NOT_PRESENT,
+        )
+        cart_contents = CartContents(
+            id="cart-001",
+            user_cart_confirmation_required=True,
+            payment_request=PaymentRequest(
+                method_data=[],
+                details=PaymentDetailsInit(
+                    id="details-001",
+                    display_items=[],
+                    total=PaymentItem(
+                        label="Total",
+                        amount=PaymentCurrencyAmount(
+                            currency="USD", value="100.00"
+                        ),
+                    ),
+                ),
+            ),
+            cart_expiry="2026-03-01T00:00:00Z",
+            merchant_name="Test Merchant",
+        )
+        mandate = CartMandate(
+            contents=cart_contents,
+            risk_payload=payload,
+        )
+        assert mandate.risk_payload is not None
+        assert mandate.risk_payload.fcb_evaluation.fcb_state == FCBState.CLOSED
+
+    def test_payment_mandate_contents_with_risk_payload(self):
+        """Test PaymentMandateContents accepts optional risk_payload."""
+        from ap2.types.mandate import PaymentMandateContents
+        from ap2.types.payment_request import (
+            PaymentCurrencyAmount,
+            PaymentItem,
+            PaymentResponse,
+        )
+
+        payload = RiskPayload(
+            agent_modality=AgentModality.HUMAN_NOT_PRESENT,
+            agent_id="b2b-agent-001",
+            cumulative_session_value=235000.0,
+            transaction_count_today=4,
+        )
+        contents = PaymentMandateContents(
+            payment_mandate_id="pm-001",
+            payment_details_id="pd-001",
+            payment_details_total=PaymentItem(
+                label="Total",
+                amount=PaymentCurrencyAmount(currency="USD", value="85000.00"),
+            ),
+            payment_response=PaymentResponse(
+                request_id="req-001",
+                method_name="basic-card",
+            ),
+            merchant_agent="merchant-001",
+            risk_payload=payload,
+        )
+        assert contents.risk_payload is not None
+        assert contents.risk_payload.cumulative_session_value == 235000.0