Agent-safe financial workflows

The problem with generic payment APIs

When an AI agent tries to integrate a broad payment platform, it faces a state problem: the API has hundreds of endpoints, stateful onboarding flows, and side effects that are hard to reason about without reading long documentation. The agent makes calls, gets ambiguous errors, and either hallucinates a fix or asks the developer to step in.

Soledgic is scoped differently. Every operation maps to a named resource with a predictable lifecycle, and sensitive movement stays behind scoped keys, idempotency, policy checks, signed webhooks, and audit logs. An agent can derive the next step from state without inventing financial logic.

A deterministic resource flow

The entire platform treasury flow is five resources in sequence. An agent can hardcode this path and handle every mainstream use case:

Each step has a single required predecessor. An agent that tracks which resources exist can always determine which call to make next.

Semantic operationIds

Every endpoint in the Soledgic OpenAPI spec uses a camelCase verb+noun operationId that describes intent, not implementation. AI agents use operationIds to generate function calls — the name alone should tell the agent what the operation does and when to use it.

The full spec is available at soledgic.com/openapi.yaml and via the SDK's built-in types.

Self-healing error responses

When an agent makes a mistake — missing a required field, wrong ordering, insufficient balance — Soledgic returns a structured hint field alongside the error message. The agent reads the hint and generates the missing step without requiring a human to intervene.

{
  "success": false,
  "error": "Participant not found",
  "error_code": "participant_not_found",
  "hint": "Create the participant first: POST /v1/participants with participant_id, display_name, and email.",
  "request_id": "req_abc123"
}

Every 4xx response that matches a known failure pattern includes a hint. The hint always specifies the exact endpoint and parameters needed to recover.

Agent-generated integrations can verify themselves

After generating an integration, an AI agent can run soledgic doctor to validate the environment before the developer looks at the screen:

npx soledgic doctor

  soledgic doctor

  ✓  API key found
  ✓  Key type: test  safe to use in development
  ✓  API reachable  https://api.soledgic.com/v1/health-check -> 200
  !  SOLEDGIC_WEBHOOK_SECRET not set
       Set this if you receive webhooks.

  All checks passed.

The command checks key format, API reachability, and webhook secret configuration — the three things that cause 90% of integration failures.

Safe for guarded retry loops

Treasury writes use stable reference_id values for deduplication. An agent that retries a failed payout request with the same reference_id will not create a duplicate payout — Soledgic returns the original result.

IDE rules file

Drop soledgic.cursorrules into your project root as .cursorrules. Cursor, Windsurf, and Copilot will read it and write correct Soledgic code by default — right amounts in cents, webhook verification, idempotency keys, and the correct resource order.

MCP server

The @soledgic/mcp package lets AI agents (Claude Desktop, Cursor, Devin) call Soledgic tools natively — no manual API wiring required. Add it to your MCP client config:

{
  "mcpServers": {
    "soledgic": {
      "command": "npx",
      "args": ["-y", "@soledgic/mcp@latest"],
      "env": {
        "SOLEDGIC_API_KEY": "slk_test_your_key"
      }
    }
  }
}

Available tools: get_api_status, create_checkout, upsert_user_wallet, list_wallet_activity, request_refund, complete_sandbox_checkout, and more. Read-only by default. Enable write tools only for sandbox projects or guarded workflows where your app controls approvals, idempotency, and audit logging.