Skip to main content
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.
ResourceURL
API Base URLhttps://api.retempo.xyz
API Root/api/v1
Dashboardhttps://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.
FieldFormatExample
IDscuid stringclz1abc2def3ghi4jkl5
AmountsDecimal string or number (USDC)"49.00" or 49.00
referenceHash0x + 64 hex characters (bytes32)"0x000...abc" (66 chars total)
Wallet addresses0x + 40 hex characters (EVM)"0xAbCd...1234"
Date/time fieldsISO 8601 UTC string"2025-01-15T10:00:00.000Z"

​
IDs

All Retempo resource IDs are cuid 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. 
{
  "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. 
{
  "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). 
{
  "referenceHash": "0xabc1230000000000000000000000000000000000000000000000000000000def"
}
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.

​
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. 
{
  "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:
FieldUsed On
occurredAtUsage events, settlements
dueAtInvoices
expiresAtCheckout sessions
recordedAtSettlements
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.
{
  "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. 
{
  "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. 
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"}'
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.