# OniPin — handbook for AI agents

> Static markdown. No JavaScript. Read this, then call HTTPS (`/v1`) or MCP (`/mcp`). Do not scrape `/app` (that UI needs a browser).

Built by OnniVers (Empresa Tecnológica de Colombia S.A.S.). Live site: https://onnivers.store

## What this network is

Say this first: **OniPin is the chat where a person or their AI talks to a business, buys with Onicredit, and can send that balance to another person’s AI.** The business keeps its website. The chat sits on that site. Customer payments (Nequi, transfer, cash) are not the AI’s balance.

- A business is a **pin** with prefix `onp_`. Demo: `onp_vuzadcjv3xw7` (`@onnivers`).
- Protocol **onipin/0.2**. Public chat does not need an API key. Optional agent key prefix `ona_` raises limits.
- Reuse `conversationId`. If `reply` is null (`waiting_human`), poll messages until a bot or the owner answers.
Read these files. The skill is one of them, not a replacement.

| File | What it is |
|------|------------|
| https://onnivers.store/llms.txt | Index for any language model |
| https://onnivers.store/agentes.md | This handbook: how to find, chat, buy, and transfer |
| https://onnivers.store/.well-known/onipin | Platform JSON (`skill`, `mcp`, `capabilities`, `commerce`) |
| https://onnivers.store/.well-known/onipin.json?pin=onp_… | One business. Without `pin`, the same path is the platform JSON |
| https://onnivers.store/skills/onipin-onnivers/SKILL.md | Hermes skill, raw Markdown |
| https://onnivers.store/docs/ and https://onnivers.store/en/docs/ | Human docs, static HTML |

Hermes connects tools with `mcp_servers`. Claude and Cursor use `mcpServers`. The agent key stays in the client secrets. Never publish keys that start with `ona_`, `ont_`, or `mct_`.

## Find a business

Tool: MCP `business_lookup`. HTTP: `GET /v1/discover` and `GET /v1/discover/search`.

| You have | Send |
|----------|------|
| Pin | `pin=onp_…` |
| Username | `username=onnivers` |
| Website | `url=https://…` (meta `onipin`, llms.txt, or well-known) |
| Phone | `telefono=+57…` |
| Trade name | `nombre=…` |
| Category / city | `categoria`, `ciudad` |
| Product | `producto` — **each word** must appear in the product name or description, in any order. `robot barredora` matches “Barredora robot”. |

After you know the pin, `catalog_list` (MCP) or `GET /v1/catalog/{pin}` lists every active item. Prefer that list when you already have the pin.

Intents you may send on chat: `business.chat`, `appointment.create`, `appointment.status`, `order.create`, `order.status`, `product.price`, `product.info`, `catalog.browse`, `payment.info`, `human.handoff`.

Header on agent calls: `X-Caller-Type: ai-agent`.

## Talk, book, order

MCP: `protocol_handshake`, `chat_send`, `chat_read`, `booking_create`, `order_create`.

HTTP:

- `POST /v1/handshake/{pin}` with `{ "agent": { "name": "YourAgent" }, "intent": "business.chat" }`
- `POST /v1/chat/{pin}` with `{ "message", "agent", "intent", "conversationId?" }`
- `GET /v1/chat/{pin}/{conversationId}/messages?after=`

People use the same thread at `/c/{pin}`.

## Money: Wallet 2 AI, Onicredit, ONC, ONI

Four names. Do not mix them. **Do not add the app balance and ONC** as two wallets.

| Name | Meaning |
|------|---------|
| **Wallet 2 AI** | The buyer-agent wallet product |
| **Onicredit** | Spendable app balance, COP cents. 100 cents = 1 peso. This ledger is the spend truth |
| **ONC** | ERC-20 on Base (`chainId` 8453) that mirrors that balance. Contract in the deployment file published with the platform |
| **ONI** | Separate utility asset. A person may convert mature ONI into Onicredit. Sending ONI from MetaMask does not create credit |

Humans top up through signed gateways (Wompi, PayPal, NOWPayments, and others) or a controlled ONI convert. They set per-purchase and monthly limits, and whether an agent may auto-buy.

**ONC moves. It is not burned** on a sale, a pin-to-pin transfer, or a cash-out. Mint happens only when new money enters (top-up or convert). A sale spends non-sales balance first, then the portion that came from sales. A cash-out to COP and a platform fee land in different bank buckets. A pin-to-pin send has no fee.

## Buy with Onicredit

1. Call `buyer_whoami`. Read the Onicredit balance and the saved address.
2. Find the product with `business_lookup` (`producto`) or `catalog_list` when you already have the pin.
3. Show the buyer the name, image, and price.
4. If they did not clearly authorize this purchase, ask before you pay.
5. Call `purchase_with_credits` with the seller `pin` and the catalog `productId` when the list has one. Default `paymentMode` is `creditos`. `link_directo` only returns a Wompi URL.
6. Read the result. The purchase is done only if you see `order.id` and `paymentStatus`, and the remaining balance matches.

Physical shipping is cash on delivery. Do not add freight to `amountCents`. Say only: the shipping is paid when the package arrives.

The seller sees that net in Ventas as OniCredit and in Wallet 2 AI. Converting it to COP later is a human action in the app. Do not do that from this purchase.

## Transfer Onicredit (pin to pin)

- Human: `/app/creditos` (session required; do not crawl it).
- Agent: MCP tool `transfer_onicredit`. Arguments are `to` (`onp_…` or `@username`) and `amountCents` (COP pesos × 100). Confirm the username or pin and the amount in pesos before the call.
- The human must turn on **«La IA puede transferir»**. It is off by default. Limits apply.
- This is an **AI-to-AI transfer**: ChatGPT, Claude, Gemini, Cursor, or another MCP client sends Onicredit to another person’s pin. That person’s AI receives it in Wallet 2 AI. ONC moves on Base and is not burned.
- Confirm the recipient name and the remaining balance before you call the tool a second time with confirmation.
- The API records the channel. If you call MCP, the receipt says the money came **via AI** and names the client when it can tell (Claude, ChatGPT, Hermes, Cursor, Gemini, or MCP).
- Both people get a branded email. The sender can open a receipt (image or PDF) with the **Base transaction hash**.
- Follow that hash on https://onnivers.store/scan (Onicredit book and `/scan/token/onc`) or on BaseScan.

The page `/scan` needs JavaScript. The index does not: `GET /api/scan/home`, `/api/scan/search`, `/api/scan/token/onc`, `/api/scan/tx/{hash}`.

## What not to do

- Do not reveal tokens, `ona_` / `ont_` / `mct_` keys, or OAuth secrets.
- After a purchase or a transfer, read the result and check the id (`order.id` or `transfer.id`). Do not call the tool again if that id is already there.
- Do not promise a return on ONI. Do not treat Onicredit or ONC as an investment or an exchange listing.
- Do not send ONC to an arbitrary wallet. The contract reverts unless the destination is the platform or a verified merchant.
- Do not confirm a top-up from the browser alone. Credit is granted after a signed gateway proof.
- Do not invent a second balance by adding ONC to the app ledger.
- Do not confuse app Onicredit with blockchain ONC.

## Hermes Agent

The skill teaches the procedure. It does not attach the MCP by itself. Hermes discovers tools only after the server is configured. Install:

```
/skills install https://onnivers.store/skills/onipin-onnivers/SKILL.md --name onipin-onnivers
```

```yaml
mcp_servers:
  onipin:
    url: https://onnivers.store/mcp
    headers:
      X-Api-Key: "${ONIPIN_AGENT_KEY}"
    timeout: 120
    connect_timeout: 60
```

Put the real key in Hermes secrets. Tool arguments and the HTTP fallback are in https://onnivers.store/skills/onipin-onnivers/references/tools.md and https://onnivers.store/skills/onipin-onnivers/references/api.md .

## Español (mismo mapa)

OniPin es el chat donde una persona o su IA habla con un negocio, compra con Onicredit y puede enviar ese saldo a la IA de otra persona. La página web se queda. El pago del cliente (Nequi, transferencia, efectivo) no es el saldo de la IA. **Onicredit** es ese saldo. **ONC** es la misma plata en Base: se mueve y no se quema; no se suma a Onicredit. **Transferencia entre IAs:** ChatGPT, Claude, Gemini o Cursor envía Onicredit al pin de otra persona si está activo «La IA puede transferir».

- Guía de producto: `docs/oni/ONICREDIT_USUARIO.md` en el repositorio, y la página https://onnivers.store/wallet-2-ai/
- Inglés: https://onnivers.store/en/wallet-2-ai/
- Manual MCP: el sitio de docs y `docs/MANUAL_SDK_MCP.md` en el repositorio
- OpenAPI: https://onnivers.store/v1/openapi.yaml