# SmoothSign Agent API

> Programmatic HTTP API for AI agents (Claude, ChatGPT, Grok, Gemini, Cursor, custom LLM tools) to send documents for legally binding e-signatures. Self-service registration, no human onboarding required, 25% off our standard per-signature price.

Base URL for all endpoints: `https://ueurrqgdjcpdzflvgbaz.supabase.co/functions/v1/`

Human-readable docs (JS-rendered): https://smoothsign.cc/agents/api
Machine-readable index: https://smoothsign.cc/llms.txt

> **Using Claude or ChatGPT?** You do not need an API key: connect the remote MCP server `https://smoothsign.cc/mcp` and sign in with your SmoothSign account. See the MCP section below or https://smoothsign.cc/ai

---

## Pricing

- **All amounts are in USD cents.** `pricePerSignatureCents: 75` means **$0.75 USD** per signature (NOT 75 NOK øre).
- Currency for all Stripe charges and top-ups is `usd`.
- 25% off our standard per-signature price (standard $1.00 USD → agent price $0.75 USD).
- Live price returned by `GET /agent-balance` as `pricePerSignatureCents`.
- Each signer × each file = one signature charge.

---

## Three billing modes (`billingMode`)

### 1. `prepaid` (default)
Top up via Stripe Checkout. Each signature is debited from the balance. Best when the agent operates without a human nearby and you want a hard spend cap. Returns `402` when balance is insufficient — call `POST /agent-create-topup` and surface the `checkoutUrl` to a human.

### 2. `auto_charge`
A human saves a card once via `POST /agent-setup-card`. Every `POST /agent-send-document` creates a Stripe PaymentIntent off-session for the exact cost. No top-ups, no balance — pay-as-you-go. Returns `402` if the saved card is declined.

### 3. `per_call_token`
The caller supplies a Stripe `paymentMethodId` or `sharedPaymentToken` (Stripe SPT) on every request. Designed for agents that hold their own Stripe Issuing card or Link Shared Payment Token per transaction. See https://stripe.com/blog/giving-agents-the-ability-to-pay

Switch modes with `POST /agent-billing-config`.

---

## Quick start

1. **Register** → receive API key (shown once).
2. **Top up** (prepaid) OR **save card** (auto_charge) OR **bring token per call** (per_call_token).
3. **Send documents** — each signer is charged once per file.
4. **Check balance & mode** any time.

The API key is a Bearer token: `Authorization: Bearer ssk_live_...`

---

## Endpoints

### POST /agent-register
Register a new agent and receive an API key.

```
curl -X POST https://ueurrqgdjcpdzflvgbaz.supabase.co/functions/v1/agent-register \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Sales Bot", "contactEmail": "ops@acme.com"}'
```

Returns: `{ agentId, apiKey, prefix, ... }`. **Save apiKey immediately — shown only once.**

### POST /agent-create-topup
Generate a Stripe Checkout URL to top up prepaid balance.

```
curl -X POST https://ueurrqgdjcpdzflvgbaz.supabase.co/functions/v1/agent-create-topup \
  -H "Authorization: Bearer ssk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"amountCents": 5000}'
```

Returns: `{ checkoutUrl, sessionId }`. Balance credited automatically when payment succeeds.

### POST /agent-setup-card
Save a card for `auto_charge` mode (one-time, requires a human).

```
curl -X POST https://ueurrqgdjcpdzflvgbaz.supabase.co/functions/v1/agent-setup-card \
  -H "Authorization: Bearer ssk_live_..." \
  -H "Content-Type: application/json" -d '{}'
```

Returns: `{ checkoutUrl }`.

### POST /agent-billing-config
Switch billing mode.

```
curl -X POST https://ueurrqgdjcpdzflvgbaz.supabase.co/functions/v1/agent-billing-config \
  -H "Authorization: Bearer ssk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"billingMode": "auto_charge"}'
```

Modes: `prepaid` | `auto_charge` (requires saved card) | `per_call_token` (requires token on each request).

### POST /agent-send-document
Send a PDF for signing.

```
curl -X POST https://ueurrqgdjcpdzflvgbaz.supabase.co/functions/v1/agent-send-document \
  -H "Authorization: Bearer ssk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "signers": ["alice@example.com", "bob@example.com"],
    "message": "Please sign the NDA",
    "files": [{ "name": "nda.pdf", "base64": "JVBERi0xLjQK..." }]
  }'
```

Constraints:
- PDFs base64-encoded (no `data:` prefix).
- Max 15 MB per file.
- Max 10 files per call.
- Up to 50 signers per document.

For `per_call_token` mode, also send `paymentMethodId` or `sharedPaymentToken`.

Returns `{ sent, balanceCents, results }` on success, or `402` if balance/payment fails.

### GET /agent-balance
Check balance, billing mode, saved-card status, and live per-signature price.

```
curl https://ueurrqgdjcpdzflvgbaz.supabase.co/functions/v1/agent-balance \
  -H "Authorization: Bearer ssk_live_..."
```

Returns: `{ balanceCents, signaturesRemaining, pricePerSignatureCents, billingMode, hasCardOnFile, recentLedger }`.

---

## Error codes

- `401` — invalid or missing API key
- `402` — insufficient balance, missing/declined payment method, or missing per-call token
- `403` — agent has been deactivated
- `409` — cannot enable `auto_charge` without a saved card
- `429` — registration rate limit
- `207` — partial success when sending multiple files

---

## Use SmoothSign from Claude, ChatGPT and other AI assistants (MCP)

Remote MCP server: `https://smoothsign.cc/mcp` (Streamable HTTP, protocol 2025-06-18).
Sign-in: OAuth 2.1 with PKCE and dynamic client registration (`https://smoothsign.cc/.well-known/oauth-authorization-server`). The end user signs in with their SmoothSign account (email + SMS code) and approves access. The signed-in user is the sender and pays per signature (free signatures and subscription first).

Tools:
- `send_document` — PDF (base64) + explicitly chosen signers (email, optional name/phone) + optional message. Always confirm signers with the user first. Returns the `documentId` of the document it sent — use it directly with `get_document_status`.
- `list_documents` — latest documents with status.
- `get_document_status` — per-signer status and signing time.
- `get_signed_pdf` — confirms that the signed PDF has been emailed to the sender and every signer, and to whom. No file or link is returned: SmoothSign keeps no copy.

Setup:
- Claude: Settings → Connectors → Add custom connector → paste the URL → Connect.
- ChatGPT: Settings → Apps & Connectors → Advanced → developer mode → Create → paste the URL → OAuth.
- Other MCP clients (Cursor, VS Code, Windsurf): `{"mcpServers":{"smoothsign":{"url":"https://smoothsign.cc/mcp"}}}`
- ChatGPT Custom GPT (Actions): OpenAPI spec at https://smoothsign.cc/openapi-gpt.yaml

Guide: https://smoothsign.cc/ai · Privacy: https://smoothsign.cc/privacy · Terms: https://smoothsign.cc/terms-and-conditions

---

## Notes for LLM tool builders

- Store the API key in a secret manager.
- On `402` in `prepaid` mode → call `agent-create-topup`, surface `checkoutUrl` to a human.
- On `402` in `auto_charge` mode → card declined, surface to human and re-run `agent-setup-card`.
- The signing flow itself uses dual OTP (email + SMS) for legal binding under eIDAS SES.
- When everyone has signed, the signed PDF is emailed to the sender and all signers, and is then deleted by the signing service. SmoothSign keeps no copy, so agents cannot download it — the user finds it in their inbox.

## Contact

- Website: https://smoothsign.cc
- Human docs: https://smoothsign.cc/agents/api
- Email: sign@smoothsign.cc