{"schema_version":"grainbud.ai-api.manifest.v1","contract_version":"grainbud.ai-api.contract.v1","generated_at":"2026-09-12T02:55:13.188Z","name":"GrainBud AI Read-Only Portfolio API","description":"Read-only personal investment portfolio snapshot API for AI analysis. The Web UI is for humans; this API is the stable AI-facing surface.","base_url":"https://grainbud.poorlow.com","authentication":{"required":false,"mode":["open"],"required_scope":"portfolio:snapshot:read","accepted_credentials":[{"type":"bearer","header":"Authorization","format":"Bearer <token>","recommended":true},{"type":"x-api-token","header":"x-api-token","format":"<token>","recommended":false}]},"capabilities":{"supported":["portfolio_snapshot.read","positions.query","instruments.search_known_holdings","quotes.latest_reference_for_known_instruments","funds.intraday_reference_estimate","exposures.read","data_quality.read","openapi.import","skill.read"],"unsupported":["order.place","order.cancel","order.modify","credential.read","historical_market_data.full_universe","transaction_history.full_ledger_api"],"quote_boundary":"Latest quote endpoints return the latest stored reference quote for instruments known to GrainBud; they are not a broker trading feed or full-market quote search."},"read_only":true,"safety":{"hard_boundaries":["Do not place orders, cancel orders, modify orders, unlock trading, or request credentials.","Do not attribute buy/sell/hold, rebalancing, stop-loss, take-profit, recovery, or cash-planning recommendations to GrainBud.","Do not promise recovery, guarantee returns, or claim future prices are certain.","Do not present GrainBud reference quotes as live executable broker quotes.","Do not hide stale quotes, missing quotes, stale FX, missing FX, account snapshot age, or pending import caveats."],"neutral_data_provider":true,"grainbud_recommendations_allowed":false,"downstream_ai_analysis_allowed":true,"decision_support_allowed":false,"allowed_decision_support_outputs":[],"allowed_data_outputs":["confirmed portfolio facts","reference quote fields","valuation caveats","data freshness diagnostics","exposure and concentration metrics","source lineage summaries"],"recommended_decision_inputs":["risk_tolerance","investment_horizon","cash_need","target_allocation","transaction_constraints"],"requirements_for_downstream_analysis":["confirmed portfolio facts","latest quote timestamp, provider, stale status, and quote age","reference valuation and confirmed snapshot separation","clear statement that GrainBud is a neutral data provider and cannot execute trades","do not attribute downstream portfolio judgments to GrainBud"]},"data_source_registry":{"confirmed_holdings":{"authority":"confirmed account snapshots imported into GrainBud","fields":"total assets, cash, quantity, confirmed price, confirmed market value, unrealized P/L, day P/L, account freshness"},"price_snapshots":{"authority":"latest stored external reference quotes and NAV snapshots","providers":["Eastmoney A-share/ETF quote and fund NAV sources","AKShare-backed server sync jobs for supported CN fund, ETF, stock and gold references","manual or captured platform records when no public quote source exists"],"boundary":"Reference-only. Missing or stale quotes never overwrite confirmed account facts."},"fund_intraday_estimates":{"authority":"public fund intraday estimate endpoints for GrainBud synced fund profiles","providers":["fundgz.1234567.com.cn JSONP estimate fields"],"boundary":"Reference-only intraday estimate. It is not official confirmed NAV and never overwrites confirmed account facts."},"fx_rates":{"authority":"stored FxRate records","boundary":"Used only when converting external estimates across currencies; missing pairs do not force conversion."}},"endpoints":[{"id":"portfolio_snapshot","method":"GET","path":"/api/ai/portfolio/snapshot","url":"https://grainbud.poorlow.com/api/ai/portfolio/snapshot","auth_required":false,"description":"Fetch the current confirmed portfolio snapshot, reference quotes, FX estimates, data freshness, source lineage, and neutral diagnostic flags."},{"id":"positions","method":"GET","path":"/api/ai/positions","url":"https://grainbud.poorlow.com/api/ai/positions","auth_required":false,"description":"Query current confirmed positions by symbol, account, asset class, market, theme, or exposure tag."},{"id":"instrument_search","method":"GET","path":"/api/ai/instruments/search","url":"https://grainbud.poorlow.com/api/ai/instruments/search","auth_required":false,"description":"Search GrainBud known instruments and holdings by code, mapped public code, provider identifier, or name."},{"id":"latest_quote","method":"GET","path":"/api/ai/quotes/latest","url":"https://grainbud.poorlow.com/api/ai/quotes/latest","auth_required":false,"description":"Fetch the latest stored reference quote for a known held instrument. Requires ?symbol=<code>."},{"id":"fund_intraday_estimate","method":"GET","path":"/api/ai/funds/intraday-estimates","url":"https://grainbud.poorlow.com/api/ai/funds/intraday-estimates","auth_required":false,"description":"Fetch a neutral intraday reference estimate for a GrainBud synced 6-digit open-end fund profile. Requires ?code=<fund-code>."},{"id":"exposures","method":"GET","path":"/api/ai/exposures","url":"https://grainbud.poorlow.com/api/ai/exposures","auth_required":false,"description":"Read theme and classification exposures such as gold, technology, cash, precious metals, or equity."},{"id":"data_quality","method":"GET","path":"/api/ai/data-quality","url":"https://grainbud.poorlow.com/api/ai/data-quality","auth_required":false,"description":"Fetch data freshness, valuation coverage, refresh recommendations, disclosures, and data-quality or exposure diagnostics."},{"id":"manifest","method":"GET","path":"/api/ai/manifest","url":"https://grainbud.poorlow.com/api/ai/manifest","auth_required":false,"description":"Machine-readable API discovery document."},{"id":"openapi","method":"GET","path":"/api/ai/openapi","url":"https://grainbud.poorlow.com/api/ai/openapi","auth_required":false,"description":"OpenAPI 3.1 contract for tools that can import an API spec."},{"id":"instructions","method":"GET","path":"/api/ai/instructions","url":"https://grainbud.poorlow.com/api/ai/instructions","auth_required":false,"description":"Markdown instructions that can be pasted into an AI skill or custom GPT action description."},{"id":"skill_markdown","method":"GET","path":"/skill.md","url":"https://grainbud.poorlow.com/skill.md","auth_required":false,"description":"Canonical hosted Markdown skill file that tells external AI how to use the read-only API."},{"id":"agent_markdown","method":"GET","path":"/agent.md","url":"https://grainbud.poorlow.com/agent.md","auth_required":false,"description":"Single-link AI-readable portfolio brief with current holdings table, caveats, and endpoint map."},{"id":"llms_txt","method":"GET","path":"/llms.txt","url":"https://grainbud.poorlow.com/llms.txt","auth_required":false,"description":"Concise AI crawler index that points to the canonical agent brief and machine-readable API contracts."}],"ai_usage_policy":["Treat confirmed_snapshot values as authoritative account facts.","Treat external_quote, NAV, delayed quotes, FX conversions, external_estimates, and reference_value as decision-support reference data only; they do not overwrite confirmed account facts.","Do not infer trades, cash transfers, or costs that are not present in the snapshot.","Always surface snapshot.diagnostics.flags as data-quality or exposure diagnostics, not GrainBud recommendations.","This API is read-only. It does not support order placement, order cancellation, trade modification, or account credential operations.","GrainBud does not provide buy/sell/hold recommendations, rebalancing instructions, stop-loss/take-profit levels, recovery plans, or cash-planning judgments.","Downstream AI tools may independently analyze these data fields, but recommendations or conclusions must not be attributed to GrainBud."]}