# Integrating FRENT POS from a coding agent

FRENT lets a coding agent add non-custodial USDC checkout to a merchant repository. The agent writes ordinary server-side integration code. Wallet login, contract deployment and every customer payment remain explicit human wallet actions in FRENT's hosted UI.

## What the coding agent should implement

1. Inspect the repository's framework, order model, routes, secret-management convention and test style.
2. Add a server-side client for `https://frent.tech/api/merchant/v1`.
3. Create one idempotent FRENT payment for an order and redirect the customer to the returned `checkout_url`.
4. Add a webhook route that reads the exact raw body, verifies `X-Frent-Timestamp` and `X-Frent-Signature`, deduplicates `X-Frent-Event-Id`, and fulfils only `payment.paid`.
5. Add environment placeholders and deployment documentation. Never write real secrets into code, logs, fixtures or prompts.
6. Add tests for idempotency, invalid signatures, stale timestamps, duplicate events and non-paid final states.

## Environment variables for the merchant repository

```dotenv
FRENT_API_URL=https://frent.tech/api/merchant/v1
FRENT_POS_API_KEY=
FRENT_WEBHOOK_SECRET=
FRENT_RETURN_URL=https://merchant.example/payments/frent/return
FRENT_NETWORK=base-mainnet
```

`FRENT_NETWORK` is optional and can be `base-mainnet` or `polygon-mainnet`. Keep the API key and webhook secret server-side. The return URL and webhook URL must use the origin registered by the merchant in FRENT.

## Human steps on FRENT

1. Visit `https://frent.tech/connect` and connect the wallet that should receive settlement.
2. Sign the gas-free login message.
3. In Your contracts, choose Base and/or Polygon and confirm each contract deployment in the wallet. Deployment consumes the network's native gas asset.
4. In Workspace > Webhooks, enter the merchant application's HTTPS origin and create an Integration API key. Copy it directly into the deployment environment as `FRENT_POS_API_KEY`.
5. Configure the HTTPS webhook destination, enable delivery and copy the one-time secret directly into the deployment environment as `FRENT_WEBHOOK_SECRET`.
6. Send the built-in test webhook and verify it before accepting live orders.

## Create a hosted checkout

Send `POST /payments` with bearer authentication and a unique `Idempotency-Key` header:

```json
{
  "amount_minor": 2500,
  "currency": "USD",
  "reference": "ORDER-1042",
  "description": "Order 1042",
  "source": "merchant_api",
  "network": "base-mainnet",
  "return_url": "https://merchant.example/payments/frent/return"
}
```

Redirect the customer to `payment.checkout_url`. Do not treat the return URL as settlement proof.

## Verify webhooks

Compute `v1=` plus the lowercase hexadecimal HMAC-SHA256 of `timestamp + "." + raw_request_body` using `FRENT_WEBHOOK_SECRET`. Reject timestamps more than five minutes old and compare signatures with a timing-safe function. Store the event ID before applying the order transition so retries are harmless.

## Pricing and settlement

FRENT charges 0.5% per successful payment, rounded upward in six-decimal USDC units, with a $0.001 minimum and $0.10 maximum. Failed and expired payment requests carry no FRENT fee. The merchant-owned terminal splits the fee and merchant proceeds atomically when the customer pays.

## Explicitly unsupported

- no autonomous agent wallet;
- no private-key handling;
- no x402 endpoint, facilitator or relayer;
- no agent OAuth onboarding;
- no MCP payment runtime;
- no contract deployment without the merchant's wallet confirmation.