# Soca

> Non-custodial USDC payments and subscriptions on Solana — a two-sided network:
> a Merchant OS for businesses (payments, subscriptions, invoices, in-person,
> usage billing, Telegram/Discord access) and a simple personal money account
> (customers pay 1% less at checkout). Funds settle wallet-to-wallet in the
> payment transaction itself; customers pay no gas; Soca never custodies funds.

- Base URL: https://soca.finance
- Auth: HTTP header `Authorization: Bearer sk_live_...` (secret key; server-side only)
- Amounts: USDC base units, 6 decimals ($9.00 = 9000000)
- SDK: `npm i @usesoca/sdk` — typed TypeScript client for every endpoint below
- Human docs: https://soca.finance/docs (each page below links its markdown mirror)

## Complete API guide
- [Full integration guide](https://soca.finance/llms-full.txt): every endpoint, request/response, webhook verification, SDK, MCP — self-contained. Hand this to your AI tool.

## Overview
- [What is Soca](https://soca.finance/docs/md/index): Soca is a stablecoin payments platform: businesses accept payments and run their money operations, and customers pay from a simple money account, settling USDC on Solana, wallet to wallet.
- [How Soca works](https://soca.finance/docs/md/how-it-works): The Soca settlement model in plain English: USDC moves wallet to wallet in a single transaction, gas is sponsored, and subscriptions run on capped, revocable on-chain authorizations.
- [Pricing and fees](https://soca.finance/docs/md/pricing): Soca pricing in one table: 1.5% when a business gets paid (and customers pay 1% less with a Soca account, online or in person), free personal transfers, free refunds, and no chargebacks, with no monthly or setup fees.
- [Security and self-custody](https://soca.finance/docs/md/security): What non-custodial means in practice: Soca cannot move, freeze, or lose your money; keys are exportable; subscriptions are bounded by four on-chain safeguards; merchant integrations use signed webhooks and hashed API keys.
- [FAQ](https://soca.finance/docs/md/faq): Straight answers to the most common questions about Soca: fees, refunds, chargebacks, supported wallets, settlement speed, self-custody, subscriptions, and how Soca differs from Stripe.

## For businesses
- [Getting started](https://soca.finance/docs/md/business/getting-started): Open a Soca business account and take your first USDC payment in minutes: no bank account, no code, and no crypto knowledge required.
- [Accepting payments](https://soca.finance/docs/md/business/payments): How Soca checkout works: share a link or QR, customers pay by email or wallet, and every payment is confirmed on-chain before it settles directly to your wallet.
- [In-person payments](https://soca.finance/docs/md/business/in-person): Turn your phone into a payment terminal: enter an amount, show a QR code, and get paid in USDC on the spot with no card reader or added hardware, for the same 1.5% fee as online.
- [Subscriptions and plans](https://soca.finance/docs/md/business/subscriptions): Recurring USDC billing without cards: customers approve once on-chain, renewals charge automatically to your wallet, and failed payments retry on a built-in recovery ladder.
- [Invoices](https://soca.finance/docs/md/business/invoices): Send one-time USDC payment requests with a hosted invoice page: the customer pays with one tap, the invoice reconciles itself, and both sides get a receipt.
- [Refunds](https://soca.finance/docs/md/business/refunds): Refund any confirmed payment in full or in part. Each refund is a new transfer you sign back to the customer, never a reversal, and chargebacks do not exist on Soca.
- [Wallets and treasury](https://soca.finance/docs/md/business/wallets-and-treasury): One account, many named wallets: route payments by purpose, keep a default receiver, export any key, and manage the money you hold with treasury buckets, reserves, and auto-sweep rules.
- [Usage-based billing](https://soca.finance/docs/md/business/usage-billing): Meter what customers consume, price it with exact-integer math, manage prepaid credits on an immutable ledger, and gate features with entitlements: all visible in the dashboard.
- [Sell access to your Discord server](https://soca.finance/docs/md/business/discord-access): Charge for a Discord role and get paid in crypto (USDC on Solana). Subscribers get the role automatically when they pay and lose it when they cancel — add Soca’s bot with one click: no bot to build, no token to copy, no code.
- [Sell access to your Telegram channel](https://soca.finance/docs/md/business/telegram-access): Charge for access to a private Telegram channel or group and get paid in crypto (USDC on Solana). Paying subscribers are let in automatically and removed when they cancel — add Soca’s shared bot as an admin: no bot to build, no token to copy, no code.

## For your money
- [Your account](https://soca.finance/docs/md/personal/your-account): Create your Soca account in under a minute: no seed phrases, no monthly fees, and a @username your friends can find you by.
- [Adding and withdrawing money](https://soca.finance/docs/md/personal/add-and-withdraw): Move money into Soca with a debit card, Apple Pay, or your bank, and back out again, with every fee shown before you confirm.
- [Paying with Soca](https://soca.finance/docs/md/personal/paying-with-soca): Choose Soca at checkout and pay 1% less than the listed price, with real receipts, subscriptions you fully control, and no card numbers to leak.
- [Sending money](https://soca.finance/docs/md/personal/sending-money): Send money to any @username instantly and free, and request money with a link or QR. Password-protected sends are coming soon.
- [Private payments](https://soca.finance/docs/md/personal/privacy): How Soca private payments work: private sends, private receive links, and private payouts route a USDC transfer through a privacy partner so it is not linkable to your wallet on the public Solana chain. Opt-in and off by default, USDC on Solana only. It breaks the on-chain link between sender and recipient; it is not a mixer and it is not anonymity.
- [Security and recovery](https://soca.finance/docs/md/personal/security-and-recovery): Passkeys protect your payments, your keys stay exportable, and losing your phone never means losing your money.

## Developers
- [Quickstart](https://soca.finance/docs/md/developers/quickstart): Accept your first USDC payment in about five minutes: create an API key, create an invoice, send the customer to the hosted checkout, and fulfill on the invoice.paid webhook.
- [Authentication](https://soca.finance/docs/md/developers/authentication): How Soca API keys work: Bearer secret keys with sk_test_ and sk_live_ prefixes, strict mode scoping, key hygiene, 401 behavior, and per-endpoint rate limits.
- [The Soca SDK](https://soca.finance/docs/md/developers/sdk): The official @usesoca/sdk TypeScript client: zero dependencies, fully typed, one method per real endpoint: invoices, plans, payments, subscriptions, events, metering, credits, entitlements, and webhook verification.
- [Embed a Pay button](https://soca.finance/docs/md/developers/embed): Drop a "Pay with Soca" button onto any website with one script tag. It opens Soca’s hosted checkout in a popup and can tell your page when the payment completes.
- [API reference](https://soca.finance/docs/md/developers/api-reference): Every Soca REST endpoint: invoices, plans, payments, subscriptions, events, usage meters and metering, prepaid credits, and entitlements, with parameters, requests, and responses.
- [Webhooks and events](https://soca.finance/docs/md/developers/webhooks): Signed webhook deliveries: registering an endpoint, verifying the x-wc-signature header, the retry schedule, and every event type Soca emits with what to do when it fires.
- [How Telegram and Discord access works](https://soca.finance/docs/md/developers/telegram-and-discord): The mechanics behind Soca’s paid Telegram and Discord access: the one shared platform bot, the wallet-link handshake, idempotent grant and revoke driven by subscription events, and the self-hosting switch — all with no code and no per-merchant bot token.
- [MCP for AI agents](https://soca.finance/docs/md/developers/mcp): Connect AI assistants and IDEs straight to your Soca account over the Model Context Protocol: the /api/mcp remote server, OAuth 2.1 or API-key auth, and the tools it exposes for invoices, plans, usage, credits, and entitlements.
- [Errors and testing](https://soca.finance/docs/md/developers/errors-and-testing): The Soca error envelope and every error code, SocaError in the SDK, test mode isolation, idempotency keys, cursor pagination, and how to handle rate limits.

## API quick reference
- Create: POST https://soca.finance/v1/invoices, POST https://soca.finance/v1/plans (both return a hosted `checkout_url`)
- Read (cursor-paginated): GET https://soca.finance/v1/payments | subscriptions | invoices | events | meters
- Usage: POST https://soca.finance/v1/meter-events (single or batch, idempotent)
- Credits: POST https://soca.finance/v1/credit_grants, POST https://soca.finance/v1/credit_debits, GET https://soca.finance/v1/customers/{id}/credit_balance
- Entitlements: POST https://soca.finance/v1/entitlement_grants, GET https://soca.finance/v1/customers/{id}/entitlements/{feature_key}
- Fulfill: verify `x-wc-signature`, act on `invoice.paid` / `subscription.active`
- MCP server for AI agents: https://soca.finance/api/mcp (OAuth 2.1 or static `sk_` key)
- No-code: Telegram / Discord paid access via Dashboard -> Settings -> Integrations