<SYSTEM>This is the full developer documentation for Minmo</SYSTEM>

# Build with Minmo

> Give your coding agent reliable context, then build a typed server-side integration with the public Minmo SDK.

## Give your agent the right context

[Section titled “Give your agent the right context”](#give-your-agent-the-right-context)

Start with the small, machine-readable index. It points an agent to the pages that matter instead of asking it to ingest the whole site:

```text
https://docs.minmo.to/llms.txt
```

Then give it a concrete task and these constraints:

```text
Build a server-side Minmo integration for [describe the workflow].


Read https://docs.minmo.to/llms.txt and fetch only the relevant Markdown pages.
Use @minmoto/sdk 0.3.0 and inspect its exported types before implementing.
Keep MINMO_PARTNER_ID and MINMO_API_KEY in server environment variables.
Start with a read-only account request. Do not invent SDK methods or capabilities.
Type-check the integration and state what was actually tested.
```

## Choose your integration path

[Section titled “Choose your integration path”](#choose-your-integration-path)

### Use the Minmo SDK

[Section titled “Use the Minmo SDK”](#use-the-minmo-sdk)

For Node.js and TypeScript backends, use the supported, typed [`@minmoto/sdk` client](/sdk/). Follow the [quickstart](/sdk/quickstart/) to make a first read-only request, then explore the capabilities you need.

### Use the Minmo API

[Section titled “Use the Minmo API”](#use-the-minmo-api)

For another runtime, or when you need the protocol beneath the SDK, open the [environment-specific OpenAPI document](/openapi.json) in a new tab. Treat the SDK as the default integration surface whenever your runtime supports it.

## Use focused, machine-readable references

[Section titled “Use focused, machine-readable references”](#use-focused-machine-readable-references)

| Resource                                                           | Purpose                                                      |
| ------------------------------------------------------------------ | ------------------------------------------------------------ |
| [/llms.txt](/llms.txt)                                             | Discover the recommended documentation and context bundles   |
| [/markdown/index.json](/markdown/index.json)                       | List every individual Markdown export                        |
| [/markdown/sdk/quickstart.md](/markdown/sdk/quickstart.md)         | Install and initialize the public SDK                        |
| [/markdown/sdk/authentication.md](/markdown/sdk/authentication.md) | Handle credentials, capabilities, errors, and retries        |
| [/openapi.json](/openapi.json)                                     | Open the live OpenAPI document for this environment          |
| [/llms-full.txt](/llms-full.txt)                                   | Load all guides when a tool supports a larger context window |

Examples are compiled against the pinned public SDK during this app’s checks. That verifies the interface, not access to a capability or a live money-moving flow.

# Overview

> Build wallets, payments, swaps, escrow, Partner operations, and live events with the public Minmo SDK.

The public **`@minmoto/sdk`** package is the primary programmability surface for Minmo. Use its typed, Partner-bound client to build backend integrations.

* [Quickstart](/sdk/quickstart/) — install the package and read your Partner account.
* [Capabilities](/sdk/capabilities/) — find the right resource for your workflow.
* [Authentication](/sdk/authentication/) — configure credentials and capability scope.
* [Events](/sdk/events/) — react to live changes and reconcile authoritative state.
* [OpenAPI document](/openapi.json) — inspect the underlying HTTP interface in a new tab.

These guides target **SDK 0.3.0**. They cover the public npm package, not Mini’s internal SDK. Your Partner’s configuration and API-key capabilities determine which operations are available to your integration.

## Start building

[Section titled “Start building”](#start-building)

```sh
npm install @minmoto/sdk@0.3.0
```

You need a Minmo Partner ID and a Partner API key. Run the SDK in trusted server code. Follow the [quickstart](/sdk/quickstart/) for a complete example.

## Source and support

[Section titled “Source and support”](#source-and-support)

* [SDK on npm](https://www.npmjs.com/package/@minmoto/sdk)
* [Public SDK source and issues](https://github.com/minmoto/sdk)
* [Minmo Console](https://console.minmo.to)

# Quickstart

> Install the public SDK and connect a server-side service to your Partner account.

## Prerequisites

[Section titled “Prerequisites”](#prerequisites)

* Node.js 22 or newer.
* A Minmo Partner ID and Partner API key with the permissions your integration needs.
* A server-side TypeScript project.

Create the key in Console’s API-key management area. Store `MINMO_PARTNER_ID` and `MINMO_API_KEY` in your server environment or secrets manager.

## Install

[Section titled “Install”](#install)

```sh
npm install @minmoto/sdk@0.3.0
```

## Connect

[Section titled “Connect”](#connect)

```ts
import { MinmoClient } from "@minmoto/sdk";


const minmo = new MinmoClient({
  partnerId: process.env.MINMO_PARTNER_ID!,
  apiKey: process.env.MINMO_API_KEY!,
});


const partner = await minmo.account.get();
console.log(`Connected to ${partner.displayName}`);
```

This reads the Partner account without creating a payment or moving funds. The SDK uses the production service by default. Supply `baseUrl` only when connecting to another Minmo deployment with matching credentials.

## Next steps

[Section titled “Next steps”](#next-steps)

Read [authentication](/sdk/authentication/), choose a resource from [capabilities](/sdk/capabilities/), and use [events](/sdk/events/) to react to changes.

# Authentication

> Configure Partner credentials and handle SDK errors in trusted server code.

The public SDK accepts `partnerId` and `apiKey`. It sends the key using `X-API-Key` and scopes Partner resources to the configured Partner. It does not expose the internal SDK’s bearer-token or token-provider helpers.

Keep API keys in server-side secrets. Never place them in browser bundles, mobile apps, public environment variables, logs, or prompts sent to AI tools. Grant each key only the capabilities its integration needs.

## Handle errors

[Section titled “Handle errors”](#handle-errors)

```ts
import { MinmoClient, MinmoSdkError } from "@minmoto/sdk";


const minmo = new MinmoClient({
  partnerId: process.env.MINMO_PARTNER_ID!,
  apiKey: process.env.MINMO_API_KEY!,
});


try {
  await minmo.account.get();
} catch (error) {
  if (error instanceof MinmoSdkError) {
    console.error({
      code: error.code,
      status: error.status,
      requestId: error.requestId,
      retryable: error.retryable,
    });
  }
  throw error;
}
```

Use `retryable` as an input to a bounded retry policy. Preserve idempotency keys when retrying operations that create payable resources or move money. Do not blindly retry an operation whose outcome is unknown; reconcile its state.

# Capabilities

> Find the public SDK resources for your integration.

Each `MinmoClient` is bound to the Partner ID provided at construction. The installed package’s TypeScript declarations are the method-level reference. Use your editor’s completion and type checking to inspect the exact signature for your installed version.

| Workflow                                | SDK resource                                     |
| --------------------------------------- | ------------------------------------------------ |
| Partner account and configuration       | `account`, `settings`, `analytics`               |
| Team access and integration credentials | `members`, `invitations`, `apiKeys`, `referrals` |
| Payment stores and invoices             | `integrations.pay`                               |
| Payment service providers               | `integrations.psp`                               |
| Accounting reports                      | `integrations.accounting`                        |
| Rates, swaps, and agents                | `otc.rates`, `otc.swap`, `otc.agents`            |
| Wallets                                 | `wallet`                                         |
| Escrow                                  | `escrow`                                         |
| Live domain updates                     | `events` and domain subscriptions                |

Availability depends on your Partner setup and API-key capabilities. Selecting a Partner never grants access on its own.

## Read available integration resources

[Section titled “Read available integration resources”](#read-available-integration-resources)

```ts
import { MinmoClient, SourceType } from "@minmoto/sdk";


const minmo = new MinmoClient({
  partnerId: process.env.MINMO_PARTNER_ID!,
  apiKey: process.env.MINMO_API_KEY!,
});


const stores = await minmo.integrations.pay.listStores();
const providers = await minmo.integrations.psp.listProviders();
const sources = await minmo.integrations.accounting.listSources(
  SourceType.PSP_CONNECTION,
);
```

For method details and additional examples, see the [public SDK README](https://github.com/minmoto/sdk#readme).

# Events

> Subscribe to domain changes and read authoritative resource state.

Domain clients expose subscriptions alongside their commands and queries. For example, subscribe to Minmo Pay changes:

```ts
import { MinmoClient } from "@minmoto/sdk";


const minmo = new MinmoClient({
  partnerId: process.env.MINMO_PARTNER_ID!,
  apiKey: process.env.MINMO_API_KEY!,
});


const subscription = minmo.integrations.pay.events({
  onEvent(event) {
    console.log(event.type, event.id);
  },
  onError(error) {
    console.error("Minmo Pay event stream failed", error.message);
  },
});


await subscription.ready;


// Close during application shutdown, after finishing your workflow.
await subscription.close();
```

Treat an event as a signal that something changed. Re-read the relevant SDK resource when current state matters. Design handlers to tolerate duplicate events and reconnects, and handle an authoritative resync when required.

This is an SDK event stream, not a generic webhook setup procedure.