> 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/agents-identity-and-data/agent-proposal-api.md). # Pro agent proposal API ## Capability boundary This API accepts analysis proposals. It does not trade. An agent credential can read its own mandate, quota and fixed-code recent audit, then submit a strict `TradeProposal`. An accepted response means only that the advisory proposal entered NIGHTSHIFT's operator ledger. The operator must still attach it to an exact draft, obtain a fresh AEGIS review and explicitly confirm through the normal venue boundary. The agent cannot call the private proposal ledger, execution review, signer, cancellation, funding or reconciliation routes. The machine-readable contract is `packages/contracts/generated/nightshift-agent-api-v1.openapi.json`. ## Issue a credential 1. Provision an active signed Agent Pro license using [`agent-pro-entitlements.md`](/nytshift-docs/agents-identity-and-data/agent-pro-entitlements.md), start NIGHTSHIFT with only that license, its issuer public key and a private `NIGHTSHIFT_OPERATOR_SECRET`, and keep the supervised app on `127.0.0.1`. 2. Open Terminal **Safety settings** and unlock the local operator session. 3. In **Pro Agent API**, enter a human-recognizable agent name, exact venue symbols, maximum proposed notional, lifetime from 15 minutes through 24 hours and rolling hourly attempt limit. 4. Select **Issue once**. Copy the displayed token directly into the agent's secret manager. Closing the modal clears the token from page memory; NIGHTSHIFT cannot display it again. 5. Do not put the token in a URL, cookie, localStorage, prompt, screenshot, shell history, source file, analytics event or log. The Terminal's v1 issuer always requires operator approval, enables long/short/abstain and caps proposal validity at two minutes from generation. The underlying contract still validates every exact mandate rather than trusting UI defaults. ## Verify and submit Keep the credential in a process environment supplied by the agent's secret manager: ```powershell $base = "http://127.0.0.1:3000" $headers = @{ Authorization = "Bearer $env:NIGHTSHIFT_AGENT_TOKEN" } Invoke-RestMethod -Uri "$base/api/agent/v1/proposals" -Headers $headers ``` Create a fresh proposal rather than copying stale timestamps: ```powershell $now = [DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds() $proposal = @{ schemaVersion = "1" proposalId = ([guid]::NewGuid().ToString()) generatedAtMs = $now validUntilMs = $now + 60000 symbol = "BTC" stance = "long" confidence = 0.70 evidence = @(@{ claim = "Fresh provider observation"; source = "provider"; observedAtMs = $now }) entryType = "limit" entryPrice = 100 sizeHintUsd = 50 invalidation = "Price invalidation" stopPrice = 99 targets = @(102) timeHorizon = "intraday" assumptions = @() risks = @("Volatility") } $body = @{ proposal = $proposal } | ConvertTo-Json -Depth 8 -Compress Invoke-RestMethod -Method Post -Uri "$base/api/agent/v1/proposals" -Headers ($headers + @{ "Content-Type" = "application/json" }) -Body $body ``` Replace the example price and size only with real current analysis and stay inside the displayed mandate. An `accepted` response with `approvalRequired: true` is not an order acknowledgement. Inspect the operator ledger, attach deliberately if appropriate and continue through the normal human-confirmed workflow. Every authenticated proposal object that reaches policy evaluation, including schema-invalid or out-of-mandate analysis, consumes both the credential's rolling-hour budget and the license's shared UTC-month allowance. A retry requires a genuinely new proposal UUID and fresh analysis; never change the UUID merely to bypass a lifecycle conflict. ## Revoke and stop * Use **Revoke** to invalidate one credential immediately. * Use **Revoke all** to invalidate every active credential in one durable operation. * After a suspected leak, revoke all first, stop the affected agent processes and inspect the fixed-code access audit. Do not wait for expiry. * For a lost operator secret, stop the local runtime, replace the secret, restart, unlock and use **Revoke all** so stored state reflects the incident. Secret rotation makes old token digests unusable but does not substitute for durable revocation evidence. There is no agent execution kill switch because agents have no execution capability. Existing venue kill switches remain authoritative for user-confirmed capital-moving workflows. ## Health, backup and recovery `/api/health` exposes only `agentAccessState`, entitlement state/reason/expiry, retention and aggregate counts. It never returns a path, license/customer ID, license token, public key, token digest, mandate or agent identity. The default checkpoint is `%USERPROFILE%\.nightshift\data\agent-access-v1.json` on Windows and `~/.nightshift/data/agent-access-v1.json` elsewhere. Do not hand-edit or delete the checkpoint to clear an error. Preserve the bytes for incident review, stop the supervisor before restore and use only verified backups: ```powershell pnpm local:stop pnpm backup:list pnpm backup:verify -- pnpm backup:restore -- pnpm local:start pnpm local:health ``` The checkpoint stores agent names, mandates and fixed-code audit metadata, so treat its backup as private operational data even though no plaintext credential or proposal body is present. ## Remote-access rule Do not expose the current local server with a tunnel, port forward or public reverse proxy. Loopback HTTP is the reviewed deployment. A future remote proposal service needs reviewed TLS termination, origin/network policy, a managed secret store, abuse protection, entitlement enforcement and incident monitoring. The separate v2 automation surface supports sender-constrained, policy-bound Hyperliquid testnet orders on reviewed loopback deployment only; follow [`agent-automation.md`](/nytshift-docs/agents-identity-and-data/agent-automation.md). The v1 bearer proposal token and endpoints remain advisory-only and are never upgraded into signer authority. Remote or mainnet automated execution remains a different, unsupported product boundary. --- # 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/agents-identity-and-data/agent-proposal-api.md?ask=&goal= ``` `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.