> ## Documentation Index
> Fetch the complete documentation index at: https://glide-9da73dea.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# @glideco/schemas

> Zod schemas and closed-vocabulary types for Glide agent banking. TypeScript source of truth for the JSON Schemas published at glide.co/schemas/agent-banking.

Zod schemas and closed-vocabulary types for Glide agent banking. Every schema
in this package serves two purposes: it validates data at runtime in TypeScript,
and it generates the JSON Schema documents published at
`glide.co/schemas/agent-banking/draft/*` via a build script that converts
Zod's output to JSON Schema 2020-12.

The TypeScript schemas are the source of truth. The published JSON Schemas
are downstream artifacts — derived, not maintained by hand.

## Install

```bash theme={null}
npm install @glideco/schemas
```

[npmjs.com/package/@glideco/schemas](https://www.npmjs.com/package/@glideco/schemas)

## Zod schemas vs. JSON Schemas

| Layer        | Where it lives                                | Who uses it                                                              |
| ------------ | --------------------------------------------- | ------------------------------------------------------------------------ |
| Zod schemas  | `packages/schemas/src/*.ts` (this package)    | TypeScript / tRPC / MCP server — parse and throw at runtime              |
| JSON Schemas | `glide.co/schemas/agent-banking/draft/*.json` | External implementers, validators in other languages, the standards docs |

The build script at `scripts/build-json-schemas.mjs` calls Zod's JSON Schema
converter, wraps each output with `wrapSchema()` to add the canonical `$id`,
and writes both `apps/web/public/schemas/` (the served copy) and `dist/schemas/`
(the standalone artifact). The `$id` URL is what external consumers should
cite — the host is a deployment detail.

## Published schema names

| Schema name             | `$id` (draft channel)                                                     |
| ----------------------- | ------------------------------------------------------------------------- |
| `connector-manifest`    | `https://glide.co/schemas/agent-banking/draft/connector-manifest.json`    |
| `agent-policy-envelope` | `https://glide.co/schemas/agent-banking/draft/agent-policy-envelope.json` |
| `agent-activity-event`  | `https://glide.co/schemas/agent-banking/draft/agent-activity-event.json`  |
| `trust-tier`            | `https://glide.co/schemas/agent-banking/draft/trust-tier.json`            |
| `scoped-grant-claims`   | `https://glide.co/schemas/agent-banking/draft/scoped-grant-claims.json`   |
| `skill-manifest`        | `https://glide.co/schemas/agent-banking/draft/skill-manifest.json`        |
| `grant`                 | `https://glide.co/schemas/agent-banking/draft/grant.json`                 |
| `receipt`               | `https://glide.co/schemas/agent-banking/draft/receipt.json`               |

Schemas publish at `/draft/` URLs until 3+ independent implementers exist.
Promotion to `/v1/` is an explicit, announced event.

## Core schemas

**AgentPolicyEnvelope** — the 14-axis policy evaluated by `@glideco/policy-engine`
on every agent tool call. Covers amount caps (per-tx, per-day, lifetime),
step-up threshold, counterparty allowlist, velocity limits, chain allowlist,
geo allowlist, MCC allow/block lists, and an absolute time window. An empty
`counterparty_allowlist` is fail-closed: the engine denies all counterparties.

**GrantClaims** — OAuth 2.0 / RFC 7519 JWT claims with RFC 8707 resource
indicators. The `aud` field carries both `vault_id` and `entity_id` (non-standard
object form); verifiers must check both. Max TTL is 60 minutes enforced by
`grantClaimsValidatedSchema`. The `act` (RFC 8693 actor) claim is always required
— missing means denied at the verifier.

**Receipt** — the tool-call receipt persisted in `activity_log` after every
money-touching MCP call settles. `on_chain_tx` is server-fetched from chain RPC,
never from a facilitator response body — a money-safety rule inherited from
x402.pay client-receipt-trust learnings.

**AgentScope** — closed vocabulary of 15 MCP scopes a grant can carry. Adding a
scope is a CODEOWNERS-protected change because the policy-engine evaluator must
understand the same set.

## Usage

```ts theme={null}
import { AgentPolicyEnvelope, GrantClaims, Receipt, agentScopeSchema } from '@glideco/schemas';

// Parse and throw on schema mismatch.
const envelope = AgentPolicyEnvelope.parse(rawJson);

// Validate grant claims including the 60-min TTL cap.
import { grantClaimsValidatedSchema } from '@glideco/schemas';
const claims = grantClaimsValidatedSchema.parse(jwtPayload);

// Validate a receipt before persisting it.
const receipt = Receipt.parse(activityLogRow);

// Check a scope string is in the closed vocabulary.
const scope = agentScopeSchema.parse('payments:initiate');
```

## CAIP-2 translation

`@glideco/schemas` exports `chainIdToCaip2()` and `caip2ToChainId()` for
translating between Glide's internal short-ids (`eth`, `sol`) and the
CAIP-2 wire form that x402, AP2, and ACP protocols carry.

```ts theme={null}
import { chainIdToCaip2, caip2ToChainId } from '@glideco/schemas';

chainIdToCaip2('eth');   // → 'eip155:1'
caip2ToChainId('eip155:8453');  // → 'base'
caip2ToChainId('eip155:9999');  // → null (callers must return 400, not fallback)
```

`BSC` (`bsc`) is deliberately excluded: USDC on BSC has 18 decimals vs. 6
everywhere else, which would silently underflow amount-in-cents math by 10^12.

## Building a JSON Schema for publication

```ts theme={null}
import { z } from 'zod';
import { wrapSchema, buildSchemaId } from '@glideco/schemas';

// Convert any Zod schema to a wrapped JSON Schema ready for publication.
const body = z.toJSONSchema(myZodSchema);
const wrapped = wrapSchema('grant', body, {
  channel: 'draft',
  title: 'Glide Grant Claims',
  description: 'RFC 7519 JWT claims for an agent banking grant.',
});
// wrapped.$id → 'https://glide.co/schemas/agent-banking/draft/grant.json'
```

## Reading list

* [Standards overview](/docs/oss/standards/index) — the public standards namespace these schemas underpin.
* [ConnectorManifest standard](/docs/oss/standards/connector-manifest)
* [AgentPolicyEnvelope standard](/docs/oss/standards/agent-policy-envelope)
* [`@glideco/policy-engine`](https://www.npmjs.com/package/@glideco/policy-engine) — evaluates `AgentPolicyEnvelope` at runtime.
* [`@glideco/kya-vc`](/docs/oss/packages/kya-vc) — uses `canonicalJson` from this package for VC signing.
* [Source on GitHub](https://github.com/darshanbathija/axtior-neobank/tree/main/packages/schemas)