@conto_finance/sdk 0.1.0

package/README.md

@@ -0,0 +1,107 @@
+# @conto_finance/sdk
+
+TypeScript SDK for Conto. Use it when you control the agent runtime and want typed access to
+payment requests, payment execution, and organization-level provisioning.
+
+## Install
+
+```bash
+npm install @conto_finance/sdk
+```
+
+## Choose the Right Key
+
+| If your application needs to...                                       | Client       | Credential                         | Env var             |
+| --------------------------------------------------------------------- | ------------ | ---------------------------------- | ------------------- |
+| Make payment or read calls as one agent                               | `Conto`      | Agent SDK key (`conto_agent_...`)  | `CONTO_API_KEY`     |
+| Provision agents, wallets, policies, or memberships from your backend | `ContoAdmin` | Organization API key (`conto_...`) | `CONTO_ORG_API_KEY` |
+
+An admin SDK key is still an agent SDK key. It keeps the `conto_agent_...` prefix, so it is not a
+drop-in replacement for `ContoAdmin`.
+
+## Agent SDK Quick Start
+
+```typescript
+import { Conto } from '@conto_finance/sdk';
+
+const conto = new Conto({
+  apiKey: process.env.CONTO_API_KEY!,
+});
+
+const request = await conto.payments.request({
+  amount: 25,
+  recipientAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f...',
+  recipientName: 'OpenAI',
+  purpose: 'API credits',
+  category: 'API_PROVIDER',
+});
+
+if (request.status === 'APPROVED') {
+  const result = await conto.payments.execute(request.requestId);
+  console.log(result.txHash);
+}
+```
+
+For a single-call managed-wallet flow, use:
+
+```typescript
+const result = await conto.payments.pay({
+  amount: 10,
+  recipientAddress: '0x...',
+  purpose: 'Service fee',
+});
+```
+
+## Admin SDK Quick Start
+
+`ContoAdmin` uses an organization API key (`conto_xxx...`), not an agent SDK key.
+
+```typescript
+import { ContoAdmin } from '@conto_finance/sdk';
+
+const admin = new ContoAdmin({
+  orgApiKey: process.env.CONTO_ORG_API_KEY!,
+});
+
+const { members } = await admin.team.listMembers();
+const serviceOwner = members.find((member) => member.user?.email === 'ops@yourcompany.com');
+
+if (!serviceOwner) {
+  throw new Error('No dedicated owner membership found');
+}
+
+const agent = await admin.agents.create({
+  name: 'Trading Bot',
+  agentType: 'CUSTOM',
+  ownerMembershipId: serviceOwner.id,
+});
+
+const wallet = await admin.wallets.create({
+  name: 'Operations Wallet',
+});
+```
+
+## What This Package Covers
+
+- `Conto` for agent-scoped payment flows
+- `ContoAdmin` for organization-scoped provisioning and management
+- Built-in retries for `429` and `5xx` responses
+- Typed request and response shapes for the public SDK surface
+
+## What To Use Instead
+
+- Use the REST API docs if you need endpoints that are not wrapped by this package yet, especially
+  external-wallet `approve -> transfer -> confirm` flows.
+- Use the MCP server if a tool-calling assistant should operate Conto directly.
+
+## Docs
+
+- SDK install: [conto.finance/docs/sdk/installation](https://conto.finance/docs/sdk/installation)
+- Authentication: [conto.finance/docs/sdk/authentication](https://conto.finance/docs/sdk/authentication)
+- Payments: [conto.finance/docs/sdk/payments](https://conto.finance/docs/sdk/payments)
+- Admin SDK: [conto.finance/docs/sdk/admin](https://conto.finance/docs/sdk/admin)
+- API reference: [conto.finance/api-docs](https://conto.finance/api-docs)
+
+## License
+
+MIT