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

# Retempo API Base URL, Field Formats, and Conventions

> Reference for the Retempo API base URL, ID formats, USDC amounts, wallet addresses, referenceHash encoding, and ISO 8601 date-time fields.

This page covers the key configuration values and field conventions you need to integrate with the Retempo API. Before making your first request, confirm your base URL, content type header, and field formats match the specifications below. Misformatted fields — especially wallet addresses, reference hashes, and timestamps — are the most common source of validation errors.

## API Endpoints

All Retempo API requests go to the base URL below. The dashboard lets you manage your services, payment plans, and subscriptions through a visual interface.

| Resource     | URL                       |
| ------------ | ------------------------- |
| API Base URL | `https://api.retempo.xyz` |
| API Root     | `/api/v1`                 |
| Dashboard    | `https://retempo.xyz`     |

All endpoints follow the pattern `https://api.retempo.xyz/api/v1/{resource}`. For example, to list your services you would call `GET https://api.retempo.xyz/api/v1/services`.

## Field Formats

Retempo enforces specific formats for IDs, amounts, addresses, hashes, and timestamps. Use this table as a quick reference when constructing request bodies.

| Field            | Format                             | Example                          |
| ---------------- | ---------------------------------- | -------------------------------- |
| IDs              | cuid string                        | `clz1abc2def3ghi4jkl5`           |
| Amounts          | Decimal string or number (USDC)    | `"49.00"` or `49.00`             |
| `referenceHash`  | `0x` + 64 hex characters (bytes32) | `"0x000...abc"` (66 chars total) |
| Wallet addresses | `0x` + 40 hex characters (EVM)     | `"0xAbCd...1234"`                |
| Date/time fields | ISO 8601 UTC string                | `"2025-01-15T10:00:00.000Z"`     |

### IDs

All Retempo resource IDs are [cuid](https://github.com/paralleldrive/cuid2) strings. They are generated server-side and returned in API responses. You do not generate IDs yourself — store the IDs returned by create endpoints and reference them in subsequent requests.

```json theme={null}
{
  "id": "clz1abc2def3ghi4jkl5"
}
```

### Amounts

All monetary amounts are denominated in USDC. You can pass amounts as a decimal string or as a number. Retempo does not accept amounts of `0` — all amounts must be positive and non-zero.

```json theme={null}
{
  "amount": "49.00"
}
```

### Reference Hash (`referenceHash`)

The `referenceHash` field uniquely identifies a settlement on-chain. It must be a bytes32 hex string: the prefix `0x` followed by exactly 64 hexadecimal characters (32 bytes total, 66 characters including the prefix).

```json theme={null}
{
  "referenceHash": "0xabc1230000000000000000000000000000000000000000000000000000000def"
}
```

<Warning>
  Passing a `referenceHash` that does not conform to the `0x` + 64 hex character format will result in a `400 Bad Request`. Ensure your hash generation logic zero-pads the value to the full 32-byte length.
</Warning>

### Wallet Addresses

The `payerAddress` and `merchantAddress` fields accept standard EVM wallet addresses: the prefix `0x` followed by exactly 40 hexadecimal characters. Both addresses must be non-zero — passing the zero address (`0x0000000000000000000000000000000000000000`) causes Arc to reject the settlement with an `InvalidAddress` error.

```json theme={null}
{
  "payerAddress": "0xAbCdEf1234567890AbCdEf1234567890AbCdEf12",
  "merchantAddress": "0x1234567890AbCdEf1234567890AbCdEf12345678"
}
```

### Date and Time Fields

All date/time fields across the Retempo API accept and return ISO 8601 strings. Always use UTC (the `Z` suffix or `+00:00` offset) to avoid timezone-related mismatches.

The following fields follow this format:

| Field        | Used On                   |
| ------------ | ------------------------- |
| `occurredAt` | Usage events, settlements |
| `dueAt`      | Invoices                  |
| `expiresAt`  | Checkout sessions         |
| `recordedAt` | Settlements               |

<Tip>
  Use ISO 8601 UTC timestamps for all date fields (`occurredAt`, `dueAt`, `expiresAt`, `recordedAt`) to avoid timezone issues. A timestamp like `"2025-01-15T10:00:00.000Z"` is unambiguous regardless of where your server runs.
</Tip>

```json theme={null}
{
  "occurredAt": "2025-01-15T10:00:00.000Z",
  "dueAt": "2025-02-15T10:00:00.000Z",
  "expiresAt": "2025-01-15T11:00:00.000Z"
}
```

## Currency

All amounts in Retempo are denominated in USDC. The `currency` field defaults to `"USDC"` and does not need to be specified explicitly in most requests. Do not pass amounts in other currencies — Retempo does not perform currency conversion.

```json theme={null}
{
  "amount": "100.00",
  "currency": "USDC"
}
```

## Content-Type

Every API request that includes a body must set the `Content-Type` header to `application/json`. Requests without this header, or with a mismatched content type, will be rejected.

```bash theme={null}
curl -X POST https://api.retempo.xyz/api/v1/services \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"name": "My Service"}'
```

<Info>
  The Retempo API always returns responses with `Content-Type: application/json`, including error responses. Parse the `error` field on non-2xx responses to read the error message.
</Info>