# Sollection

> Sollection is an invoice creation and payment layer for AI assistants,
> agents, and humans. It turns AI-generated invoice drafts into
> wallet-approved, payable Solana invoices.

Sollection is non-custodial. It never asks for private keys or seed phrases.
Wallet signing happens through the user's wallet provider.

## Correct AI flow

Sollection can be used by AI assistants, LLMs, agent frameworks, and automation
tools to prepare invoice intents from natural language or structured API calls.
Examples include ChatGPT, Claude, Gemini, Cursor, MCP-compatible clients,
workflow tools, and custom backend agents.

User -> AI assistant -> createInvoiceIntent -> preview + walletSignUrl ->
recipient wallet signs on Sollection -> final invoice ->
payUrl/x402Url/statusUrl.

Invoice intents are not payable. They do not have payUrl or x402Url. Recipient
wallet approval is required before a final invoice is created. AI assistants
must not invent invoice links and must not claim an invoice is payable before
Sollection returns finalInvoice with payUrl.

## Links

- [Docs](https://sollection.xyz/docs)
- [Create invoices from any AI assistant](https://sollection.xyz/docs/ai-invoices)
- [Invoice intents](https://sollection.xyz/docs/invoice-intents)
- [Wallet approval](https://sollection.xyz/docs/wallet-approval)
- [AI and agent integrations](https://sollection.xyz/docs/integrations)
- [MCP-compatible assistants](https://sollection.xyz/docs/integrations/mcp)
- [Backend agents](https://sollection.xyz/docs/integrations/agents)
- [AI assistant rules](https://sollection.xyz/docs/llms)
- [Action-safe OpenAPI](https://sollection.xyz/.well-known/openapi.json)
- [Developer OpenAPI](https://sollection.xyz/api/v1/openapi.json)
- [Privacy](https://sollection.xyz/privacy)
- [Terms](https://sollection.xyz/terms)

## Action-safe operations

- createInvoiceIntent: POST https://sollection.xyz/api/v1/invoice-intents
- getInvoiceIntent: GET https://sollection.xyz/api/v1/invoice-intents/:intentId
- getInvoiceStatus: GET https://sollection.xyz/api/v1/invoices/:invoiceId
- MCP server: POST https://sollection.xyz/mcp

For createInvoiceIntent, send tokenSymbol as USDC or USDT. Sollection invoice
intents currently support only USDC and USDT on Solana mainnet-beta. Normal
users do not need token mint addresses. Do not ask users for SOL, devnet/testnet
token mints, or arbitrary SPL token mints for invoice intents.

Use Authorization: Bearer <SOLLECTION_GPT_ACTION_API_KEY> for approved
action-safe REST API traffic. This key is separate from merchant API keys and
cannot bypass wallet approval. The hosted public MCP endpoint does not require
an Authorization header.

## x402 payments

x402 is for paying a final invoice. It is not for creating invoice intents.
x402Url exists only after a final invoice exists. A payer agent calls the
x402Url, receives a 402 response with a server-built unsigned Solana
transaction, signs that exact transaction with the payer wallet, and resubmits
it in X-PAYMENT.

Agent x402 requests must include the bearer key for an Agent Profile configured
under /agents. Sollection evaluates that profile before returning payment
requirements or settling a payment; requests without an active profile are
denied with AGENT_REVOKED. Policy limits, token and merchant allowlists,
recipient wallet rules, and human-approval thresholds apply to every decision.

Recipient wallet signing during invoice creation does not transfer funds.
Payer x402 signing is a separate payment transaction and may transfer funds.

## Merchant/account API

Merchant API keys from the Developers page can access account endpoints such as
/api/v1/me, /tokens, /recipients, /customers, /invoices, and webhooks. Merchant
invoice creation uses verified recipient IDs or the logged-in dashboard flow.
Do not treat merchant invoice creation as the generic AI assistant flow.

Payment links still exist at POST /api/v1/payment-links for account-only legacy
trusted integrations. They create immediately payable links from a merchant API
key and destination wallet, so they are excluded from the action-safe schema and
should not be exposed as general LLM invoice creation tools.

## MCP server

The hosted MCP server runs at https://sollection.xyz/mcp and exposes only these tools:
create_invoice_intent, get_invoice_intent, and get_invoice_status. It does not
expose wallet signature confirmation, dashboard/private/account tools, payment
links, or merchant tools. create_invoice_intent creates only a non-payable
invoice intent and returns preview plus walletSignUrl. The hosted public MCP
endpoint does not require a bearer token.

## AI safety rules

- Create invoice intents.
- Show invoice previews.
- Direct users to walletSignUrl.
- Check invoice intent status.
- Show final invoice links after approval.
- Use x402Url to pay final invoices if acting as a payer agent.

AI assistants must not:

- Claim an invoice is payable before finalInvoice exists.
- Ask for seed phrases or private keys.
- Invent payUrl, x402Url, invoiceId, or statusUrl.
- Bypass wallet approval.
- Treat x402Url as available before final invoice creation.
- Submit wallet signatures unless running inside a trusted Sollection wallet signing page.
- Ask normal users for token mint addresses for invoice intents.
- Ask users for SOL, devnet/testnet token mints, or arbitrary SPL token mints for invoice intents.

## Flow reminders

- Always create an invoice intent first for AI-assisted invoice creation.
- Always show the preview before asking the user to sign.
- Send the user to walletSignUrl for recipient wallet approval.
- Only show payUrl/x402Url/statusUrl after finalInvoice exists.