> For the complete documentation index, see [llms.txt](https://nytshift.gitbook.io/nytshift-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://nytshift.gitbook.io/nytshift-docs/engineering-guide/09-contracts-and-apis.md).

# Contracts and APIs

[← Identity, portfolio and funding](/nytshift-docs/engineering-guide/08-identity-portfolio-and-funding.md) · [Documentation home](/nytshift-docs/start-here/readme.md) · Next: [Development →](/nytshift-docs/engineering-guide/10-development.md)

Contracts are release artifacts. NYTSHIFT does not treat TypeScript types as sufficient proof that browser, service, signer and Python representations agree.

## Contract pipeline

```mermaid
flowchart LR
    Z[Versioned Zod registry] --> T[TypeScript types]
    Z --> J[JSON Schema 2020-12]
    Z --> O[OpenAPI 3.1.1]
    J --> P[Python parity models]
    O --> C[Client/API checks]
    T --> R[Runtime producer validation]
    P --> S[Signer request validation]
```

Generated artifacts are committed under `packages/contracts/generated` and checked for deterministic drift.

The registry is physically owned by domain modules rather than one monolithic barrel:

| Import                           | Ownership                                                        |
| -------------------------------- | ---------------------------------------------------------------- |
| `@terminal/contracts/core`       | shared market/account/trade primitives and exact-decimal helpers |
| `@terminal/contracts/strategy`   | strategy, PAPER and RHC paper-state contracts                    |
| `@terminal/contracts/execution`  | Arcus/Hyperliquid signer, lifecycle and reconciliation contracts |
| `@terminal/contracts/platform`   | risk, commercial, agent, MCP and eligibility projections         |
| `@terminal/contracts/public-*`   | privacy-reduced anonymous API documents                          |
| `@terminal/contracts/customer-*` | authenticated customer API documents                             |

`@terminal/contracts` remains a re-export-only compatibility surface for external package consumers. Workspace source imports the owning subpath, and a boundary test rejects new root-barrel imports or cycles among the four extracted domains.

## Compatibility rules

* Existing named-v1 request, parameter, security and response boundaries are immutable.
* Additive functionality receives a separately named/versioned operation or document.
* Public producers validate before serialization and attach exact contract headers.
* Validation failure returns a fixed contract error without leaking raw provider payloads or addresses.
* Prices, sizes and notionals use bounded non-exponent decimal strings across signer boundaries.
* Unknown external fields on capital-moving metadata raise schema drift for review.
* Browser/public contracts intentionally remove endpoint, secret and provider-native identity fields.
* TypeScript/Python parity tests bind all signer request shapes.

## API families

The Next.js BFF route tree is under `apps/web/app/api`.

| Family                   | Representative routes                                                                          | Authentication/authority                                             |
| ------------------------ | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| Health/release           | `/api/health`                                                                                  | Anonymous, secret-free, exact release projection                     |
| Public market            | `/api/market`, `/book`, `/candles`, `/trades`, `/funding`, `/liquidations`                     | Anonymous read-only, official-origin and byte bounded                |
| Charting UDF             | `/api/charting/udf/*`                                                                          | Anonymous TradingView-compatible read-only projection                |
| Public venue accounts    | `/api/arcus/account/[address]`, `/hyperliquid/account/[address]`, `/lighter/account/[address]` | Anonymous exact-address, privacy-reduced                             |
| Robinhood Chain          | `/api/rhc/*`, `/api/robinhood-chain`                                                           | Anonymous canonical identity/readiness/data contracts                |
| Customer profile         | `/api/profile/*`                                                                               | Verified Privy customer + exact linked wallet                        |
| Agent connections/MCP    | `/api/agent-connections`, `/api/mcp`                                                           | Customer-issued expiring connection/tool scope                       |
| Pro proposals            | `/api/agent/v1/proposals`, `/api/proposals/*`                                                  | Signed entitlement + expiring proposal credential/operator lifecycle |
| Agent automation         | `/api/agent/v2/automation/*`, `/api/automations/*`                                             | Signed v2 entitlement + DPoP + testnet policy                        |
| Operator execution       | `/api/execution/*`, `/api/arcus/execution/*`                                                   | Operator session + CSRF + one-use confirmation                       |
| Funding/withdrawal       | `/api/profile/funding`, `/api/arcus/funding/*`                                                 | Customer/operator gates by operation; disabled defaults              |
| Observability/commercial | `/api/observability`, `/api/commercial/*`                                                      | Operator-only aggregate, privacy-reduced                             |

## Public market contract

Public market responses normalize venue identity, symbol, metadata, mark/oracle state, freshness, transport and fixed failure codes. Consumer code must not bypass the shared parser to read arbitrary provider JSON.

The exact-context rule matters: a symbol alone cannot join a response to a chart, account or order. Venue, discovered instrument identity, DEX/market ID and observation time participate in authority.

## Public account contract

The public account documents preserve venue-local balances, positions, margin and lifecycle fields while excluding provider-native order/client/transaction IDs and private payloads. Zero/system addresses and malformed scopes fail before provider fan-out.

## MCP contract

The gateway implements MCP protocol `2025-11-25` with a deliberately small method/tool vocabulary. Method, content type, protocol version, tool name, JSON keys and byte budgets fail closed. Tool annotations cannot imply capital authority.

## Signer contracts

The signer boundary uses immutable request families for Arcus and Hyperliquid actions, including fee-bound orders, policy-bound automation, parent/TP/SL brackets and leverage-only requests. Signer authentication, network/account scope, exact-decimal validation and idempotency are rechecked in Python rather than trusted from the BFF.

## Error taxonomy

Prefer fixed machine-readable codes over upstream messages. A useful response separates:

* transport status;
* provider/source;
* data state (`available`, `stale`, `partial`, `unavailable`, `held`);
* capability (`none`, `read`, `paper`, `review`, `testnet-policy`);
* reason code;
* observation/retrieval time;
* coverage bounds.

Raw venue errors may contain sensitive identifiers or unstable wording and are cancelled/redacted at the adapter edge.

## Working with contracts

```powershell
pnpm contracts:generate
pnpm contracts:check
```

Change the registry first, update producers/consumers second, regenerate committed artifacts, then run TypeScript/Python parity and route tests. Never hand-edit generated schemas.

References: [contract evolution runbook](/nytshift-docs/agents-identity-and-data/contract-evolution.md), [API strategy](/nytshift-docs/normative-design/api-strategy.md), [generated artifacts](https://github.com/Nytshift/nytshift/tree/agent/nightshift-paper-db-live-readiness/packages/contracts/generated/README.md) and [agent client](https://github.com/Nytshift/nytshift/tree/agent/nightshift-paper-db-live-readiness/packages/agent-client/README.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://nytshift.gitbook.io/nytshift-docs/engineering-guide/09-contracts-and-apis.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.