Skip to content

Integrations

Mercury SDK: get started

The complete Mercury API through typed application or agent clients

Use an ordinary App, or an Agent when the workload needs agent identity. Alter builds provider requests from a reviewed contract and applies the same connection authorization, policy, approvals, and audit records as raw requests.

Terminal window
npm install @alter-ai/sdk @alter-ai/mercury
# Python (installs core automatically)
pip install alter-sdk-mercury

The provider package includes only Mercury types and response schemas and pins its contract version.

Configure Mercury OAuth or store an API token, request the scopes the application needs, and retain each customer’s grant ID after Connect consent. Alter supplies the credential; it never belongs in operation input.

import { App } from "@alter-ai/sdk";
import { MercuryIntegration } from "@alter-ai/mercury";
const app = new App({ apiKey: process.env.ALTER_API_KEY! });
try {
const client = new MercuryIntegration(app, { grantId: process.env.MERCURY_GRANT_ID! });
const result = await (await client.accounts.getAccounts({})).wait();
console.log(result.bodyJson());
} finally {
await app.close();
}
from alter_sdk import App
from alter_sdk_mercury import MercuryIntegration
async def first_call(api_key: str, grant_id: str):
async with App(api_key=api_key) as app:
client = MercuryIntegration(app, {"grant_id": grant_id})
call = await client.accounts.get_accounts({})
result = await call.wait()
return result.body_json()

Contract 2026-11-10 publishes 90 business operations from Mercury’s official machine-readable reference pages. The policy catalog contains 101 canonical routes: 90 business routes and 11 authentication protocol routes. The source review labels 103 operations, including two OAuth aliases reconciled to those protocol routes. Authentication routes are cataloged with written SDK exclusions. The API reference links every operation to its complete input fields, response models, TypeScript and Python examples, and policy identity. Browse by resource under this provider’s API reference in the Integrations sidebar, or download the pinned OpenAPI specification. The Developer Portal provider view and alter integrations operations mercury --version 2026-11-10 also expose the schemas.

Generated calls pin the Alter contract version. Mercury’s own product, role, scope and subscription requirements still apply. There is no silent version fallback and no automatic write retry or pagination.

Terminal window
alter integrations execute mercury mercury.getaccounts \
--version 2026-11-10 --grant "$MERCURY_GRANT_ID" --input '{}' --wait

Arguments use native path, query, headers, and body containers. Array query parameters are sent the way the provider’s document declares them: one delimited value where it declares explode: false (or a pipe- or space-delimited style), repeated keys otherwise. SDK methods preserve provider field names, decimal lexemes and large integers as strings when necessary. HTTP 204 returns null / None from the typed decoder. Binary responses use bodyBytes() / body_bytes(); the CLI can save them with --output-file.

A policy rule can require approval for any operation. The call returns a pending approval; wait() resolves once the approver decides, and resume(approvalId) picks a pending approval up after a restart. Approval cards show the operation, its contract version and the request input the sensitivity review marked safe to display.

Recipient and transaction attachment uploads accept a file object with filename, content_type and content_base64. The serialized input must fit the shared 5 MiB proxy limit. File bytes are sensitive. An approval holds the complete upload encrypted in Vault, masks its file fields for approvers, and executes the frozen upload after approval. Keep the required file object in the request; removing it makes the upload invalid.

Payment rules cover transfers, payment requests, funding destinations and the reviewed spend-limit changes. Send rules cover delivery to recipients, invoice/customer notifications and caller-chosen webhook or Request Object destinations. Removing an entire resource, disabling a card or webhook, and closing a relationship carry delete; overwriting an ordinary field carries write. Conditional effects inspect the actual arguments, and unreadable discriminators fail closed. Logout carries delete and send even without an explicit callback because recipient notifications cannot be ruled out. The duplicateCheckOverride boolean is policy-visible on both payment routes: it intentionally skips repeated-payment screening. Mercury checks an approval request when it is created, without repeating that check at approval. Protocol fields remain unjudgeable when a comparison would lose case, ordering or effective values hidden in signed Request Objects; rules reading those fields fail closed.

Five protocol routes carry credential gates and have no SDK method: four issuance-capable routes and revocation of the connection’s own credential. The documented nonce-only UserInfo-credential priming request is exempt from the issuance gate; unknown shapes, extra members and proof-bearing requests retain it. Device initiation returns pending-flow secrets without a credential gate. UserInfo credential issuance is included because its holder-bound identity assertion authenticates a person to third parties, even without banking access. The other authentication protocol routes also have no SDK method: they remain visible to policy, with individual exclusion reasons. Card-reveal responses mask the card number, CVC and expiration fields in payload capture while preserving eligible non-sensitive metadata. Response masking follows the reviewed schema locations for each operation; a private holder name does not cause an ordinary category name to be masked. Issuing an upload URL is marked secret output and withholds the whole capture. Sensitive bank details, files and webhook secrets are held encrypted for approval and masked in approver views and retained payloads. The application’s capture setting still governs all other eligible bodies. Binary responses are never captured.

An operator can permit a default-refused credential operation with a credential_minting allowance scoped to the exact operation and one named API key or agent. Mercury allowances require that caller’s metadata ID, an absolute expiry and a written reason. The exception can allow the call or require approval for each call; it does not grant access to other callers or operations, and stops working at expiry. Create and inspect these allowances in the dev portal or with alter rules create and alter rules get.

Mercury reports request failures through HTTP status. Transaction, card and approval status fields describe business resources; they are not treated as generic failures in a successful HTTP response. Partner onboarding and token permissions still determine which operations Mercury accepts.

The pinned official source, its hash, the generated methods and the policy mapping are checked together. Scheduled checks save upstream candidates and report additions, removals and schema changes; they never replace a published contract automatically. Existing contract versions remain available for installed SDKs and pending approvals.

Persist call.approvalId (TypeScript) or call.approval_id (Python), then construct a fresh provider client and call resume(savedId), followed by wait(). The stored approval selects the operation; this installed package verifies its provider and contract version before attaching the response validator. Mismatches raise ManagedOperationError, never silently decode using another contract. See persist-and-resume examples.

Policy operation fields also accept the published SDK function IDs listed by alter integrations operations mercury. Use when.operation for a json_match or conditional require_approval rule, or match.operations for content_match (including redaction and step-up). Conditional approval can also use when.match.operations with parameter conditions. alter policy simulate --operation <function-id> tests that exact function.

Managed calls carry a server-verified function identity. Alter still evaluates policy against the actual method, URL and body after building the request from the authorized connection. The reviewed family labels apply directly to every request. This catalog changes the previous labels on existing routes; the owner approved those breaking changes because Mercury has no live usage. A raw call can share an endpoint with several SDK functions and matches all of them; a function name never grants permission or bypasses existing restrictions.

For example, this rule requires approval for one function:

{
"effect": "require_approval",
"when": { "operation": "mercury.createcategory" },
"approval": { "approvers": ["reviewer@example.com"] }
}

Save it with alter policy rules create --app <app-id> --grant <grant-id> --type require_approval --body @rule.json, or select the function in the portal.

User-directory pagination cursors are user identifiers. start_after and end_before remain policy selectors and are masked in approval displays; nextPage and previousPage are masked in eligible captures. An approved request carrying a classified sensitive cursor has both capture bodies withheld under the shared held-request contract. Its exact request still reaches Mercury, and its response still reaches the caller.

For operations using reviewed response schemas, captures withhold non-success response bodies and bodies whose status is unknown. Error envelopes can contain private values outside the success schema; request capture and status metadata remain available. Raw proxy calls, SDK-reported calls and approved execution apply the same protection.

Report an issue with this page

Necessary

Required for sign-in, security, authorization, and remembering your choices.

Always active

Analytics

Helps us understand which product and documentation features are useful.

Performance diagnostics

Uses performance tracing and privacy-masked session replay to diagnose problems.

You can change these choices at any time from Cookie settings.