For developers
Build around the invoice.
Create invoices, share payment links, and track USDC payments. Run billing from your terminal with the native CLI, or connect contractor invoicing and customer funding to your application through the REST API.
Native CLI · v0.2.2
Your billing. Your terminal.
One Rust binary for customers, invoices, payment links, and your dashboard. Available for macOS and Linux on ARM64 and x86-64, with no Node.js, Bun, Cargo, or MCP host required.
Sign in through your browser with read-only access by default. Use API keys for unattended jobs and shell-capable agents, with structured JSON, explicit exit statuses, and recovery information for invoice operations.
Download and inspect the installer before running it; it verifies release checksums. Invoice writes require write scopes and an active signing session. macOS binaries are currently unsigned and unnotarized; see the guide for installation details.
curl -fL https://github.com/tinkrtailor/cleared-cli/releases/download/v0.2.2/install.sh -o install.sh
less install.sh
sh install.sh --version 0.2.2
export PATH="$HOME/.local/bin:$PATH"
cleared login
cleared dashboard
cleared --json invoices list --status issued --limit 20Scroll horizontally to read long lines.
REST API
Start with a signed request.
API keys use HMAC authentication, not Bearer authentication. Get your key ID and secret in dashboard settings and keep the secret on your server. This read-only example lists your organization's invoices. The API selects the network from your organization's configuration; use a test organization for development.
- GET /v1/invoices
- List invoices for your organization.
- GET /v1/invoices/:id
- Read an invoice and its payment status.
- POST /v1/invoices/issue
- Issue using an API key with invoice:write scope and an active server signer. Requires an existing customer and a completed business profile.
For issuance, use integer USDC base units (six decimals) and a Unix-seconds due date. A submitted transaction is not proof of payment. Preserve the token in any returned payment link.
API overviewimport { createHash, createHmac, randomUUID } from 'node:crypto';
// Run server-side with Node.js 20+ or Bun.
const { CLEARED_API_KEY, CLEARED_KEY_ID } = process.env;
if (!CLEARED_API_KEY?.startsWith('clr_sk_') ||
!CLEARED_KEY_ID?.startsWith('clr_pk_')) {
throw new Error('Set CLEARED_API_KEY and CLEARED_KEY_ID');
}
const path = '/v1/invoices';
const query = 'limit=5';
const ts = Date.now().toString();
const nonce = randomUUID();
const bodyHash = createHash('sha256').update('').digest('base64');
const message = ['GET', path, query, bodyHash, ts, nonce].join('\n');
const secret = Buffer.from(CLEARED_API_KEY.slice(7), 'base64url');
const signature = createHmac('sha256', secret).update(message).digest('base64');
const response = await fetch('https://api.clearedpay.xyz' + path + '?' + query, {
headers: {
'x-cleared-key': CLEARED_KEY_ID,
'x-cleared-ts': ts,
'x-cleared-nonce': nonce,
Authorization: 'CLEARED-HMAC ' + signature,
},
signal: AbortSignal.timeout(15000),
});
if (!response.ok) throw new Error('API request failed: ' + response.status);
console.log(await response.json());Scroll horizontally to read long lines.
TypeScript SDK
Work with USDC amounts.
The current SDK lives at packages/sdk-ts in the private Cleared repository and exports @cleared/sdk. Access is required; it is not currently available from the public npm registry. This example uses its local fee utilities.
From a repository checkout, run bun install at the root, then bun run build in packages/addresses and packages/sdk-ts. Use the SDK from a workspace that depends on it. Use the REST API or native CLI for invoice operations.
import { calcFee, parseUSDC, formatUSDC } from '@cleared/sdk';
// Standard fee estimate, calculated locally.
console.log(formatUSDC(calcFee(parseUSDC('1000.00')))); // '20.00'
console.log(formatUSDC(calcFee(parseUSDC('5000.00')))); // '50.00'
// USDC amounts use six decimal places.
console.log(parseUSDC('1000.00')); // 1000000000nScroll horizontally to read long lines.
MCP server
Connect an MCP host to your billing.
For MCP-compatible clients, run the private repository's MCP server with Bun after installing workspace dependencies. The package is not currently on the public npm registry. Replace the absolute checkout path and both credential placeholders in this client configuration. The server signs API requests using your key.
Use a Base Sepolia key for this example. Issuing invoices also needs write permission and an active server signer. Tool access follows your API key permissions. For agents that run shell commands, the native CLI is available as a public binary download.
Ask about MCP access{
"mcpServers": {
"cleared": {
"command": "bun",
"args": ["run", "/absolute/path/to/cleared/packages/mcp/src/bin/cleared-mcp.ts"],
"env": {
"CLEARED_API_KEY": "clr_sk_REPLACE_WITH_YOUR_SECRET",
"CLEARED_KEY_ID": "clr_pk_REPLACE_WITH_YOUR_KEY_ID",
"CLEARED_API_URL": "https://api.clearedpay.xyz",
"CLEARED_CHAIN": "base-sepolia"
}
}
}
}Scroll horizontally to read long lines.
Planned integration
Payment events, your ledger.
Webhooks are planned so your application can respond to payment events and credit a customer's platform balance. Production delivery is not available yet. Endpoint registration, signatures, retries, and delivery visibility still require engineering work.
- Cleared confirms a payment and sends a payment event to your backend.
- Your backend verifies the event and matches the invoice to your customer.
- Your application records the payment once and credits its own ledger.
This is a workflow preview, not an executable webhook API. Your team owns customer mapping, duplicate handling, and ledger crediting. Current integrations can read invoice status through the API while webhook delivery is developed.
Discuss your integration