> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crycketpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> Complete reference for the Crycket API

## Base URL

```
https://api.crycketpay.com/v1
```

Test mode is activated by using a `pk_test_` API key — same URL, same code path, routed to testnets.

## Authentication

All requests require an `Authorization: Bearer <api_key>` header.

| Key format          | Environment                          |
| ------------------- | ------------------------------------ |
| `pk_live_<32chars>` | Production — real funds, real chains |
| `pk_test_<32chars>` | Test mode — testnets, no real funds  |

```bash theme={null}
curl https://api.crycketpay.com/v1/intents \
  -H "Authorization: Bearer pk_live_..."
```

## Error format

All errors return a consistent envelope. The HTTP status code is the primary signal; the `code` field is machine-readable.

```json theme={null}
{
  "error": {
    "code": "intent.already_fulfilled",
    "message": "This payment intent has already been fulfilled.",
    "param": null,
    "details": {
      "intent_id": "pi_abc123",
      "current_state": "confirmed"
    }
  }
}
```

| Status | Meaning                                             |
| ------ | --------------------------------------------------- |
| 400    | Malformed request or validation error               |
| 401    | Invalid or missing API key                          |
| 402    | Feature requires a higher plan tier                 |
| 404    | Resource not found                                  |
| 409    | Conflict — wrong state for this operation           |
| 422    | Semantically invalid (e.g. token not on this chain) |
| 503    | RPC upstream unavailable — includes `retry_after`   |

## Idempotency

| Endpoint                      | Key                              | Behavior                                                |
| ----------------------------- | -------------------------------- | ------------------------------------------------------- |
| `POST /v1/intents`            | Caller-supplied `idempotencyKey` | Same key within 24h returns existing intent             |
| `POST /v1/intents/:id/build`  | Intent ID                        | Returns same unsigned tx if state unchanged             |
| `POST /v1/intents/:id/submit` | Tx signature/hash                | Duplicate broadcast is harmless; returns existing state |
| `PATCH /v1/intents/:id`       | `updatedAt` timestamp            | Stale writes return 409                                 |