Sollection Docs

Overview

Sollection has three layers:

1. 1. Intent layer. AI assistants, LLMs, agent frameworks, automation tools, and apps prepare invoice intents. An invoice intent is a draft. It is not payable.
2. 2. Approval layer. The recipient wallet or a verified merchant/account flow authorizes invoice creation.
3. 3. Payment layer. A final invoice has a pay page for humans and an x402 endpoint for agents.

User / AI assistant
  -> createInvoiceIntent
  -> preview + walletSignUrl
  -> recipient wallet signs on Sollection
  -> final invoice is created
  -> payer uses payUrl or agent uses x402Url

Verified merchant/account
  -> creates final invoice with verified recipient wallet
  -> payer uses payUrl or agent uses x402Url

The safety boundary is simple: no guest payable invoice. AI assistants, LLMs, agents, and workflow tools may create invoice intents, but they must not create final payable invoices directly and must not invent payment links.

Quickstart

Create Sollection invoices from any AI assistant

AI assistants can prepare invoice intents from natural language or structured API calls. The intent is a draft, not a payable invoice. It has no payUrl or x402Url. Recipient wallet approval is required before Sollection creates a final invoice. Wallet signing approves invoice creation only and does not transfer funds.

User:
Create a Sollection invoice for PT Maju Jaya for 250 USDC,
due 2026-07-20, recipient wallet 9xQ...

AI assistant:
Calls createInvoiceIntent.

Sollection:
Returns preview + walletSignUrl.

User:
Opens walletSignUrl and signs with the recipient wallet.

Sollection:
Creates final invoice.

AI assistant:
Calls getInvoiceIntent. If finalInvoice exists, shows payUrl, x402Url, statusUrl.

• Never share seed phrases or private keys.
• AI assistants do not control your wallet.
• Wallet signing only approves invoice creation.
• Payment requires a separate payer wallet transaction.

Invoice intents

An InvoiceIntent is a draft/pre-invoice object for AI-generated invoices, preview-before-commit workflows, and wallet approval. It prevents assistants and agents from creating a payable invoice without authorization.

Required fields for AI actions are recipientWallet, tokenSymbol, and lineItems. Use USDC or USDT on Solana mainnet-beta; normal users do not need token mint addresses. Existing clients may still send token. Do not use SOL, devnet/testnet mints, or arbitrary SPL mints for invoice intents.

{
  "recipientWallet": "9xQ...",
  "tokenSymbol": "USDC",
  "customerName": "PT Maju Jaya",
  "dueDate": "2026-07-20",
  "lineItems": [
    { "description": "Landing page website", "amount": "200", "quantity": 1 },
    { "description": "Maintenance", "amount": "50", "quantity": 1 }
  ]
}

{
  "recipientWallet": "9xQ...",
  "tokenSymbol": "USDT",
  "lineItems": [
    { "description": "Support retainer", "amount": "500", "quantity": 1 }
  ]
}

Implemented statuses

• SIGNATURE_REQUIRED: wallet approval is required and the intent is not payable.
• CONFIRMED: wallet approval is complete and a final invoice exists or is expected in finalInvoice.
• EXPIRED: the 24-hour intent window elapsed before approval.

Unsigned intents never expose payUrl or x402Url. Those links only appear in the final invoice response after confirmation.

Wallet approval

Wallet approval happens on Sollection's hosted signing page, not inside ChatGPT, Claude, Cursor, an MCP client, or any other AI tool.

1. User opens walletSignUrl.
2. Sollection shows the invoice preview.
3. User connects a Solana wallet such as Phantom or Solflare.
4. The connected wallet must match recipientWallet.
5. User signs the displayed message.
6. Sollection verifies the signature and creates the final invoice.

The implemented signing message includes the Sollection approval purpose, domain, intentId, recipientWallet, amount, token symbol, token mint, mainnet-betacluster, payload hash, nonce, expiration timestamp, and the sentence "Signing does not transfer funds."

Signing approves invoice creation. It does not transfer funds.

Final invoices

A final invoice is the payable object. It is created only after wallet approval for the AI-assistant flow, or through a verified merchant account/API key flow. Final invoices have payUrl, x402Url, and statusUrl.

With the platform action key, this endpoint returns public-safe invoice status for a final invoice. With a merchant API key, it returns the merchant-owned invoice shape from the developer API.

{
  "invoiceId": "inv_abc123",
  "status": "OPEN",
  "payUrl": "https://sollection.xyz/pay/pay_abc123",
  "x402Url": "https://sollection.xyz/api/x402/pay/pay_abc123",
  "statusUrl": "https://sollection.xyz/invoice/inv_abc123/status",
  "amount": "250",
  "tokenSymbol": "USDC",
  "tokenName": "USD Coin",
  "tokenMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "tokenDecimals": 6,
  "cluster": "mainnet-beta"
}

Invoice lifecycle statuses in the database are DRAFT, OPEN, PAID, and CANCELLED.

x402 payments

x402 is for paying final invoices. It is not used to create invoice intents. An agent should never attempt to pay an unsigned invoice intent, because an unsigned intent has no x402Url.

Final invoice exists
  -> agent calls x402Url
  -> Sollection returns 402 with a server-built unsigned transaction
  -> payer wallet signs the payment transaction
  -> agent submits X-PAYMENT
  -> Sollection submits and confirms on-chain settlement
  -> invoice becomes PAID

Recipient approval and x402 payment are different signatures. Recipient approval creates the invoice and does not transfer funds. Payer x402 signing authorizes the payment transaction and transfers funds if submitted successfully.

The current x402 adapter speaks version 1, scheme exact, uses X-PAYMENT, and returns settlement metadata in X-PAYMENT-RESPONSE.

REST API

Sollection exposes separate API categories. Do not use merchant endpoints as generic AI actions unless your product explicitly supplies a merchant API key and verified recipient IDs.

AI-safe action endpoints

• createInvoiceIntent: POST /api/v1/invoice-intents
• getInvoiceIntent: GET /api/v1/invoice-intents/:intentId
• getInvoiceStatus: GET /api/v1/invoices/:invoiceId

Internal browser wallet endpoints

• GET /api/v1/invoice-intents/:intentId/confirm-wallet: returns the signing challenge.
• POST /api/v1/invoice-intents/:intentId/confirm-wallet: used by Sollection's signing page to submit public key and signature.

Merchant/account endpoints

• GET /api/v1/me, /tokens, /recipients, /customers
• POST /api/v1/invoices/preview, POST /api/v1/invoices, GET /api/v1/invoices
• POST /api/v1/payment-links is legacy/account-only and immediately payable.

Payment endpoints

• GET /pay/:payAccessToken: human payment page.
• POST /api/pay/:payAccessToken: Solana Pay transaction request.
• GET /api/x402/pay/:payAccessToken: x402 discover and settle.

AI and Agent Integrations

Sollection can be integrated through OpenAPI/REST, hosted wallet signing, x402, and the hosted MCP endpoint at https://sollection.xyz/mcp.

• AI tools can create invoice intents.
• AI tools cannot create final invoices without wallet approval.
• Wallet signing happens on Sollection's hosted page unless the client is a trusted wallet-capable app.
• Agents can pay final invoices through x402.

Use Sollection with MCP-compatible assistants

The Sollection MCP server runs inside this Next.js app at https://sollection.xyz/mcp. The production URL is https://sollection.xyz/mcp. The hosted public MCP endpoint does not require a bearer token. Connect MCP-compatible clients directly to the endpoint.

MCP tools

• create_invoice_intent: create a non-payable invoice intent.
• get_invoice_intent: check wallet approval and final invoice status.
• get_invoice_status: read public-safe final invoice links and status.

The MCP server does not expose wallet signature confirmation, dashboard, private account, payment-link, or merchant tools. Wallet signing happens on Sollection's hosted signing page.create_invoice_intent returns preview and walletSignUrl only; it never returns payUrl or x402Url before wallet approval. Invoice intents use USDC or USDT on Solana mainnet-beta only.

MCP endpoint:
https://sollection.xyz/mcp

Authentication:
No Authorization header required for the hosted public MCP endpoint.

Exposed tools:
- create_invoice_intent
- get_invoice_intent
- get_invoice_status

Use Sollection from backend agents

Backend agents can call the REST API directly from LangChain, LlamaIndex, custom Node.js/Python agents, or n8n HTTP workflows. No Sollection SDK is required for the implemented flow.

1. Collect invoice data from the user or workflow.
2. Call createInvoiceIntent.
3. Show or send walletSignUrl to the recipient wallet owner.
4. Poll getInvoiceIntent.
5. Once confirmed, show or use finalInvoice links.
6. If paying as an agent, call x402Url only after final invoice exists.

POST /api/v1/invoice-intents
Authorization: Bearer <SOLLECTION_GPT_ACTION_API_KEY>
Content-Type: application/json

{
  "recipientWallet": "9xQ...",
  "tokenSymbol": "USDC",
  "amount": "250",
  "description": "Website services",
  "dueDate": "2026-07-20"
}

OpenAPI schemas

Sollection currently exposes two OpenAPI schemas.

• GET /.well-known/openapi.json: action-safe schema with createInvoiceIntent, getInvoiceIntent, and getInvoiceStatus.
• GET /openapi.json: alias for the action-safe schema.
• GET /api/v1/openapi.json: full merchant/developer API schema. It includes account and legacy payment-link endpoints and is not the recommended AI action schema.

AI assistant rules

Sollection publishes /llms.txt so AI crawlers and assistants can discover the correct flow.

AI Usage Contract

AI assistants may:

• Create invoice intents.
• Show previews.
• Direct users to walletSignUrl.
• Check invoice status.
• Show final pay links after confirmation.

AI assistants must not:

• Claim an invoice is payable before finalInvoice exists.
• Ask for private keys or seed phrases.
• Invent payUrl, x402Url, or statusUrl.
• Submit wallet signatures unless running inside Sollection's own browser signing page.
• Treat x402Url as available before wallet approval.

Security model

Sollection is non-custodial. It stores invoice data, builds payment transactions, verifies signatures, submits signed payment transactions, and confirms settlement. It does not ask for, collect, or store seed phrases or private keys.

• Recipient wallet approval signs a message and does not transfer funds.
• Payer wallet payment signs a transaction and may transfer funds.
• Merchant API keys are account credentials and must stay server-side.
• Action keys are platform-level keys for approved assistant/agent flows only.
• Payment links are immediately payable and should be treated as trusted merchant/account integrations, not public LLM tools.

Errors

Assistant-safe errors use a structured envelope with an optionalassistantHint.

{
  "error": {
    "code": "MISSING_REQUIRED_FIELD",
    "message": "recipientWallet is required.",
    "assistantHint": "Ask the user for the recipient wallet before creating the invoice intent."
  }
}

Implemented assistant-facing codes include MISSING_REQUIRED_FIELD, INVALID_WALLET, UNSUPPORTED_TOKEN, EMPTY_LINE_ITEMS, POLICY_LIMIT_EXCEEDED, INTENT_EXPIRED, SIGNATURE_REQUIRED, INVOICE_NOT_READY, and RATE_LIMITED. Some merchant API endpoints still use the older error.message/error.code shape.

Webhooks

Webhooks are implemented for merchant accounts from the Developers page. Events are invoice.sent and invoice.paid. Deliveries are signed with X-Sollection-Signature and retried by the cron worker.

Webhooks are not part of the action-safe AI schema.

Payment links

Payment links remain implemented at POST /api/v1/payment-links, but they are legacy/account-only. They create an immediately payable invoice from a merchant API key, destination wallet, amount, and token. The destination wallet is trusted inline and is not pre-verified.

Because payment links return payUrl and x402Url immediately, they are not safe as general AI-assistant actions and are intentionally excluded from /.well-known/openapi.json. Prefer invoice intents for AI-created invoices.