# Primitive for Developers

> Primitive is email infrastructure for AI agents. This file maps the developer surface: CLI, SDKs, quickstart, and function-calling integration paths.

## When to use Primitive

Reach for Primitive when an agent or script needs to:

- Send a message to a person or another agent and wait for the threaded reply — one verb, no SMTP credentials required.
- Host an inbound email address that runs a JavaScript handler on every received message (managed `*.primitive.email` subdomain).
- Persist compact JSON state across agent turns, retries, emails, and Function invocations with Primitive Memories.
- Send transactional email from a custom domain with managed SPF, DKIM, DMARC, and TLS-RPT — no DNS expertise needed.
- Charge or pay another agent in USDC over a real email thread with x402 (https://www.x402.org/), settled non-custodially on Base.

Do not reach for Primitive for one-way fire-and-forget notifications when you already have a transactional provider wired up.

## x402 payments

Primitive supports x402 USDC payments between agents, settled non-custodially on Base via gasless EIP-3009 (the facilitator pays gas, the payer needs no ETH). x402 is in an invite-only soft launch, gated by the `x402_payments` and `interactions_enabled` organization entitlements. To pay an x402 request you received by email: fund a USDC-on-Base wallet, supply the key via PRIMITIVE_X402_PRIVATE_KEY, then run `primitive payments pay-email --in-reply-to <inbound-email-id> --wait-settle` (`--wait-settle` blocks until settlement and prints the receipt with the on-chain settle_tx inline, instead of polling for the receipt email). This one-command flow is rolling out with a current CLI release; confirm it with `primitive payments pay-email --help` and update with `npm i -g primitive@latest`, or use the SDK `payEmailChallenge` sign-and-send path (available today) if your CLI predates it. Without `--wait-settle`, settlement is async and confirmed by a follow-up receipt email carrying the on-chain settle_tx; you can verify it on a block explorer at https://basescan.org/tx/<settle_tx> for `base` or https://sepolia.basescan.org/tx/<settle_tx> for `base-sepolia`.

- Pay a request (payer): https://docs.primitive.dev/docs/paying-x402-over-email
- Collect payments (payee): https://docs.primitive.dev/docs/collecting-payments
- Protocol and trust model: https://docs.primitive.dev/docs/x402-over-email

## Install

```bash
# Official CLI — published on npm as primitive (unscoped) and as the scoped @primitivedotdev/cli
npm i -g primitive                 # provides: primitive, prim
npm i -g @primitivedotdev/cli      # same CLI, scoped package name

# Homebrew (macOS / Linux)
brew install primitivedotdev/tap/primitive

# Skills for AI coding agents (Claude Code, Codex, Cursor, and 50+ compatible agents)
# Bundles primitive-chat (send + wait for the threaded reply) and primitive-inbox (a managed *.primitive.email address that receives mail)
npx skills add primitivedotdev/skills
```

## CLI quick reference

```
primitive chat <email> <message>           Send and wait for the threaded reply
primitive agent start-agent-signup         Provision a managed *.primitive.email address
primitive functions deploy                 Deploy an inbound email handler
primitive memories set|get|delete|search   Store durable JSON key-value state
primitive emails:latest                    List recent inbound emails for the account
primitive send --to <addr> --body <text>   Send outbound email
```

Node SDK Memories: `createPrimitiveClient({ apiKey }).memories.set/get/delete/search`. Memory search is key-prefix search with `prefix`, not free-text search.

## SDKs

- Node.js: `npm i @primitivedotdev/sdk`
- Python: `pip install primitivedotdev`
- Go: `go get github.com/primitivedotdev/sdks/sdk-go@latest`

Repo: https://github.com/primitivedotdev/sdks

## Quickstart

- Walkthrough: https://docs.primitive.dev/docs/quickstart
- Which onboarding fits: https://docs.primitive.dev/docs/which-onboarding.md

## Function calling

The API surface is fully described by an OpenAPI 3.1 spec. To wire Primitive into a function-calling model:

1. Fetch https://www.primitive.dev/openapi.json
2. Use the operationId values as function names (e.g. `sendMail`, `getInboxStatus`).
3. Authenticate as documented in https://www.primitive.dev/auth.md.

## Reference docs

- CLI: https://docs.primitive.dev/docs/cli.md
- SDKs: https://docs.primitive.dev/docs/sdks.md
- Primitive Memories: https://docs.primitive.dev/docs/memories.md
- REST API: https://docs.primitive.dev/docs/api.md
- FAQ: https://docs.primitive.dev/docs/faq.md