---
title: "Build stablecoin payins with AI agents: API, MCP server, Agent Skills, and CLI"
seoTitle: "Stablecoin payins with AI agents: MCP, Skills, CLI"
description: "Build stablecoin payins with AI coding agents using BlindPay's API, MCP server, Agent Skills, and CLI. Setup in 6 steps, a task map, and guardrails."
date: "2026-10-30"
category: "stablecoins"
author: "BlindPay Team"
howto:
  name: "How to build stablecoin payins with an AI coding agent"
  steps:
    - name: "Start on a development instance"
      text: "Create a development instance and decide what the agent may touch. Development uses the USDB test token and no real money moves."
    - name: "Connect the MCP server"
      text: "Add https://mcp.blindpay.com/mcp to your agent, sign in with your BlindPay account, and pick the development instance. No API key goes into the client."
    - name: "Add Agent Skills and the payin prompt"
      text: "Run npx skills add blindpaylabs/skills, then give the agent the payin quickstart prompt so it knows the gotchas such as minor units and the 5-minute quote."
    - name: "Let the agent build the payin flow"
      text: "Ask it to create a customer, link a wallet, quote and create a payin, and write a webhook handler that verifies signatures and deduplicates on svix-id."
    - name: "Have the agent test the failure paths"
      text: "Ask it to run a failed payin with request_amount 66600 and a refunded one with 77700, and to confirm the handler and ledger stay correct."
    - name: "Add guardrails before production"
      text: "Use the read-only MCP URL for exploration, keep human approval for money movement, store keys as secrets, and review the diff yourself before going live."
faq:
  - q: "Does BlindPay have an MCP server for payins?"
    a: "Yes. BlindPay hosts an MCP server at https://mcp.blindpay.com/mcp with 93 tools generated from the public API, including PostV1InstancesPayinQuotes, PostV1InstancesPayinsEvm, GetV1InstancesPayins, and GetV1InstancesPayinsById. You sign in with your BlindPay account and choose the instance the agent may use, so no API key is pasted into the client."
  - q: "Can an AI agent create a payin on its own?"
    a: "Technically yes, since payin creation is a write tool, but it should not do so unattended on production. The server does not block a call by itself. Start on a development instance, keep a confirmation step in your agent prompt, and use the read-only URL when the agent should only look."
  - q: "What are Agent Skills and how do I install them for BlindPay?"
    a: "Agent Skills are a packaged knowledge layer that teaches an agent BlindPay's rails, corridors, fees, and API patterns, so generated code is more likely to be correct the first time. Install them with the command npx skills add blindpaylabs/skills, and use them alongside the MCP server in Codex, Claude Code, Cursor, and similar hosts."
  - q: "Is there a BlindPay CLI for scripting payins?"
    a: "Yes. The BlindPay CLI installs with npm install -g @blindpay/cli and covers quotes, payins, virtual accounts, and webhook endpoints. Every command accepts a --json flag, blindpay schema returns field definitions, and exit codes are 0 for success, 1 for a user error, and 2 for an API error."
  - q: "Can I give an agent a read-only BlindPay API key?"
    a: "Not today. BlindPay API keys carry full read and write access to their instance, and a scoped or read-only key type is not yet available. For read-only access use the MCP read-only URL, https://mcp.blindpay.com/mcp/readonly, which serves only the read tools, and keep API keys for development instances."
  - q: "What if my AI app builder cannot host an MCP server?"
    a: "Builders such as Lovable, v0, Bolt, and Replit generate application code, so use the REST API from a backend route instead. Paste a prompt describing the function, store BLINDPAY_API_KEY and BLINDPAY_INSTANCE_ID as secrets in the builder, and never call BlindPay from client-side code, because that would expose your key."
---

BlindPay offers a REST API with an OpenAPI spec, a hosted MCP server, Agent Skills, and a CLI. An AI coding agent can use them to create customers, wallets, payin quotes, payins, virtual accounts, and webhook endpoints, and to read back structured results. Start on a development instance, and keep a human in the loop for money movement.

This guide is about payins: fiat in, stablecoins out. For the manual version of the same flow, read the [integration quickstart](/resources/more/stablecoin-payin-api-integration-quickstart). For the payout and FX angle, see [how AI agents get live FX quotes through MCP](/resources/more/ai-agents-live-fx-quotes-mcp).

## Key takeaways

- BlindPay gives agents four surfaces: the REST API, the MCP server, Agent Skills, and the CLI. They sit on the same API.
- The hosted MCP server uses sign-in and instance selection, so no API key goes into the client.
- API keys have full access to an instance. For read-only access, use the read-only MCP URL.
- Development instances run payins with test money. `66600` forces a failure and `77700` a refund, so an agent can practice the unhappy paths.
- The server does not block a write call on its own. Put the confirmation step in your prompt or app.

## Why do AI agents need structured payment APIs?

Agents work best when an API returns predictable fields and clear errors. A payin has exact rules: amounts are integers in minor units, a quote expires in 5 minutes, and a created payin cannot be canceled. An agent that guesses at those rules writes code that fails in production.

Structured surfaces remove the guessing. The MCP server hands the agent the call order, amount units, and the steps a person must do in the dashboard. Agent Skills teach rails and fees. The CLI returns JSON. Together they make generated payin code more likely to be correct on the first pass. Agents also need a way to see payments after the fact, which is why the same surfaces cover listing and retrieving payins.

## What does each surface do?

The four surfaces cover different working styles. Pick by where the agent runs and what it needs to do.

| Surface | Best for | Example payin task | Guardrail |
| --- | --- | --- | --- |
| REST API and OpenAPI 3.1 spec | Code the agent writes into your backend, app builders | Generate a typed client from `https://api.blindpay.com/doc` and write the payin route | Key stays server side, never in client code |
| MCP server | An agent that acts during a chat or coding session | Call `PostV1InstancesPayinQuotes`, show fees, then `PostV1InstancesPayinsEvm` after you confirm | Sign in to a development instance; use `/mcp/readonly` to look only |
| Agent Skills | Better generated code in Codex, Claude Code, Cursor | Build a webhook handler that follows BlindPay's conventions | Review the generated diff |
| CLI | Shell sessions, scripts, CI | `blindpay payin_quotes create`, then `blindpay payins create --quote-id qu_...` | Development key stored as a CI secret |

The MCP server's tools are generated from the public API, and each carries read-only or destructive annotations. The payin tools include `PostV1InstancesPayinQuotes`, `PostV1InstancesPayinsEvm`, `GetV1InstancesPayins`, and `GetV1InstancesPayinsById`. Related tools cover customers (`PostV1InstancesCustomers`), blockchain wallets (`PostV1InstancesCustomersBlockchainWallets`), virtual accounts (`PostV1InstancesCustomersVirtualAccounts`), and webhook endpoints (`PostV1InstancesWebhookEndpoints`). The full list is in the [MCP tools reference](/docs/mcp/tools).

The CLI installs with `npm install -g @blindpay/cli` and is configured with `blindpay config set --api-key <your-api-key> --instance-id <your-instance-id>`. Every command takes `--json`, `blindpay schema` returns the field definitions, and exit codes are `0`, `1`, and `2`. See the [CLI announcement](/blog/cli) for the command list.

## What can an agent safely do?

An agent can safely do anything that reads or that happens on a development instance. It should not move production money without a person approving the exact amount and recipient.

| Task | Safe by default? | Why |
| --- | --- | --- |
| Read payins, customers, wallets, webhook endpoints | Yes | Read tools; also served at the read-only URL |
| Look up rails and required bank fields | Yes | Reference data tools |
| Write payin code, webhook handlers, and tests | Yes, with review | Output is code you read before it runs |
| Create customers, quotes, and payins on development | Yes | USDB test token, no real money |
| Create a virtual account on production | Needs a person | Triggers real compliance and bank review |
| Create a payin on production | Needs a person | Confirm the amount and the destination wallet first |
| Register a production webhook or change settings | Needs a person | Affects how real events reach your systems |

Payins are the lower-risk direction, because the payer moves the fiat, but a wrong destination wallet still matters. BlindPay cannot recover stablecoins delivered to a wrong address. Treat the wallet address like a payment instruction and have a person confirm it.

## How do I set it up?

Follow these six steps. They work in Claude Code, Codex, Cursor, VS Code, and other MCP clients.

1. **Create a development instance.** Do this in the [BlindPay dashboard](https://app.blindpay.com). Customers are approved automatically and payins complete about 30 seconds after creation.
2. **Connect the MCP server.** In Claude Code run `claude mcp add --transport http blindpay https://mcp.blindpay.com/mcp`. In Codex run `codex mcp add blindpay --url https://mcp.blindpay.com/mcp`. Sign in and pick the development instance. For hosts that run only local servers, or for CI, use `npx -y @blindpay/mcp` with `BLINDPAY_API_KEY` and `BLINDPAY_INSTANCE_ID` set.
3. **Add Agent Skills.** Run `npx skills add blindpaylabs/skills`.
4. **Give the agent the payin prompt.** The [payins integration prompt](/prompts/integrate-payins) encodes the gotchas, and the [connect an AI agent prompt](/prompts/connect-ai-agent-mcp) covers the MCP setup. A task prompt that works: "Using the BlindPay tools on my development instance, create a customer, register a testnet wallet, create a payin quote for 10000 with cover_fees true, create the payin, and write a webhook handler that verifies the Svix signature and deduplicates on svix-id."
5. **Have it test failures.** Ask for a failed payin (`request_amount` `66600`) and a refunded one (`77700`), and for tests proving the ledger is correct in both. The case list is in the [payin sandbox testing checklist](/resources/more/payin-api-sandbox-testing-checklist).
6. **Review before production.** Read the diff, confirm signature verification and idempotency, and switch to production keys yourself.

The full per-platform table, including Lovable, v0, Bolt, and Replit, is in the [Build with AI docs](/docs/build-with-ai).

## What guardrails should I add?

Add guardrails at four levels: keys, environment, approval, and review.

- **Scoped access, with what exists today.** API keys carry full read and write access to one instance, and a read-only key type is not yet available. So give an agent a development key only, and use `https://mcp.blindpay.com/mcp/readonly` when it should just observe.
- **Sandbox first.** Do all building on a development instance. Switching to production means a new instance, a new API key, and a new webhook endpoint.
- **Human approval for money movement.** The MCP server does not block a call itself. Tools carry annotations, so clients that support them can ask before any non-read call, and the server tells the agent to confirm amounts and recipients on production. Keep a confirmation step in your own prompt as well.
- **Secrets hygiene.** Keep keys in environment variables or secrets, never in prompts or client code. If a key leaks, delete it and create a new one, which revokes it immediately.
- **Idempotency.** Have the agent send an `Idempotency-Key` on every create call, so a retried tool call cannot create two payins. The behavior is covered in [idempotency keys in a stablecoin API](/resources/more/stablecoin-api-idempotency-keys).
- **Disconnect when done.** You can disconnect an agent from Settings, then Connected apps, in the dashboard.

Respect the development rate limit too: 40 requests per minute per instance, which a looping agent can hit.

## What should the agent build for webhooks?

Ask it for the same handler you would write by hand: verify the `svix-id`, `svix-timestamp`, and `svix-signature` headers on the raw body, deduplicate on `svix-id`, read `status` from the payload, and never move a terminal payin backwards. The design is in [payin webhooks, idempotency, and reconciliation](/resources/more/payin-webhooks-idempotency-reconciliation). The MCP server also exposes every webhook event and its payload schema as resources under `blindpay://webhooks/events`, so the agent can check payload shapes without guessing.

## Where does BlindPay fit?

BlindPay offers the REST API with an OpenAPI 3.1 spec, official SDKs for Node.js, Python, Go, PHP, and Swift, a hosted MCP server with a read-only endpoint, a local `@blindpay/mcp` package, Agent Skills, the CLI, and prebuilt quickstart prompts. BlindPay describes itself as AI-native stablecoin infrastructure, and these are the documented surfaces behind that description. Details are on the [MCP page](/mcp).

For where agent payment protocols fit, see [AP2, ACP, and x402 compared](/resources/more/agent-payment-protocols-compared). If you are new to the payin model, begin with [what a stablecoin payin API is](/resources/more/what-is-a-stablecoin-payin-api). BlindPay's fees are shown in the quote before you create a payin. See [/pricing](/pricing).

## Sources

- BlindPay docs, [Build with AI](/docs/build-with-ai) (checked on 2026-10-30)
- BlindPay docs, [BlindPay MCP tools reference](/docs/mcp/tools) (checked on 2026-10-30)
- BlindPay, [CLI announcement](/blog/cli) (checked on 2026-10-30)
- Model Context Protocol, [introduction](https://modelcontextprotocol.io) (checked on 2026-10-30)

*This article is for general information only and is not legal, tax, or financial advice.*