ZK Agent Integration

This page documents the ZK agent flow for submitting proofs and receiving decisions without exposing raw scores.

Endpoints

Method	Endpoint	Description
GET	/api/v1/policies	Returns active policy hashes by context
POST	/api/v1/agent/submit	Submits a verified decision on-chain via relayer

Getting Policy Hashes

Use the policy listing endpoint to retrieve the correct policyHash for your context:

curl https://www.zkbasecred.xyz/api/v1/policies

200 OK

{
  "policies": [
    {
      "context": "allowlist.general",
      "policyHash": "sha256:<hash>",
      "normalizationVersion": "v1"
    }
  ]
}

Submit Decision On-Chain

POST

/api/v1/agent/submit

Submits a verified decision on-chain via the relayer wallet. The relayer pays gas and writes the decision to the DecisionRegistry contract on Base mainnet.

Request body

{
  "subject": "0xabc123...",
  "context": "allowlist.general",
  "decision": "ALLOW",
  "policyHash": "sha256:<policy-hash>",
  "proof": {
    "a": ["0x...", "0x..."],
    "b": [["0x...", "0x..."], ["0x...", "0x..."]],
    "c": ["0x...", "0x..."]
  },
  "publicSignals": ["<policyHash>", "<contextId>", "<decision>"]
}

Field	Type	Required	Description
subject	string	Yes	Wallet address
context	string	Yes	Decision context
decision	"ALLOW" | "DENY" | "ALLOW_WITH_LIMITS"	Yes	The decision to record
policyHash	string	Yes	Policy hash used for the decision
proof	{ a, b, c }	Yes	Groth16 proof in contract-ready format
publicSignals	[string, string, string]	Yes	[policyHash, contextId, decision]

Response

200 OK

{
  "success": true,
  "transactionHash": "0x...",
  "subjectHash": "0x<bytes32>",
  "contextBytes32": "0x<bytes32>",
  "policyHashBytes32": "0x<bytes32>"
}

Field	Type	Description
success	boolean	Whether the transaction was submitted
transactionHash	string	On-chain transaction hash
subjectHash	string	bytes32 hash of the subject
contextBytes32	string	bytes32 encoding of the context
policyHashBytes32	string	bytes32 encoding of the policy hash

Error responses

Status	Code	Description
400	INVALID_REQUEST	Missing or invalid fields
400	SUBMIT_ERROR	Invalid proof or mismatch
422	SUBMIT_ERROR	Transaction reverted on-chain
503	CONFIG_ERROR	Relayer not configured
500	SUBMIT_ERROR	Server error

Typical Agent Flow

1. Get policies — GET /api/v1/policies to fetch the current policyHash for your context.
2. Generate proof — POST /api/v1/decide-with-proof to evaluate the subject and get a ZK proof.
3. Submit on-chain — POST /api/v1/agent/submit to write the decision to the DecisionRegistry.

Notes

• The verifier expects Groth16 proofs in snarkjs format.
• Policy hashes are derived from the canonical policy definitions in the decision engine.
• The API will reject requests when the policy hash does not match the active policy for the requested context.
• The /agent/submit endpoint requires a configured relayer wallet (RELAYER_PRIVATE_KEY). If the relayer is not configured, the endpoint returns 503.