canonical: https://jentic.com/apis/luniumpay.com/luniumpay

# Luniumpay Lunium — crypto ⇄ PIX settlement (Brazil)

The Lunium API settles between crypto and PIX in Brazil: it generates PIX charges that either credit a BRL custody balance or deliver crypto to a wallet, sends PIX payouts from that balance, and converts external crypto into a PIX payment through a three-step quote, accept, and track flow. It also withdraws BRL balance as crypto to a self-custodial wallet, moves funds between customer subaccounts, runs a USDT wallet that can pay a Pix, and verifies that a PIX happened by its E2E identifier without a key. A sandbox simulates cash-in, custody, payouts, crypto withdrawals, transfers, and cash-out with fictitious funds, and production and sandbox are told apart by lun_ and lun_test_ keys sent in the X-API-Key header.

## For AI agents

Create PIX charges that credit BRL custody or deliver crypto, send PIX payouts, quote and execute crypto-to-PIX cash-outs, and check balances in Lunium. Uses an X-API-Key; a free sandbox key simulates every flow.

## Scope

Does not process card payments, issue invoices, or trade crypto on an exchange order book. Use for PIX collection, BRL custody, PIX payouts, and crypto-to-PIX settlement in Brazil only.

## Capabilities

- Generate a PIX charge with amount_cents and payer_tax_number that credits BRL custody (destino saldo) or delivers crypto (destino cripto) via POST `/cashin/charge`
- Send a PIX payout from the available BRL balance to a pix_key through POST /payouts, up to R$ 6.000,00 per PIX
- Quote, accept, and track an external crypto-to-PIX cash-out with POST /cash-outs, POST `/cash-outs/{cashout_id}/accept`, and GET `/cash-outs/{cashout_id}`
- Withdraw BRL custody balance as crypto to a self-custodial payout_address via POST `/saldo/sacar-cripto`
- Read the BRL balance, holds, and statement per customer_ref, and transfer between subaccounts with POST `/saldo/transferir`
- Confirm that a PIX happened by its E2E id with the open GET `/v1/verificar/{e2e}`, no key needed
- Get a lun_test_ sandbox key in one call with POST `/keys/sandbox` and simulate outcomes with sandbox_scenario values such as delayed, held, or refunded

## Use cases

### Payments agent through Jentic

A billing agent collects BRL from a Brazilian customer. It searches Jentic for 'generate a PIX charge', receives POST `/cashin/charge` with its amount_cents, payer_tax_number, and destino fields, and creates a charge that credits custody. Because a paid PIX does not mean credit is complete, it then checks GET `/cashin/{cashin_id}/status` and the balance statement before marking the invoice settled.

Example prompt: Call POST `/cashin/charge` with amount_cents 15000, payer_tax_number of the payer, destino saldo, and a stable external_id, then poll GET `/cashin/{cashin_id}/status` until settlement is reported

### Crypto to PIX cash-out

Pay a Brazilian supplier in BRL from stablecoins. POST /cash-outs quotes an asset and network listed by GET /catalog against a pix_key or a full br_code, POST `/cash-outs/{cashout_id}/accept` returns the deposit address, and GET `/cash-outs/{cashout_id}` tracks the order until the PIX is delivered.

Example prompt: Call GET /catalog, then POST /cash-outs with asset USDT, a supported network, brl_amount '500.00', and the supplier's pix_key, accept it with POST `/cash-outs/{cashout_id}/accept`, and report the deposit address

### Marketplace subaccount payouts

A platform holds funds for its own clients as subaccounts identified by customer_ref. GET `/saldo/clientes` pages through subaccount balances, POST `/saldo/transferir` moves funds between a subaccount and the house without PIX, and POST /payouts sends a PIX from a subaccount's available balance to the client's key.

Example prompt: Call GET /saldo with customer_ref 'seller-42', and if the balance covers it, POST /payouts with amount_cents 20000, the seller's pix_key, pix_key_type cpf, customer_ref 'seller-42', and a stable external_id

### Sandbox integration testing

Exercise every money flow without moving money. POST `/keys/sandbox` returns a lun_test_ key from an email address, charges create non-payable QR codes that POST `/sandbox/cashin/{cashin_id}/pay` confirms, sandbox_scenario forces outcomes such as held, expired, or settlement_failed, and POST `/sandbox/reset` clears the fictitious state.

Example prompt: Call POST `/keys/sandbox` with the tester's email, create a charge with POST `/cashin/charge` using sandbox_scenario held, then confirm it with POST `/sandbox/cashin/{cashin_id}/pay` and inspect GET `/sandbox/events`

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/cashin/charge` | Generate a PIX charge for BRL custody or crypto delivery |
| GET | `/cashin/{cashin_id}/status` | State of a PIX charge |
| POST | `/payouts` | Send a PIX from the BRL balance |
| POST | `/cash-outs` | Quote a crypto-to-PIX cash-out |
| POST | `/cash-outs/{cashout_id}/accept` | Accept a cash-out and get the deposit address |
| GET | `/saldo` | BRL balance, holds, and next releases |
| GET | `/v1/verificar/{e2e}` | Verify a PIX happened, no key needed |
| POST | `/keys/sandbox` | Get a sandbox API key |

## Key resources

- **Cash-in charges** — PIX charges that credit BRL custody or deliver crypto, with previews, limits, and status
- **Payouts** — PIX payments debited from available BRL balance
- **Cash-outs** — External crypto-to-PIX orders: quote, accept, track, and refund address
- **Balance** — BRL custody per house and customer_ref subaccount, statements, transfers, and crypto withdrawals
- **USDT wallet** — Stablecoin deposits, statements, and Pix payments funded by USDT
- **Keys, webhooks, and sandbox** — API keys and limits, webhook delivery history and retries, and simulated flows

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 57 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 48 / 100
  - Developer Experience & Jentic Compatibility: 65 / 100
  - AI-Readiness & Agent Experience: 44 / 100
  - Agent Usability: 92 / 100
  - Security: 50 / 100
  - AI Discoverability: 68 / 100
- **View full report:** https://jentic.com/apis/luniumpay.com/luniumpay/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Lunium by hand means juggling lun_test_ and lun_ keys in the X-API-Key header, following the three-step cash-out flow, keeping external_id stable across retries, and treating paid, settled, and available as separate states. Through Jentic you install once, import Lunium from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Rules filter by method and path, so you can bound the agent to the operations a task needs, such as creating charges and reading status. Cash-out ids sit in the path (`/cash-outs/{cashout_id}`), so tracking can be pinned to one order. Money-moving operations like payouts, crypto withdrawals, and subaccount transfers are not included unless you add them.
- **Credential handling:** Your Lunium API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'generate a PIX charge' or 'cash out USDT to PIX', and Jentic returns the matching Lunium operation with its input schema, including enums like destino and pix_key_type, so the agent calls the right endpoint without reading the Portuguese-language docs.

## Related APIs

- **Stripe API** — Global card and wallet payments, including Pix in Brazil
- **Coinbase Advanced Trade** — Crypto trading accounts, orders, and balances on Coinbase
- **Chaingateway.io** — Managed Ethereum wallets, token balances, and send-funds operations

## FAQ

### What authentication does the Lunium API use?

Per its OpenAPI spec, the Lunium API uses an apiKey in the X-API-Key header. Keys starting lun_test_ are sandbox keys that move nothing, and lun_ keys are production; a sandbox key comes from POST `/keys/sandbox.` Some routes, such as GET `/v1/verificar/{e2e}`, GET /ping, and the public Mesh directory reads, need no key. Through Jentic, the key is stored encrypted by your own Jentic One instance and injected at execution time.

### Does a paid PIX charge mean the funds are credited?

No. The spec separates payment completion, settlement, and available balance. A charge from POST `/cashin/charge` can be paid while settlement is still pending or the funds are on hold, so follow settlement_status on GET `/cashin/{cashin_id}/status` and the statement at GET `/saldo/extrato` before treating money as available.

### What are the limits for the Lunium API?

The OpenAPI spec states that a payout through POST /payouts is capped at R$ 6.000,00 per PIX, subject to lower account limits, and that limits, fees, and holds are dynamic. Read current per-key limits and daily usage from GET `/keys/me` and payer limits from GET `/cashin/limits`, and see https://docs.luniumpay.com/manual for details.

### How do I send a PIX payout with Lunium through Jentic?

Install Jentic One, add the Lunium API from the Jentic directory, and store your X-API-Key. Your agent searches for 'send a PIX payout', receives POST /payouts with its amount_cents, pix_key, and pix_key_type schema, and sends it with a stable external_id so a retry after a timeout does not pay twice. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I verify a PIX payment someone says they made?

Yes. GET `/v1/verificar/{e2e}` confirms a PIX by its E2E identifier without an account or key, and does not return the PIX key, full name, or tax document. If it finds nothing, the response says the PIX may have been made at another institution, so absence is not proof it never happened.

### Is there a Lunium MCP server?

Yes - Lunium's spec lists an MCP endpoint at api.luniumpay.com/mcp. You can also connect the Lunium API directly through Jentic: your agent gets the full 66-endpoint surface from the spec without loading another server's tool definitions into its context, your key is injected at call time by your self-hosted instance instead of living in an MCP config, and your rules decide which operations the agent may call.

### Can I limit what my agent is allowed to do with the Lunium API?

Yes. For a collections agent, allow only POST `/cashin/charge`, GET `/cashin/{cashin_id}/status`, and GET /saldo, so it can bill customers and watch settlement but cannot send payouts, withdraw crypto, or move funds between subaccounts. The agent's calls are logged for review.