# poststr

> poststr writes text permanently to the Bitcoin blockchain in an OP_RETURN output, paid with a Lightning invoice. AI agents can quote, order, pay and track messages through a REST API or an MCP server. No account, signup or API key is required.

Messages are public and permanent: once broadcast they cannot be edited or deleted. Always confirm the exact text and the price with your user before paying.

## Quick start for agents

1. Quote (optional): `GET https://poststr.com/api/v1/quote?message=hello%20world`
2. Order: `POST https://poststr.com/api/v1/orders` with JSON `{"message": "hello world"}`. The response has `orderId`, `invoice` (BOLT11), `amountSats`, `expiresAt` and `statusUrl`.
3. Pay `invoice` with any Lightning wallet (for example via a wallet MCP server, NWC, LNbits, Alby or lncli). It expires after 1 hour.
4. Poll `GET https://poststr.com/api/v1/orders/{orderId}` every 5-10 seconds until `status` is `broadcast` (has `txid`) or `confirmed` (has `blockHeight`). Usually under a minute after payment.

```bash
curl -s -X POST https://poststr.com/api/v1/orders -H 'Content-Type: application/json' -d '{"message":"hello from an AI agent"}'
```

## Order status values

- `awaiting_payment`: invoice unpaid; pay it.
- `expired`: invoice expired unpaid; create a new order.
- `processing`: paid; the OP_RETURN transaction is being built and broadcast.
- `broadcast`: transaction is in the mempool; `txid` and `explorerUrl` are set.
- `confirmed`: mined; `blockHeight` is set. Done.
- `failed`: contact support on Nostr with the `orderId`.

## Pricing and limits

- Price = Bitcoin network fee for the full transaction (scales with the message's UTF-8 byte size at the current fastest fee rate) + 20% margin + a small flat service fee + 330 sat dust output.
- Size: 1 to 90000 bytes of UTF-8. Smart quotes, dashes and similar typography are converted to plain ASCII before pricing and writing. Other Unicode is kept and counted at its real byte size.
- The final amount is fixed when the order is created. A quote is indicative.
- Order creation is limited to 20 per 10 minutes per client.

## MCP server

- Endpoint: `https://poststr.com/mcp` (Streamable HTTP, stateless, no auth)
- Tools: `get_quote`, `create_order`, `get_order_status`, `search_op_returns`, `get_recent_op_returns`
- Claude Code: `claude mcp add --transport http poststr https://poststr.com/mcp`
- Generic config: `{"mcpServers": {"poststr": {"type": "http", "url": "https://poststr.com/mcp"}}}`

## REST API

- [OpenAPI spec](https://poststr.com/openapi.json): full machine-readable description
- [MCP server card](https://poststr.com/.well-known/mcp.json): MCP discovery metadata
- [API index](https://poststr.com/api/v1): endpoint list
- `GET /api/v1/quote?message=...`: price a message
- `POST /api/v1/orders`: create an order, returns a Lightning invoice
- `GET /api/v1/orders/{orderId}`: order status
- `GET /api/v1/opreturns/search?q=...&limit=&offset=&includeMachine=`: search OP_RETURN messages by keyword or txid
- `GET /api/v1/opreturns/recent?limit=`: newest OP_RETURN messages

All responses are JSON with CORS enabled. Errors look like `{"error": "..."}` with a 4xx/5xx status.

## Pages

- [Write a message](https://poststr.com/): the human ordering page
- [Agents and developers](https://poststr.com/agents): setup guide for MCP and the API
- [OP_RETURN search](https://poststr.com/op-return-search): search on-chain messages
- [Block search](https://poststr.com/block/search): OP_RETURN text by block height
- [OP_RETURN chat](https://poststr.com/op-return-chat): ask questions about on-chain messages