AI Context File

Copy the markdown below into a CLAUDE.md, .cursorrules, or similar AI context file in your project. This gives your AI coding assistant the knowledge it needs to work with the Tesser API without re-reading the full documentation each session.

Usage

1. Copy the content below
2. Save it as CLAUDE.md (for Claude Code), .cursorrules (for Cursor), or any context file your tool supports
3. Place it in your project root

Context File

Code
 
# Tesser Payments API

## Overview

Tesser is a payments platform for stablecoin and fiat transfers. The API handles payment creation, wallet management, counterparty onboarding, compliance screening, and treasury operations.

## API Access

- **Base URL**: `https://sandbox.tesserx.co/v1`
- **Auth**: OAuth 2.0 client credentials → Bearer token
- **Docs**: https://docs.tesser.xyz
- **LLM docs**: https://docs.tesser.xyz/llms-full.txt
- **OpenAPI Schema**: https://docs.tesser.xyz/api/v1/schema.json

### Authentication

```bash
curl --request POST \
  --url https://dev-awqy75wdabpsnsvu.us.auth0.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{
    "client_id": "'$TESSER_API_KEY'",
    "client_secret": "'$TESSER_API_SECRET'",
    "audience": "https://sandbox.tesserx.co",
    "grant_type": "client_credentials"
  }'
```

### Environment Variables

```
TESSER_API_KEY=your-api-key
TESSER_API_SECRET=your-api-secret
```

## MCP Server

All API operations are available as MCP tools at `https://sandbox.tesserx.co/v1/mcp`.

## Key Endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/payments` | Create a payment (payout, deposit) |
| GET | `/v1/payments/{id}` | Get payment by ID |
| PATCH | `/v1/payments/{id}` | Update payment with account info |
| POST | `/v1/payments/{id}/risk-review` | Submit risk review decision |
| GET | `/v1/accounts` | List accounts (wallets, ledgers, bank accounts) |
| POST | `/v1/accounts` | Create an account |
| GET | `/v1/entities/counterparties` | List counterparties |
| POST | `/v1/entities/counterparties` | Create a counterparty |
| GET | `/v1/currencies` | List supported currencies |
| GET | `/v1/networks` | List supported blockchain networks |

## API Conventions

- All request/response fields use **snake_case**
- Amounts are strings (e.g. `"1000.50"`)
- IDs are UUIDs
- Timestamps are ISO 8601 (e.g. `"2025-12-01T09:00:00.000Z"`)
- Webhook events follow the pattern `resource.action` (e.g. `payment.balance_updated`, `step.confirmed`)

## Domain Glossary

Language that is easy to confuse. This is a glossary, not a spec.

### Funds Movement

- **Payment** — A funds-movement resource with a `direction` (`inbound`, `outbound`, `rebalance`) and a `payment_type` (`deposit`, `withdrawal`, `transfer`). Carries `desired` / `estimated` / `actual` overlays and one or more steps.
- **Inbound Payment** — A payment with `direction = "inbound"` recording funds sent on-chain from an external wallet to one of your **Managed Wallets**. Detected by monitoring the chain, not initiated through the API. Distinct from a **Deposit**.
- **Deposit** — A customer-initiated inbound funds movement (`POST /v1/treasury/deposits`) that routes fiat or stablecoin through a provider to a destination account. Not the same as an **Inbound Payment**.
- **Step** — One leg of a payment's execution (`transfer`, `swap`). Has a lifecycle status and `estimated` / `actual` overlays.

### Inbound Lifecycle

- **Confirmed** — Step state when the on-chain transaction is included in a block. Fires `payment.created`. Funds are visible but **not yet final** — the block can still be reorganized.
- **Completed** — Step state when the block has finalized. Fires `step.completed` + `payment.updated`. Funds are safe to spend.

Avoid using "confirmed" and "completed" interchangeably — for inbound they are two distinct moments.

### Outbound Lifecycle (wallet source)

- **Signature Requested** — The unsigned transaction is prepared and Tesser is waiting for the customer to sign. Fires `step.signature_requested`.
- **Signed** — The signature was accepted and the source balance is reserved. Fires `payment.balance_updated` (`reserved`) followed by `step.signed`.
- **Submitted** — Event-only marker that broadcast is beginning.
- **Confirmed (outbound)** — The broadcast was accepted by the network (mempool). Carries the transaction hash. **Not final.** Unlike inbound, this means broadcast acceptance, not block inclusion.
- **Completed (outbound)** — The transfer reached finality. `step.completed` fires, followed by the terminal `payment.updated`. That ordering is contractual: detect terminal state from the pair.

### Balances

- **Total Balance** — All funds credited to an account asset, including inbound funds that have arrived but not yet finalized. For an inbound payment, credited at **Confirmed**.
- **Available Balance** — Funds free to spend (total minus reserved). For an inbound payment, credited once the step is **Completed** (block finality). Inbound risk screening does not gate it. Invariant: available ≤ total.

### Risk & Screening

- **Risk Screening** — Evaluation of a payment's external counterparty wallet against the workspace's risk policy. For an inbound payment the screened party is the **sender** (the Unmanaged Account); for an outbound payment it is the recipient. The outcome is a `risk_status` and drives the `payment.risk_updated` webhook. **Advisory for inbound** (does not gate Available Balance — funds are already custodied), **gating for outbound** (fail-closed).
- **Risk Decision** — A manual approval/rejection submitted when screening returns `awaiting_decision`. Recorded as `manually_approved` / `manually_rejected` with reviewer and timestamp.

### Accounts & Counterparties

- **Managed Wallet** (a.k.a. Managed Account, `is_managed: true`) — A wallet Tesser custodies and can sign for. Inbound funds are credited to one.
- **Unmanaged Account** (`is_managed: false`) — An external wallet Tesser does not control. Auto-created to represent the **sender** of an inbound payment, keyed by its on-chain address.
- **Placeholder Counterparty** — The single shared counterparty that all inbound senders are attached to, because the owner of a sending wallet cannot be identified. One per tenant.

### Relationships

- An inbound payment has exactly one step (type `transfer`), born **Confirmed**, transitioning to **Completed** at finality.
- An inbound payment's sender is an **Unmanaged Account** attached to the **Placeholder Counterparty**; its recipient is a **Managed Wallet**.
- **Confirmed** credits **Total Balance**; **Completed** (finality) credits **Available Balance**. Inbound risk screening is advisory and does not gate this credit.