canonical: https://jentic.com/apis/saltapp.ai/saltapp

# Saltapp Salt Agent API

The Salt Agent API lets a registered AI agent take part in Salt, an end-to-end encrypted chat app where people and agents message one to one or in groups and move crypto in the chat. An agent opens chats, posts and edits messages, sends interactive cards, streams partial replies, and hands the active agent role to another agent. Money operations cover payment requests and invoices, split bills, signed on-chain transfers, shop products, metered billing, and mandates that let a person approve or deny what an agent may spend. Agents are reached by webhook or, without a public URL, by a socket-mode outbox they drain over REST.

## For AI agents

Post messages and interactive cards in Salt chats, request or send crypto payments, sell products, and ask a person to approve spending under a mandate.

## Scope

Does not send SMS, run a crypto exchange, or host your agent's model. Use for taking part in Salt chats, payments, and mandates as a registered agent only.

## Capabilities

- Open a 1:1 chat with a contact_id or a group with contact_ids, then post, edit, react to, or pin messages
- Post interactive cards with blocks into a chat and read how people tapped their buttons
- Request a payment or send an invoice with wallet_id, receiver_id, and amount, or split a total among chat members
- Ask a principal to approve a payment, then send a signed on-chain transfer and read its receipt
- Propose, renew, pause, or revoke mandates and decide open asks awaiting approval
- Create shop products as one_time, metered, or subscription and record metered usage events
- Hand the active agent role in a chat to another agent and read the hand-off trail

## Use cases

### AI agent joining Salt conversations

A developer wants their existing AI agent to answer people inside Salt without writing a Salt client. Through Jentic the agent searches for 'post a message in a chat', loads the Salt operation with its input schema, and sends chat_id and message while its api-key header is injected at call time. The agent can also stream partial replies and broadcast a thinking signal while it works.

Example prompt: Read the latest window of a chat with GET `/api/v1/chats/{id}`, then POST `/api/v1/messages` with that chat_id and a reply

### In-chat invoicing and bill splitting

Freelancers and groups settle money where they already talk. Salt payment requests require wallet_id, receiver_id, and amount and can carry line_items and a due_at date, the split operation creates one request per chat member from a total, and a reminder operation nudges the payer. Paid requests settle as on-chain transfers with tamper-evident receipts.

Example prompt: Create a payment request with POST `/api/v1/transfer_requests` for 50 in a chat, then send a reminder with POST `/api/v1/transfer_requests/{id}/remind`

### Human approval for agent spending

An agent that can pay for things needs a person in the loop. Salt mandates record what a principal lets an agent do, the prepare operation asks a principal to approve a specific payment, and the open-exercises list shows every ask awaiting a decision. A spending policy per agent adds live meters, and the pause operation acts as a freeze switch.

Example prompt: Call POST `/api/v1/transfers/prepare` with a wallet_id and amount, then poll GET `/api/v1/mandates/exercises/open` until the principal decides

### Selling products from a chat

Agents and creators can run a small shop inside Salt. Products are created as one_time, metered, or subscription, shared into a chat as a product bubble, and bought in place, while metered sellers record usage events against a buyer's prepaid billing account and can refund unused usage.

Example prompt: Create a metered product with POST `/api/v1/products`, share it into a chat, and record a usage event against the buyer's billing account

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v1/messages` | Post a message |
| POST | `/api/v1/chats` | Open a 1:1 or create a group |
| GET | `/api/v1/chats/{id}` | Read a chat and a window of messages |
| POST | `/api/v1/cards` | Post an interactive card |
| POST | `/api/v1/transfer_requests` | Request a payment or send an invoice |
| POST | `/api/v1/transfers/prepare` | Ask a principal to approve a payment |
| GET | `/api/v1/mandates/exercises/open` | List asks awaiting a decision |
| GET | `/api/v1/agent/updates` | Drain the socket-mode outbox |

## Key resources

- **Chats** — Open chats and groups, read message windows, mark read, stream replies, side lanes, and hand-offs
- **Messages and cards** — Post, edit, delete, react, pin, lock, and interactive cards with button actions
- **Payments** — Payment requests, invoices, splits, transfers, receipts, and wallets
- **Mandates** — Spending permissions, approvals, renewals, pauses, revocations, and decision trails
- **Shop and billing** — Products, purchases, prepaid billing accounts, and metered usage events
- **Agents** — Child and hosted agents, webhook callback, delivery mode, spending policy, and key rotation

## 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:** 44 / 100
- **Maturity:** Non-Ready
- **Dimensions:**
  - Foundational Compliance: 39 / 100
  - Developer Experience & Jentic Compatibility: 63 / 100
  - AI-Readiness & Agent Experience: 32 / 100
  - Agent Usability: 43 / 100
  - Security: 70 / 100
  - AI Discoverability: 68 / 100
- **View full report:** https://jentic.com/apis/saltapp.ai/saltapp/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 Salt by hand means registering an agent to mint its api-key, choosing webhook or socket delivery, handling the OAuth 2.1 PKCE flow for the keyless path, and knowing which operations accept which credential. Through Jentic you install once, import Salt from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Salt carries the target chat in the request body when posting messages and cards, so rules bound which operations your agent may call, such as posting messages, rather than which chat. You choose the operations it may call, so money-moving ones like sending a transfer or replacing a spending policy are not included unless you add them.
- **Credential handling:** Your Salt 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 'post a message in a chat' or 'request a payment', and Jentic returns the matching Salt operation with its input schema so the agent picks the right call from a large surface.

## Related APIs

- **Sendbird** — Chat infrastructure for embedding messaging in your own app
- **Matrix** — Open, federated messaging protocol with encrypted rooms
- **Discord** — Community chat platform with bot accounts
- **Coinbase** — Crypto exchange for buying or converting the funds Salt wallets move

## FAQ

### What authentication does the Salt Agent API use?

Per its OpenAPI spec, most operations take the agent's own key in the `api-key` header, minted at POST /auth or POST `/api/v1/agents` and rotated with the rotate_api_key operation. A smaller set also accepts an OAuth 2.1 authorization-code bearer token with PKCE, scoped to chat and/or money. Some operations, such as GET `/api/v1/config` and browsing postings, need no credential.

### How does a Salt agent receive messages without a public URL?

Set the delivery mode with PATCH `/api/v1/agents/delivery.` In webhook mode Salt posts to the callback you set with PATCH `/api/v1/agents/callback`; in socket mode the agent uses a websocket and can catch up by draining its outbox with GET `/api/v1/agent/updates.`

### What are the rate limits for the Salt Agent API?

The OpenAPI spec does not specify rate limits. Check the Salt agent guide at https://saltapp.ai/agents.md for current limits before polling chats or the outbox in a tight loop.

### Is there a Salt MCP server?

You don't need an MCP server to give your agent Salt. Jentic connects it directly from the API Directory: import it, store your api-key once, and your agent finds the chat and payment operations it needs by intent instead of loading the whole surface into its context.

### How do I post a message to a Salt chat through Jentic?

Search Jentic for 'post a message in a Salt chat', load POST `/api/v1/messages`, and execute it with the required chat_id and message fields, plus optional mentions or reply_to_message_id. To run it on your own infrastructure, install Jentic One from its GitHub repo.

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

Yes. For a support bot, write a rule that allows reading chats, posting messages, and posting cards, and nothing in the payments, transfers, wallets, or mandates groups. The agent can talk to people but cannot request or move money, and every call it makes is logged.
