# Mangrove - complete AI integration overview This file is generated from the reviewed integration pages below. The REST contract, execution configuration JSON Schema and Oracle proxy contract are public references at https://mangrovedeveloper.ai/openapi.json, https://mangrovedeveloper.ai/execution-config.schema.json and https://mangrovedeveloper.ai/openapi-oracle.json. They use their documented API hosts and paths; these references do not prove workflow acceptance. Some REST responses are unspecified or opaque. Use the live MCP catalog for callable tools and prices. This file includes the onboarding guides listed below; it is not the full product API manual. ## Guide: Build with AI # Build with AI Give your coding tool the same SDK and API contracts that your application uses. Start with these four public reference files: 1. [OpenAPI specification](https://mangrovedeveloper.ai/openapi.json): registered public REST operations in OpenAPI format. Some responses are opaque; Oracle proxy operations have a separate contract. 2. [Execution configuration JSON Schema](https://mangrovedeveloper.ai/execution-config.schema.json): authoring fields and runtime-derived defaults. The server remains authoritative for validation and runtime policy. 3. [llms.txt](https://mangrovedeveloper.ai/llms.txt): a concise overview and links to the integration guides. 4. [llms-full.txt](https://mangrovedeveloper.ai/llms-full.txt): reviewed onboarding, SDK release status, first-call examples and hosted MCP discovery. You can use the references while coding in Claude, Cursor, ChatGPT, Gemini or Copilot. Tools differ in how they fetch URLs and attach files. If yours cannot read a URL, download the file and attach it using that tool's supported workflow. Providing reference files gives the model context; connecting an MCP server is a separate step. ## Copy this prompt ```text I'm building against Mangrove. Use these reference files: - OpenAPI spec: https://mangrovedeveloper.ai/openapi.json - Execution config schema: https://mangrovedeveloper.ai/execution-config.schema.json - Quick overview: https://mangrovedeveloper.ai/llms.txt - Full integration docs: https://mangrovedeveloper.ai/llms-full.txt Write matched server-side Python and TypeScript functions that accept an API key and read developer usage metrics using the MangroveAI SDKs: Python: from mangrove_ai import MangroveAI; users.get_my_metrics(). TypeScript: import { MangroveAI } from '@mangrove-ai/sdk'; users.getMyMetrics(). Follow the SDK guide's verified release state and installation instructions. Use finite timeouts, preserve null/missing metrics, and handle authentication, malformed responses and unavailable dependencies. Keep credentials out of prompts, logs and browser code. Include mocked success, 401 and 503 tests. Separately show anonymous hosted MCP initialization and tools/list at https://api.mangrovedeveloper.ai/mcp/, requesting current pricing metadata. Read advertised schemas before suggesting a tool call; unknown price is not free. Do not execute paid compute, create wallets, connect brokers or place orders. Mangrove provides deterministic risk management based on live market and account conditions: Mangrove-owned execution software evaluates those inputs against the user's policy and enforces the decision in supported workflows, including the local Mangrove Agent where supported. SDKs and connected AI clients submit requests and preserve decisions/audit information; they do not make the policy decision. Distinguish AI strategy execution records from broker holdings and verify venue support before claiming enforcement. ``` ## Follow the workflow 1. Read the three files and the [combined AI SDK guide](https://mangrovedeveloper.ai/llms-full.txt). Install the published package versions listed in the SDK guide. 2. Sign in to the [developer portal](https://mangrove.io/developer/api-keys), create a scoped key and store it in private server configuration. Never paste it into an AI conversation. 3. Generate SDK-based functions using the exact methods above. Run mocked tests against the installed packages first. Label any direct HTTP or MCP alternative explicitly. 4. Follow the [quickstart](https://mangrovedeveloper.ai/llms-full.txt): inspect the public MCP catalog, then read authenticated metrics outside the conversation. The metrics read is separate from executing a tool. 5. For a later business action, inspect its contract, access and cost. Mangrove-owned execution software evaluates live market/account inputs deterministically against user policy and enforces the decision in the supported execution path, including the local Mangrove Agent where supported. SDKs and connected AI clients submit the action and preserve the returned decision and audit information; do not substitute a model's judgment for it. ## Validate generated code REST uses `Authorization: Bearer`; the SDKs set that header. Hosted MCP additionally accepts `X-API-Key`. A `401` or `403` is an access failure. A `402` requests payment, not permission to pay automatically. If a paid request or order has an uncertain outcome, preserve its operation identity and reconcile it before another attempt. Do not assume every response is wrapped in `data`, every list has identical pagination, a missing price means free, or every environment has the same catalog. Some OpenAPI response shapes are unspecified. The [Oracle proxy contract](https://mangrovedeveloper.ai/openapi-oracle.json) is a separate release dependency; do not derive its fields from the core schema. ## Runnable examples and alternatives Start with the [Python SDK example](https://mangrovedeveloper.ai/examples/first_sdk_call.py), [JavaScript example for the TypeScript SDK](https://mangrovedeveloper.ai/examples/first_sdk_call.mjs) and [private-config instructions](https://mangrovedeveloper.ai/examples/first-sdk-call.md). For a labeled direct HTTP/MCP alternative, the [standard-library reference client](https://mangrovedeveloper.ai/examples/first_api_call.py) and [its instructions](https://mangrovedeveloper.ai/examples/first-api-call.md) initialize MCP, request the catalog and read usage metrics without an external Python HTTP dependency. It is not an SDK install or a broker workflow. ## Next steps - [AI SDKs and release status](https://mangrovedeveloper.ai/llms-full.txt) - [Authentication](https://mangrovedeveloper.ai/llms-full.txt) - [Hosted MangroveAI MCP](https://mangrovedeveloper.ai/llms-full.txt) - [Markets SDK and broker workflow](https://mangrovedeveloper.ai/llms-full.txt) - [API reference overview](https://mangrovedeveloper.ai/llms-full.txt) --- ## Guide: Quickstart # Quickstart Start with public discovery and a developer usage read. This confirms the integration without launching a backtest or placing an order. MangroveAI, Markets and the local agent have different capabilities and credentials. ## 1. Read the SDK and API contracts Read the [combined Python/TypeScript AI SDK guide](https://mangrovedeveloper.ai/llms-full.txt), [OpenAPI specification](https://mangrovedeveloper.ai/openapi.json), [execution configuration schema](https://mangrovedeveloper.ai/execution-config.schema.json), [concise overview](https://mangrovedeveloper.ai/llms.txt) and [full integration guide](https://mangrovedeveloper.ai/llms-full.txt). The SDK guide identifies the published package versions used by these examples. Do not install the Markets npm package as an AI API replacement. The core REST schema uses OpenAPI; response types are not complete for every operation. The separately reviewed [Oracle proxy schema](https://mangrovedeveloper.ai/openapi-oracle.json) covers its allowlisted proxy operations. Use the current execution configuration reference for authoring fields and runtime-derived defaults; runtime validation remains server-owned. Check deployment availability before relying on an operation. ## 2. Discover hosted MCP tools (protocol alternative) The endpoint is `https://api.mangrovedeveloper.ai/mcp/`. Follow the anonymous `initialize`, `notifications/initialized` and `tools/list` sequence in the [hosted MCP guide](https://mangrovedeveloper.ai/llms-full.txt). Request pricing with `params._meta["mangrove/include_pricing"]=true`. Read `result.tools` for current tool names and input schemas, and `result._meta["mangrove/pricing"]` for receiver-owned prices when available. Missing pricing is unknown, not free. The protocol method is `tools/list`, not a callable `list_tools`. No business tool needs to execute for this first task. ## 3. Create a scoped API key Sign in at the [API Keys page](https://mangrove.io/developer/api-keys). Store the key in a secret manager or private server configuration. Keep it out of source control, browser code, email and AI prompts. See [authentication](https://mangrovedeveloper.ai/llms-full.txt). ## 4. Make the SDK read Install the published package for your language using the [SDK guide's installation instructions](https://mangrovedeveloper.ai/llms-full.txt). Python: ```python from mangrove_ai import MangroveAI def get_developer_metrics(api_key: str) -> dict: with MangroveAI(api_key=api_key, load_dotenv=False, timeout=15, auto_retry=False) as client: return client.users.get_my_metrics().model_dump(mode="json") ``` TypeScript: ```typescript import { MangroveAI } from "@mangrove-ai/sdk"; export const getDeveloperMetrics = async (apiKey: string) => { const client = new MangroveAI({ apiKey, timeoutMs: 15_000 }); return client.users.getMyMetrics(); }; ``` Use the downloadable [Python](https://mangrovedeveloper.ai/examples/first_sdk_call.py) or [JavaScript](https://mangrovedeveloper.ai/examples/first_sdk_call.mjs) example with [private-config instructions](https://mangrovedeveloper.ai/examples/first-sdk-call.md). Both call `GET /api/v1/users/me/metrics`, use Bearer authentication and preserve missing/null counts. They return developer usage, not brokerage balances or positions. Run the mocked checks before using your own key. ## 5. Choose the next workflow Mangrove provides deterministic risk management based on live market and account conditions. In supported workflows, Mangrove-owned execution software evaluates those conditions against the user's policy and enforces the decision, including the local Mangrove Agent where supported. SDKs and connected AI clients submit the action and preserve the result and audit information. Do not infer approval or claim coverage of an unverified venue. - [Build with AI](https://mangrovedeveloper.ai/llms-full.txt) contains a copyable prompt for the same SDK workflow. - [Markets SDKs](https://mangrovedeveloper.ai/llms-full.txt) cover separate wallet/venue integrations. A developer usage read does not connect a broker or authorize a trade. - [Hosted MCP](https://mangrovedeveloper.ai/llms-full.txt) covers current tools, pricing and protocol lifecycle. - The [local agent client guide](https://github.com/MangroveTechnologies/mangrove-agent/blob/main/docs/clients.md) describes local custody and credentials. Its venue operations may differ from hosted Markets. ## Direct HTTP alternative For an integration that deliberately avoids SDK dependencies, use the tested [standard-library REST/MCP reference](https://mangrovedeveloper.ai/examples/first_api_call.py) and [its private-config instructions](https://mangrovedeveloper.ai/examples/first-api-call.md). Direct REST requests use `Authorization: Bearer`; `X-API-Key` is also supported by hosted MCP, not by this REST read. Keep the HTTP response's status, envelope and operation-specific schema checks. --- ## Guide: Authentication # Authentication For a server-side integration, sign in to the [developer portal](https://mangrove.io/developer/api-keys), create a scoped API key and store it in a secret manager. The portal manages your signed-in account; the key authenticates your application. ## REST API Send your key in the Bearer authorization header: ```http Authorization: Bearer YOUR_API_KEY ``` The public REST origin is `https://api.mangrovedeveloper.ai`. Use the operation path in the [OpenAPI specification](https://mangrovedeveloper.ai/openapi.json). For example, `GET /api/v1/users/me/metrics` is an authenticated read of developer usage. `X-API-Key` is not the authentication header for these REST operations. ## Hosted MangroveAI MCP The hosted endpoint is `https://api.mangrovedeveloper.ai/mcp/`. It accepts either: ```http X-API-Key: YOUR_API_KEY ``` or: ```http Authorization: Bearer YOUR_API_KEY ``` Supply credentials through the MCP client's protected header configuration. Do not type a real key into an AI prompt. A client that cannot set protected headers needs its own supported authentication workflow; reference-file attachment does not authenticate an MCP connection. Lifecycle and catalog discovery methods are anonymous. Execution is checked separately for authentication, role, scope, entitlement or payment. A successful `tools/list` response does not authorize every listed operation. OAuth connector availability depends on the deployed endpoint and its authorization metadata. Do not infer OAuth support from a source flag, a developer API key, or a broker's own OAuth support. Follow the deployment's actual challenge and metadata before using a client-specific connector setup. ## Scope and ownership A valid key can still be refused when its role, scope or product entitlement is insufficient. Use the exact required scope from the operation documentation or the server's permission error. Resource names are singular, such as `strategy:read`, rather than invented forms such as `read:strategies`. Use an explicitly restricted scope list for least privilege. Do not assume an empty list means read-only. Revoking and reissuing a key may be needed when the intended permissions change. User and organization ownership still applies; knowing an identifier is not permission to read it. ## x402 payments Some tools support keyless payment using x402. Discover the receiver's current prices through MCP `tools/list` with `params._meta["mangrove/include_pricing"] = true`. The actual `402 Payment Required` response supplies the payment requirements for that request. Use a compatible payer only after the user authorizes the cost and network. An API key is not a promise that every operation is included in the account's plan. Missing pricing metadata means unavailable, not free. Do not automatically change authentication mode, pay, or retry a chargeable operation to get around an access failure. If the outcome is uncertain, retain its operation identity and reconcile it instead of submitting another paid request. ## Errors - `401`: credentials are missing, invalid or expired. Check the header format and the active key. - `403`: the caller lacks a required permission or entitlement. Read the server's error; changing the header name does not grant access. - `402`: payment is required. Inspect the requirements without signing or paying automatically. - `429`: the rate limit was reached. Respect the response's retry guidance and use bounded retries. - `503`: a dependency is unavailable. Do not treat an unavailable catalog, price or schema as an empty success. Response shapes vary by operation. Check both HTTP status and the operation's documented success/error fields. Preserve a safe correlation identifier for support, and redact credentials and private account data from diagnostic exports. ## Credential handling Never commit keys, place them in browser bundles, include them in URLs, or print request headers. Prefer a secret manager and a dedicated key per integration. Rotate or revoke a key if it is exposed. Broker keys, wallet signing secrets and developer API keys have distinct custody and permission rules; developer authentication does not grant broker authorization. --- ## Guide: SDKs Overview # SDKs Choose the product first, then its client. MangroveAI and Mangrove Markets use different APIs and workflows. | Product | Python | TypeScript | Purpose | | --- | --- | --- | --- | | [MangroveAI](https://mangrovedeveloper.ai/llms-full.txt) | `mangroveai`, import `mangrove_ai` | `@mangrove-ai/sdk` | Managed strategies, signals, backtests and developer usage | | [Mangrove Markets](https://mangrovedeveloper.ai/llms-full.txt) | `mangrovemarkets` | `@mangrove-ai/markets` | Venue, wallet and marketplace workflows; release capabilities differ | | Mangrove KB | `mangrove-kb` | See its guide | Local signal and indicator computation | The [combined MangroveAI SDK guide](https://mangrovedeveloper.ai/llms-full.txt) contains matched Python and TypeScript first calls and the release-state table. Start there for application code. The TypeScript AI package `@mangrove-ai/sdk` is separate from the Markets package `@mangrove-ai/markets`. Mangrove provides deterministic risk management based on live market and account conditions. Mangrove evaluates those inputs against the user's policy and enforces the decision in the supported execution workflow. SDKs and agents submit requests and preserve the returned decision and audit information; they do not replace that enforcement. Verify the selected venue's integration and deployment before claiming it is covered. ## SDK, direct HTTP or MCP Use an SDK for server-side application code. Use [direct REST](https://mangrovedeveloper.ai/llms-full.txt) when you need an operation-specific HTTP integration. Use the [hosted MCP guide](https://mangrovedeveloper.ai/llms-full.txt) for a compatible agent client and current tool discovery. REST methods and MCP tools are separate contracts; do not infer parity from a similar name. The [local Mangrove Agent](https://github.com/MangroveTechnologies/mangrove-agent) is another integration with its own credentials, signing and catalog. It is not an npm replacement for the hosted MangroveAI API. --- ## Guide: MangroveAI SDKs (Python and TypeScript) # MangroveAI SDKs Use these clients for the managed MangroveAI REST API. The supported first task in either language is a read of the authenticated developer's usage metrics. It does not run compute, create a wallet or place an order. ## Packages and release state | Client | Published version used by these examples | | --- | --- | | Python `mangroveai`, import `mangrove_ai` | [PyPI 2.3.0](https://pypi.org/project/mangroveai/2.3.0/) | | TypeScript `@mangrove-ai/sdk` | [npm 1.1.0](https://www.npmjs.com/package/@mangrove-ai/sdk/v/1.1.0) | ## Python first call Requires Python 3.10 or later. Install the published package in your application environment: ```bash python -m pip install mangroveai==2.3.0 ``` Read your API key from a secret manager or private configuration and pass it to this function: ```python from mangrove_ai import MangroveAI def get_developer_metrics(api_key: str) -> dict: with MangroveAI( api_key=api_key, load_dotenv=False, timeout=15, auto_retry=False, ) as client: metrics = client.users.get_my_metrics() return metrics.model_dump(mode="json") ``` The distribution name and import name differ. Use `mangrove_ai`; no `jwt=` constructor is documented here. For session authentication use the SDK's actual auth service contract, rather than inventing a constructor option. ## TypeScript first call The package requires Node.js 20 or later and ESM. Install the published package: ```bash npm install @mangrove-ai/sdk@1.1.0 ``` ```typescript import { MangroveAI } from "@mangrove-ai/sdk"; export const getDeveloperMetrics = async (apiKey: string) => { const client = new MangroveAI({ apiKey, timeoutMs: 15_000 }); return client.users.getMyMetrics(); }; ``` For custom deployments, Python `base_url` is the versioned API base (ending in `/api/v1`); TypeScript `baseUrl` accepts the API origin and normalizes a supplied versioned base. Verify the exact environment rather than silently targeting production. For `dev_` and `test_` keys, configure the intended base URL explicitly. The examples do not provision a test endpoint, and a test key must not silently use the production default. The SDK's protected runtime configuration can supply `MANGROVE_BASE_URL`; never put credentials in that URL. With the default production configuration, both methods call `GET https://api.mangrovedeveloper.ai/api/v1/users/me/metrics` with `Authorization: Bearer`. They return the `metrics` object after checking the `success`/`metrics` envelope. Metrics include optional counts such as `messages_count` and `backtests_count`. Missing or null values remain unknown; do not convert them to zero. These are developer usage metrics, not brokerage balances or positions. Download [the Python example](https://mangrovedeveloper.ai/examples/first_sdk_call.py), [the JavaScript example for the TypeScript package](https://mangrovedeveloper.ai/examples/first_sdk_call.mjs), and [their private-configuration instructions](https://mangrovedeveloper.ai/examples/first-sdk-call.md). The JavaScript file uses the built package's public ESM interface; TypeScript applications also receive its declarations. ## Shared capability boundaries | Workflow | Supported contract and limits | | --- | --- | | First authenticated read | Python `users.get_my_metrics()` and TypeScript `users.getMyMetrics()` | | Other managed REST operations | Python domain methods and TypeScript's operation-keyed `request` use their checked contracts. Check the exact operation and response; do not assume every API has a convenience method | | Oracle proxy | Separate `https://mangrovedeveloper.ai/openapi-oracle.json` contract is a release dependency. It covers the supported proxy allowlist; adapted or unspecified results remain opaque | | Execution configuration | The separately published [execution configuration JSON Schema](https://mangrovedeveloper.ai/execution-config.schema.json) describes authoring fields and runtime-derived defaults; the server remains authoritative for validation and live runtime behavior | | Hosted MCP | Separate protocol initialization and `tools/list`; neither first-call method executes a tool or makes a payment | | Execution records | MangroveAI's strategy execution positions and trades describe its strategy records, not all positions held at a broker | | Broker authorization, balances and orders | Separate [Markets SDK workflow](https://mangrovedeveloper.ai/llms-full.txt); do not invent `users.create`, broker positions or Alpaca OAuth methods for these AI clients | Mangrove provides deterministic risk management based on live market and account conditions. Mangrove-owned execution software evaluates the live inputs against the user's policy and enforces the decision in supported workflows, including the local Mangrove Agent where supported. SDKs and connected AI clients request supported actions and retain the returned decision, reason and audit identifiers when supplied. They must not infer approval from a missing decision or claim enforcement for an unverified venue. ## Errors and retries Use finite request timeouts. The examples disable Python's automatic retry and the TypeScript client does not retry automatically. A `401` is an authentication failure, `403` an access denial, `402` a payment requirement, `429` a rate limit, and `503` an unavailable dependency. Receiving a payment requirement is not permission to pay. The Python client exposes typed `APIError` subclasses with `status_code`, `retry_after` and `correlation_id` when supplied. The TypeScript client exposes `APIError` with `status`, `code`, `correlationId` and `retryAfter`, plus configuration, malformed-response, timeout, cancellation and network errors. Retain safe correlation identifiers; keep credentials and private responses out of logs. Do not automatically retry an order or paid request after an uncertain outcome. ## Contracts and source - [Registered REST OpenAPI specification](https://mangrovedeveloper.ai/openapi.json): OpenAPI. Some responses are unspecified or opaque; a valid schema is not proof of complete response typing. - [Execution configuration JSON Schema](https://mangrovedeveloper.ai/execution-config.schema.json): current authoring fields and runtime-derived defaults. Runtime validation remains server-owned. - [Quickstart](https://mangrovedeveloper.ai/llms-full.txt) and [Build with AI](https://mangrovedeveloper.ai/llms-full.txt). - [Python registry](https://pypi.org/project/mangroveai/2.3.0/) and [TypeScript registry](https://www.npmjs.com/package/@mangrove-ai/sdk/v/1.1.0). --- ## Guide: Mangrove Markets SDKs # Mangrove Markets SDKs Markets SDKs handle wallet, DEX and supported venue workflows. Marketplace products, listings, offers and escrow are currently under construction; an SDK method or published schema does not establish that those workflows are available. The Markets clients are separate from the [MangroveAI Python/TypeScript clients](https://mangrovedeveloper.ai/llms-full.txt). `@mangrove-ai/markets` is the Markets package; it does not provide MangroveAI's developer usage API. ## Published packages Mangrove Markets uses separate packages from the MangroveAI API clients: ```bash python -m pip install mangrovemarkets==1.1.1 npm install @mangrove-ai/markets@0.4.0 ``` ## Product and custody boundaries - The TypeScript client is `MangroveClient`; Python uses `MangroveMarkets`. Neither is the AI API's `MangroveAI` constructor. - Marketplace product workflows remain under construction even where method or schema names are present. Check the selected package's documentation and the service's availability before relying on a workflow. - The supported billing modes for DEX requests are `standard` and `x402`, not `fusion`. Selecting a mode is not evidence that a payment was authorized or completed. Preserve receiver-owned payment requirements and receipts. - Keep private keys inside your custody/signing system. Local wallet signing and an OAuth-linked broker account have different custody models. - Configure the explicit Markets API origin confirmed for your deployment. Do not infer an endpoint from a marketing hostname or assume an `api.` subdomain exists; the SDK examples require explicit configuration. Do not substitute the MangroveAI API origin. ## Signing for DEX operations A signer is required only for operations that need local transaction signing. Use the package's exported types rather than a handwritten signer contract: ```typescript import type { Signer, UnsignedTransaction } from "@mangrove-ai/markets"; type SigningAdapter = Pick; type TransactionToSign = UnsignedTransaction; ``` `getAddress()` returns a public address, `getSupportedChainIds()` returns supported chain IDs, and `signTransaction(tx)` returns signed bytes. `signMessage` is not a required method. Select a signer that supports the transaction's chain. Keep keys inside your custody/signing system. Get token address, chain and decimals from authoritative backend or venue metadata for the selected transaction. A token symbol is not sufficient to identify a contract; do not reuse an address from a different chain. ## Risk and uncertain outcomes Mangrove provides deterministic risk management based on live market and account conditions. Mangrove evaluates those inputs against user policy and enforces its decision in supported execution workflows. The SDK and agent request the action and preserve returned decisions and audit information. A client-side check, an order validation response or OAuth consent alone does not prove that a particular venue is integrated with that enforcement path. Do not automatically pay, sign, submit or replay an order after a timeout. Preserve the operation identity and reconcile the actual venue result. Read the exact result and payment metadata; missing evidence is unavailable, not successful or free. ## Source and guides - [Python registry](https://pypi.org/project/mangrovemarkets/) - [TypeScript registry](https://www.npmjs.com/package/@mangrove-ai/markets) - [Markets source](https://github.com/MangroveTechnologies/MangroveMarkets) - Markets MCP guide - [MangroveAI SDK guide](https://mangrovedeveloper.ai/llms-full.txt) --- ## Guide: Hosted MangroveAI MCP # Hosted MangroveAI MCP Connect a compatible MCP client to `https://api.mangrovedeveloper.ai/mcp/`. MangroveAI exposes strategy, signal, backtesting, knowledge and execution capabilities through its current catalog. Inspect that catalog rather than assuming a fixed tool count or copying a local agent's names. ## Connection and discovery Configure the endpoint as Streamable HTTP in your client's supported MCP settings. When authentication is needed, use its protected header configuration with `X-API-Key` or `Authorization: Bearer`. Do not place real credentials in prompts or a shared project file. ## Current hosted HTTP handshake The current `/mcp/` transport accepts JSON-RPC `POST` requests and returns JSON request/response messages. Send `Content-Type: application/json` and `Accept: application/json`. It does not allocate or require `Mcp-Session-Id`, open an SSE stream, or support a separate GET event stream. Do not generate session creation, event-stream parsing or a DELETE-session step for this endpoint. For a general client that must also handle other MCP transport implementations, use an MCP SDK. First, POST this anonymous initialization request: ```json { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": { "name": "my-mangrove-client", "version": "1.0" } } } ``` An HTTP 200 JSON response contains the negotiated protocol and server information. Its shape is: ```json { "jsonrpc": "2.0", "id": 1, "result": { "protocolVersion": "2025-06-18", "capabilities": { "tools": { "listChanged": false } }, "serverInfo": { "name": "MangroveAI", "version": "" } } } ``` Read the actual `result.protocolVersion`, `result.capabilities` and `result.serverInfo`; do not hard-code the illustrative server version. The current advertised protocol is `2025-06-18`. If your client cannot support the returned version, stop with a protocol error. For subsequent requests send `MCP-Protocol-Version` with the negotiated version. Next POST the initialized notification. It has no `id`: ```json { "jsonrpc": "2.0", "method": "notifications/initialized", "params": {} } ``` The current server acknowledges this notification with HTTP **202 and an empty body**. Do not attempt to parse that acknowledgement as JSON. Finally POST the following catalog request with `MCP-Protocol-Version: 2025-06-18` (or the supported version actually negotiated): ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": { "_meta": { "mangrove/include_pricing": true } } } ``` Read `result.tools` for names, descriptions, input schemas and annotations. Receiver-owned pricing is supplied, when available, in `result._meta["mangrove/pricing"]`. That metadata may also describe REST-only operations; it does not make them callable MCP tools. Missing pricing metadata is an unavailable price, not a zero price. `tools/list` is a protocol method. It is not a tool named `list_tools`. For progressive discovery, inspect the advertised `discover_tools` input schema, then select a functional area or exact tool names as that schema allows. Only call tools that the current endpoint advertises. The public [MCP discovery document](https://mangrovedeveloper.ai/.well-known/mcp.json) and [x402 discovery pointer](https://mangrovedeveloper.ai/.well-known/x402) describe this project's endpoints and catalog method. These project metadata files are navigation aids; the live server's protocol and authorization responses are authoritative. ## A safe integration sequence 1. Connect and initialize using the MCP client's supported lifecycle. 2. Request `tools/list` without credentials to inspect the public catalog and current pricing metadata. 3. Inspect the selected input schema and establish the required account access and scopes. 4. For strategy composition or backtesting, load the server's advertised workflow skill and follow its current requirements. Do not reconstruct an old server workflow from a local copy. 5. Preview any paid computation or mutation and obtain approval before executing it. Record operation identifiers and safe correlation identifiers; keep credentials out of logs. 6. If a result is unavailable or an execution outcome is uncertain, report it and reconcile the original operation. Do not convert uncertainty into another order or payment. ## Deterministic enforcement Mangrove provides deterministic risk management based on live market and account conditions. Mangrove evaluates those inputs against the user's policy and enforces the decision in the supported execution workflow. An agent or SDK submits requests and preserves the returned decision and audit information; it does not run the checks. A successful catalog request is not an execution approval. Verify the venue and deployed path before claiming enforcement coverage. ## Hosted and local responsibilities Hosted MangroveAI supplies managed APIs and workflow tools. The [local Mangrove Agent](https://github.com/MangroveTechnologies/mangrove-agent) adds local custody, signing, scheduling and execution records. Their catalogs differ. A hosted developer key does not provision a local wallet or connect a broker account. Use the [agent's current client guide](https://github.com/MangroveTechnologies/mangrove-agent/blob/main/docs/clients.md) for local setup. Broker-held balances and local wallet signing have different custody models. Describe the actual venue and key handling rather than making a blanket custody claim. ## REST clients Application code should start with the [Python/TypeScript SDK guide](https://mangrovedeveloper.ai/llms-full.txt), which identifies the published packages used by these examples. Direct HTTP is an alternative using the [registered REST specification](https://mangrovedeveloper.ai/openapi.json). The [Oracle proxy contract](https://mangrovedeveloper.ai/openapi-oracle.json) is separate; neither contract describes every live MCP tool. REST authentication uses `Authorization: Bearer`; hosted MCP additionally accepts `X-API-Key`. REST operation schemas and MCP tool input schemas are distinct contracts. Do not assume there is a universal REST bridge for every MCP server. See [Build with AI](https://mangrovedeveloper.ai/llms-full.txt), [Quickstart](https://mangrovedeveloper.ai/llms-full.txt) and [Authentication](https://mangrovedeveloper.ai/llms-full.txt). --- ## Guide: MCP Servers Overview # MCP Servers Mangrove services expose MCP tools for different responsibilities. Select the intended service and inspect its live catalog before making business calls. Hosted service catalogs and the local Mangrove Agent are different surfaces; there is no single fixed tool count for all of them. ## Hosted MangroveAI Use `https://api.mangrovedeveloper.ai/mcp/` for managed strategy, signal, backtesting, knowledge and execution tools. Start with the protocol's anonymous `tools/list` method. Read the advertised `discover_tools` schema for progressive selection. Do not assume that a local tool named `list_tools` exists on the hosted endpoint. See the [Hosted MangroveAI MCP guide](https://mangrovedeveloper.ai/llms-full.txt) for authentication, pricing discovery and the safe execution sequence. ## Other Mangrove services - MangroveMarkets documents DEX and marketplace integration. Check the service's live catalog and availability before relying on a capability. - MangroveKnowledgeBase documents signal and indicator resources. - [Local Mangrove Agent](https://github.com/MangroveTechnologies/mangrove-agent) adds local wallet custody, signing, scheduling and execution records. Each service owns its transport, authentication, pricing and operation schemas. Do not apply MangroveAI's authentication header or x402 behavior to every service. Legacy listings and old examples are not evidence that an endpoint is currently available. ## MCP or REST Use MCP when the agent needs live discovery and typed tool calls. Use REST when application code needs a documented HTTP operation; the [OpenAPI specification](https://mangrovedeveloper.ai/openapi.json) describes the registered public MangroveAI REST contract. MCP input schemas and REST request schemas can differ. There is no assumed universal `/api/v1/tools/{tool_name}` bridge. Reference files provide coding context. They do not connect a client, authenticate an account, authorize a payment, or approve a trade. Follow [Build with AI](https://mangrovedeveloper.ai/llms-full.txt) for the authoring workflow and [Authentication](https://mangrovedeveloper.ai/llms-full.txt) for access. --- ## Guide: API Reference Overview # API Reference Overview Use the apex developer site's [OpenAPI specification](https://mangrovedeveloper.ai/openapi.json) as a public reference for the registered public REST operations. A schema reference does not prove that every operation is available for a particular account or deployment. Some responses have no declared shape or intentionally remain opaque; this schema does not prove complete generated-client typing. MCP tools have their own live input schemas. The separate [execution configuration JSON Schema](https://mangrovedeveloper.ai/execution-config.schema.json) describes current authoring fields and runtime-derived defaults. Runtime validation and policy enforcement remain owned by Mangrove execution software. The separate [Oracle proxy contract](https://mangrovedeveloper.ai/openapi-oracle.json) is a reference for the supported proxy operations and opaque adapted envelopes. Check the documented API host and verify deployment availability before use. Do not assume the RESTX exporter includes dynamically proxied operations. The API origin is `https://api.mangrovedeveloper.ai`. Use the exact path in the schema, including its API version. Most public REST resources are under `/api/v1`; the specification also includes registered public version-two routes. Do not prepend an API version twice. ## Capability areas | Area | Guide | Integration responsibility | | --- | --- | --- | | Strategies | Strategies | Saved definitions, ownership, validation and lifecycle | | Signals | Signals | Available signals and their parameter schemas | | Backtesting | Backtesting | Submitted jobs and recorded results | | Strategy Engine | Oracle Backtest, Sweeps, SIEVE | Compute workflows with their own schemas, access rules and costs | | Execution | Execution | Strategy execution records; these positions/trades are not all holdings at a broker | | AI assistant | AI Assistant | Account-scoped conversation and agent workflows | | Market and asset data | Market Data, Crypto Assets | Specific data operations and source requirements | | DeFi, social and on-chain | DeFi, Social, On-Chain | Operation-specific provider data | | Account access | [Authentication](https://mangrovedeveloper.ai/llms-full.txt), Usage | Keys, scopes, entitlements and developer usage | The topic guides explain concepts and examples. Resolve any endpoint-field disagreement using the current canonical schema and verify actual deployment availability before production integration. Not every MCP or payment-only endpoint is represented in the registered REST schema. ## Request and response handling REST authentication uses `Authorization: Bearer YOUR_API_KEY`. Start with the SDK metrics read in the [quickstart](https://mangrovedeveloper.ai/llms-full.txt). Check the HTTP status before consuming the body, then validate the operation's documented fields. Responses are not universally wrapped in `data`. For example, the developer metrics read returns `success` and `metrics`; other operations use their own envelopes. Pagination also varies by operation; use its declared parameters and response fields. Common status meanings include `400` for invalid input, `401` for missing or invalid credentials, `403` for a permission or entitlement denial, `402` for payment requirements, `404` for a missing resource, `409` for a conflict, `429` for rate limiting, and `503` for an unavailable dependency. Read the returned error message and retain a safe correlation identifier. Do not log secrets or private account data. Use a finite timeout for every request and bounded retry rules. Honor `Retry-After` when supplied. Do not automatically retry mutations, paid computation or orders after an uncertain response; preserve the original operation identity and reconcile it. ## Reference availability The apex developer site serves the current API reference at `/openapi.json`. Use its execution configuration reference for runtime-derived defaults; account permissions and workflow acceptance require separate verification. The separate `mangrove.io` application proxy fetches and validates its API source; that dynamic route returns `503` with a JSON error if the source is unavailable or invalid. The plain-text [full AI integration overview](https://mangrovedeveloper.ai/llms-full.txt) is generated from the reviewed onboarding guides; [llms.txt](https://mangrovedeveloper.ai/llms.txt) is the concise index.