> ## Documentation Index > Fetch the complete documentation index at: https://docs.webacy.com/llms.txt > Use this file to discover all available pages before exploring further. # Batch Vault Grades > Returns the v3 `composite` grade (letter + 0–100 risk score + per-category contributors) for up to 100 vaults in one request. Vault addresses travel in the POST body because the list is variable-length and may include non-EVM addresses; the endpoint is read-only. Per-vault failures are reported in-band as `{ ok: false, error_code }` (HTTP 200) so a single bad address never fails the whole batch. POLARITY: scores 0–100, higher = worse. **CU cost:** 1 CU × token count (`v3-vault-grades-batch`). Returns the V3 composite grade (letter + 0–100 risk score + per-category contributors) for up to **100** vaults in a single request. The vault addresses travel in the request **body** because the list is variable-length and can include non-EVM addresses; the endpoint is read-only. The batch never fails as a whole. Each result row carries its own outcome — either `ok: true` with a `composite`, or `ok: false` with an `error_code` (`NOT_FOUND`, `INVALID_ADDRESS`, `UNSUPPORTED_CHAIN`, or `UPSTREAM_ERROR`) — so one bad vault can't sink the request. ## OpenAPI ````yaml POST /v3/vaults/batch/grades openapi: 3.0.1 info: title: Risk Score API description: API definition for Webacy Risk Scores version: 1.2.0 servers: - url: https://api.webacy.com description: Webacy Risk Score API (Production) - url: https://api-development.webacy.com description: Webacy Risk Score API (Development) - url: http://0.0.0.0:3030/api/v1/risk-score description: Webacy Risk Score API - Local security: - api_key: [] tags: - name: Threat Risks description: Analyze addresses for security threats and malicious activity - name: Sanction Checks description: Check addresses against OFAC and other sanction lists - name: Approval Risks description: Analyze token approvals and associated risks - name: Transaction Risks description: Assess risk details for blockchain transactions - name: Exposure Risk description: Understand risk profile and exposure of addresses - name: Contract Risk description: Real-time smart contract security analysis - name: URL Risks description: Analyze URLs for phishing and security threats - name: API Usage description: Monitor and manage API consumption - name: Holder Analysis description: Token holder distribution and sniper detection - name: Address Poisoning description: Detect address poisoning attack patterns - name: Token Analysis description: Comprehensive token security and market analysis - name: Pool Analysis description: Liquidity pool data and analysis - name: Transaction Scanning description: Scan and simulate transactions for risks - name: trading-lite description: Lightweight trading risk assessment - name: RWA & Pegged Tokens description: >- Real-world asset and pegged-token analytics (supply flows, mint/burn velocity) - name: Vault Risk v3 description: >- Webacy-native v3 vault risk surface — composite grade, categories, coverage, and the framework taxonomy (RFC-019). - name: RWA Risk v3 description: >- Webacy-native v3 RWA / stablecoin risk surface — composite grade, structural-health criteria, and batch (RFC-019). paths: /v3/vaults/batch/grades: post: tags: - Vault Risk v3 summary: Batch v3 vault composite grades description: >- Returns the v3 `composite` grade (letter + 0–100 risk score + per-category contributors) for up to 100 vaults in one request. Vault addresses travel in the POST body because the list is variable-length and may include non-EVM addresses; the endpoint is read-only. Per-vault failures are reported in-band as `{ ok: false, error_code }` (HTTP 200) so a single bad address never fails the whole batch. POLARITY: scores 0–100, higher = worse. **CU cost:** 1 CU × token count (`v3-vault-grades-batch`). operationId: getVaultGradesBatchV3 parameters: - name: grading_scheme in: query required: false schema: type: string enum: - v1 - v2 default: v2 description: >- Grading scheme to pin — selects the letter-grade band table. Default `v2` (the standard 11-band scale: no `E`, adds `C+`). `v1` is frozen and **deprecated**. Independent of the API version (`v3`) and of `framework_version`. Unknown values return 400 with the supported list. requestBody: required: true content: application/json: schema: type: object required: - tokens properties: tokens: type: array minItems: 1 maxItems: 100 description: Up to 100 { address, chain } tuples — the vaults to grade. items: type: object required: - address - chain properties: address: type: string description: Vault contract address. chain: type: string description: Chain identifier (e.g. eth, base, pol). example: tokens: - address: '0xD50DA5F859811A91fD1876C9461fD39c23C747Ad' chain: eth - address: '0x0deFfd509197aAD5207d2A55862835b467E8128F' chain: eth responses: '200': description: >- Per-vault composite grade results. The batch never fails as a whole; each row is `ok: true` with a `composite`, or `ok: false` with an `error_code`. content: application/json: schema: type: object required: - schema_version - results properties: schema_version: type: string example: '3.0' results: type: array items: oneOf: - type: object required: - address - chain - ok - composite properties: address: type: string chain: type: string ok: type: boolean enum: - true composite: $ref: '#/components/schemas/V3Composite' - type: object required: - address - chain - ok - error_code properties: address: type: string chain: type: string ok: type: boolean enum: - false error_code: type: string enum: - NOT_FOUND - INVALID_ADDRESS - UNSUPPORTED_CHAIN - UPSTREAM_ERROR example: schema_version: '3.0' results: - address: '0xD50DA5F859811A91fD1876C9461fD39c23C747Ad' chain: eth ok: true composite: grading_scheme: v2 grade: F stars: 1 score: 98.5 contributors: smart_contract: score: 0 weight: 0.2 operational_governance: score: 0 weight: 0.2 asset_collateral: score: 10 weight: 0.15 market_liquidity: score: 35 weight: 0.2 counterparty: score: 0 weight: 0.1 hack_exploit_history: score: 0 weight: 0.15 chain_infrastructure: score: 0 weight: 0 upstream_risk: 98.5 clamped_by_upstream: true - address: '0x0000000000000000000000000000000000000000' chain: eth ok: false error_code: NOT_FOUND '400': description: Invalid body (empty or > 100 tokens) or grading_scheme. '403': description: Missing or invalid x-api-key. security: - api_key: [] components: schemas: V3Composite: type: object description: >- Headline grade block. POLARITY (load-bearing): `score` is 0–100, HIGHER = WORSE (A+ = 0, F = 100) — same direction as the v2 `risk.score` on the same response. `score = max(Σ contributors·weight, upstream_risk)`: floored from below by the upstream pipeline risk. The letter set in `grade` depends on `grading_scheme`: `v2` (default, standard 11-band scale) emits `C+` and never `E`; `v1` (frozen legacy scale) emits `E` and never `C+`. allOf: - oneOf: - title: grading_scheme v2 (standard) properties: grading_scheme: type: string enum: - v2 grade: type: string enum: - A+ - A - A- - B+ - B - B- - C+ - C - C- - D - F - title: grading_scheme v1 (legacy) properties: grading_scheme: type: string enum: - v1 grade: type: string enum: - A+ - A - A- - B+ - B - B- - C - C- - D - E - F properties: grading_scheme: type: string enum: - v1 - v2 example: v2 grade: type: string description: >- Letter grade. Valid set depends on `grading_scheme` (see the `oneOf` above): v2 → no `E`, has `C+`; v1 → has `E`, no `C+`. The enum here is the union across both schemes. enum: - A+ - A - A- - B+ - B - B- - C+ - C - C- - D - E - F stars: type: integer minimum: 1 maximum: 5 score: type: number description: 0–100, higher = worse; rounded to one decimal. contributors: type: object description: 'Dense map: every WebacyCategory key is present.' additionalProperties: $ref: '#/components/schemas/V3Contributor' upstream_risk: type: number description: >- Verbatim upstream pipeline risk (0–100, higher = worse). Acts as a lower bound on `score`. clamped_by_upstream: type: boolean description: >- true iff upstream_risk exceeded the framework composite and pulled `score` up. required: - grading_scheme - grade - stars - score - contributors - upstream_risk - clamped_by_upstream V3Contributor: type: object description: >- One row of `composite.contributors`: a category's resolved score and its weight under the current grading scheme. properties: score: type: number description: 0–100, higher = worse. Integer. weight: type: number description: >- Category weight under the grading scheme (sums to 1 across categories). required: - score - weight securitySchemes: api_key: type: apiKey in: header name: x-api-key ````