AgentScore Gate

​

How it works

1. An agent requests a purchase or action from your service
2. Your service calls AgentScore to verify the operator’s identity
3. AgentScore returns allow or deny based on your compliance policy
4. If denied, the operator can self-serve verify via a URL you provide

​

Define your compliance policy

{
  "require_kyc": true,
  "require_sanctions_clear": true,
  "min_age": 21,
  "allowed_jurisdictions": ["US"]
}

​

Check identity at transaction time

import { AgentScore } from '@agent-score/sdk';

const agentscore = new AgentScore({ apiKey: process.env.AGENTSCORE_API_KEY });

const policy = {
  require_kyc: true,
  require_sanctions_clear: true,
  min_age: 21,
  allowed_jurisdictions: ['US'],
};

// In your request handler
const walletAddress = req.headers['x-wallet-address'];
const operatorToken = req.headers['x-operator-token'];

const result = walletAddress
  ? await agentscore.assess(walletAddress, { policy })
  : await agentscore.assess(null, { operatorToken, policy });

if (result.decision === 'deny') {
  return res.status(403).json({
    error: 'compliance_denied',
    reasons: result.decision_reasons,
    verify_url: result.verify_url,
  });
}

// Identity verified, proceed with transaction

import { Hono } from 'hono';
import { agentscoreGate } from '@agent-score/commerce/identity/hono';

const app = new Hono();
app.use('*', agentscoreGate({
  apiKey: process.env.AGENTSCORE_API_KEY!,
  requireKyc: true,
  requireSanctionsClear: true,
  minAge: 21,
  allowedJurisdictions: ['US'],
}));

​

Per-product policy + soft mode (commerce SDK)

• PolicyBlock: typed shape carrying enforcement (hard | soft | absent), require_kyc, require_sanctions_clear, min_age, allowed_jurisdictions, allowed_shipping_countries, allowed_shipping_states. Vendors usually source these from a database row (one column per field).
• build_gate_from_policy(policy, *, api_key); translates a block into an AgentScoreGate. Returns None when the block has no enforcement set, signalling “no gate; identity_status=‘anonymous’”.
• run_gate_with_enforcement(request, gate, *, enforcement); runs the gate. On hard denial it returns status="denied" with a denial_status and denial_body for the caller to propagate. On soft denial it swallows the 403 and returns status="unverified" so the order completes with a degraded identity stamp. On success: status="verified". No gate: status="anonymous".

• PolicyBlock: same fields in camelCase (enforcement, requireKyc, requireSanctionsClear, minAge, allowedJurisdictions, allowedShippingCountries, allowedShippingStates).
• buildGateFromPolicy(policy, { apiKey }): translates a block into the options object the per-framework agentscoreGate(...) accepts (the Node SDK builds gates per framework; Hono, Express, Fastify, Next.js, Web; so the policy module emits options rather than a constructed gate, mirroring python’s build_gate_from_policy verb pattern). Returns null when no enforcement.
• runGateWithEnforcement(enforcement, runGate): wraps the per-framework middleware in the hard/soft enforcement runner. The vendor passes a runGate adapter that resolves to { ok: true } on accept or { ok: false, status, body } on deny; the runner returns a structured GateResult.

• shipping{Country,State}Allowed(...): per-product shipping allowlists. Country list is hard-enforced regardless of identity strictness; state list only fires for US shipments (e.g. wine).

​

Handle unverified operators

{
  "decision": "deny",
  "decision_reasons": ["kyc_required"],
  "verify_url": "https://agentscore.sh/dashboard/verify?address=0x..."
}

​

Session-based verification (recommended)

// No identity provided, create a verification session
const session = await agentscore.createSession({
  context: 'purchase',
  product_name: 'Premium API Access',
});

return res.status(403).json({
  error: 'identity_required',
  verify_url: session.verify_url,
  session_id: session.session_id,
  poll_secret: session.poll_secret,
  poll_url: session.poll_url,
  agent_instructions: {
    action: 'poll_for_credential',
    steps: [
      'Direct the user to visit verify_url',
      'Poll poll_url with X-Poll-Secret header every 5 seconds',
      'When status is "verified", extract operator_token from response',
      'Retry the original request with X-Operator-Token header',
    ],
  },
});

​

What’s checked

​

AgentScore Gate denial codes

​

Wallet-mode response fields

​

Fail-open behavior (opt-in)

import { agentscoreGate, getGateDegradedState } from '@agent-score/commerce/identity/hono';

const gate = agentscoreGate({ apiKey: process.env.AGENTSCORE_API_KEY!, failOpen: true });

app.use('/purchase', gate);

app.post('/purchase', async (c) => {
  const { degraded, infraReason } = getGateDegradedState(c);
  if (degraded) {
    // Compliance was NOT enforced this request. Log, alert, or refund async.
    console.warn(`[gate] degraded: ${infraReason}`);
  }
  // ...
});

​

Recommendations by vertical

​

What sellers see

• Verification level (none / claimed / verified)
• Whether each policy check passed or failed

{
  "decision": "allow",
  "operator_verification": {
    "level": "kyc_verified",
    "operator_type": "individual"
  },
  "policy_result": {
    "all_passed": true,
    "checks": [
      { "rule": "require_kyc", "passed": true },
      { "rule": "require_sanctions_clear", "passed": true },
      { "rule": "min_age", "passed": true, "required": 21 },
      { "rule": "allowed_jurisdictions", "passed": true }
    ]
  }
}

​

Privacy

• AgentScore does not store ID documents; they are processed by Stripe Identity and never leave Stripe
• We store derived facts only: verification status, jurisdiction (country code), age bracket, sanctions status
• If our database is breached, attackers see “operator X is verified, US, individual”; no identity data

​

Sandbox testing

# Always allow (verified individual, US, 21+)
curl -X POST https://api.agentscore.sh/v1/assess \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"address": "0x0000000000000000000000000000000000000001", "test": true, "policy": {"require_kyc": true, "min_age": 21}}'

# Always deny (unverified)
curl -X POST https://api.agentscore.sh/v1/assess \
  -H "X-API-Key: your-api-key" \
  -d '{"address": "0x0000000000000000000000000000000000000002", "test": true, "policy": {"require_kyc": true}}'

# Sanctions flagged
curl -X POST https://api.agentscore.sh/v1/assess \
  -H "X-API-Key: your-api-key" \
  -d '{"address": "0x0000000000000000000000000000000000000003", "test": true, "policy": {"require_sanctions_clear": true}}'

# Verified entity (DE jurisdiction)
curl -X POST https://api.agentscore.sh/v1/assess \
  -H "X-API-Key: your-api-key" \
  -d '{"address": "0x0000000000000000000000000000000000000004", "test": true, "policy": {"require_kyc": true}}'

​

Pricing

​

Next steps