# What do the Provely SDKs do?

> The Provely SDKs are thin translators into one model: operation, contract, action result, verification, receipt. The types come from the schemas.

Canonical: https://provely.sh/docs/sdks  
Last reviewed: 2026-09-05  

**The SDKs wrap the REST API. Each SDK is a thin translator into the same canonical model: operation, contract, action result, verification, and receipt. No SDK contains verification logic. The runtime owns verification.**

| SDK | Package | Status | Types |
| --- | --- | --- | --- |
| TypeScript | `@provely/sdk` | first release | generated from the JSON Schemas |
| Python | `provely` | first release | pydantic models generated from the JSON Schemas |
| More languages | on request | after the REST API and the schemas support them | generated |

## Which calls does every SDK expose?

| Call | REST endpoint | Returns |
| --- | --- | --- |
| `begin(contract, input)` | `POST /v1/operations` | The operation id, the idempotency key, the correlation keys. |
| `op.actionResult(result)` | `POST /v1/operations/{id}/action-result` | The stored acknowledgement reference. |
| `op.verify()` | `POST /v1/operations/{id}/verify` | The verdict, the reason, the evidence levels used. |
| `op.status()` | `GET /v1/operations/{id}` | The operation state and the last verdict. |
| `op.receipt()` | `GET /v1/operations/{id}/receipt` | The signed receipt document. |
| `verifyReceipt(receipt, keys)` | offline | The validation result with a reason code. |

## Which rules do all SDKs share?

- Generate the types from the contract and receipt schemas. Do not write them by hand.
- Pass the same cross-language conformance fixtures: canonical JSON, contract hashes, receipt validation, verdict rules.
- Read the API key from configuration. Never accept it as a tool argument.
- Return the verdict as the runtime gives it. Do not soften it.

*Validate a receipt offline in TypeScript*

```typescript
import { verifyReceipt } from '@provely/sdk';

const result = await verifyReceipt(receipt, {
  trustedKeys: { 'provely-prod-2026-09': '<public key hex>' },
});
// result.valid, result.reasonCode: signature_valid | receipt_key_not_trusted | ...
```

### Can I use the SDK with a framework adapter?

Yes. Adapters for the OpenAI Agents SDK, LangGraph, and MCP wrap a tool or a node so the action runs inside an operation. They register through the `Adapter` extension point and contain no verification logic.

## Read next

- [Open the quick start](https://provely.sh/docs/quick-start)
- [Read the API reference](https://provely.sh/docs/api)
- [Read what a receipt proves](https://provely.sh/receipts)