curl -X POST https://api.xenarch.dev/v1/links \
-H "Authorization: Bearer xm_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1c2a9e-4b7d-4e2a-9c31-8d5f0a7b2e14" \
-d '{
"params": {
"to": {"state": "lit", "value": "0xYourWalletAddress"},
"amount": {"state": "lit", "value": "25.00"},
"currency": {"state": "lit", "value": "USDC"},
"network": {"state": "lit", "value": "base"},
"kind": {"state": "lit", "value": "checkout"},
"product_name": {"state": "lit", "value": "Consulting hour"}
},
"nonce": "'"$NONCE"'",
"created_at": '"$CREATED_AT"',
"signed_params": "'"$SIGNATURE"'"
}'
{
"link_id": "JJjIwDyV4N1CG9g8AHMxfdJ9",
"link": "https://pay.xenarch.com/l/JJjIwDyV4N1CG9g8AHMxfdJ9",
"qr_png_url": null,
"embed_html": null,
"webhook_secret": "whsec_...",
"signed_params": "0x...",
"created_at": "2026-11-17T12:00:00Z"
}
Links
Create Link
Create a USDC pay link from a params tree signed by your wallet with EIP-712. Returns the hosted checkout URL and the link’s webhook secret.
POST
/
v1
/
links
curl -X POST https://api.xenarch.dev/v1/links \
-H "Authorization: Bearer xm_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1c2a9e-4b7d-4e2a-9c31-8d5f0a7b2e14" \
-d '{
"params": {
"to": {"state": "lit", "value": "0xYourWalletAddress"},
"amount": {"state": "lit", "value": "25.00"},
"currency": {"state": "lit", "value": "USDC"},
"network": {"state": "lit", "value": "base"},
"kind": {"state": "lit", "value": "checkout"},
"product_name": {"state": "lit", "value": "Consulting hour"}
},
"nonce": "'"$NONCE"'",
"created_at": '"$CREATED_AT"',
"signed_params": "'"$SIGNATURE"'"
}'
{
"link_id": "JJjIwDyV4N1CG9g8AHMxfdJ9",
"link": "https://pay.xenarch.com/l/JJjIwDyV4N1CG9g8AHMxfdJ9",
"qr_png_url": null,
"embed_html": null,
"webhook_secret": "whsec_...",
"signed_params": "0x...",
"created_at": "2026-11-17T12:00:00Z"
}
curl -X POST https://api.xenarch.dev/v1/links \
-H "Authorization: Bearer xm_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1c2a9e-4b7d-4e2a-9c31-8d5f0a7b2e14" \
-d '{
"params": {
"to": {"state": "lit", "value": "0xYourWalletAddress"},
"amount": {"state": "lit", "value": "25.00"},
"currency": {"state": "lit", "value": "USDC"},
"network": {"state": "lit", "value": "base"},
"kind": {"state": "lit", "value": "checkout"},
"product_name": {"state": "lit", "value": "Consulting hour"}
},
"nonce": "'"$NONCE"'",
"created_at": '"$CREATED_AT"',
"signed_params": "'"$SIGNATURE"'"
}'
{
"link_id": "JJjIwDyV4N1CG9g8AHMxfdJ9",
"link": "https://pay.xenarch.com/l/JJjIwDyV4N1CG9g8AHMxfdJ9",
"qr_png_url": null,
"embed_html": null,
"webhook_secret": "whsec_...",
"signed_params": "0x...",
"created_at": "2026-11-17T12:00:00Z"
}
Authentication
Send one of:Authorization: Bearer xm_live_..., a merchant API key. The signer must be the account’s owner wallet.- The
xen_sessioncookie from Sign-In with Ethereum. The signer must be the wallet you signed in with.
403).
Body
| Field | Type | Description |
|---|---|---|
params | object | The link terms as tagged values {"state": "lit", "value": ...}. to, amount, currency, network and kind are required. See Create pay links and GET /v1/links/schema. |
nonce | string | 32 random bytes as 0x plus 64 hex characters |
created_at | integer | Unix seconds when you signed. Must be within 300 seconds of the server clock. |
signed_params | string | 65-byte EIP-712 signature as 0x plus 130 hex characters |
download_url | string | Optional. A file link revealed on the receipt after payment. Not part of params and not signed. https on an allowed host only. |
params as strings, such as "25.00". The signature covers the exact JSON, and a number serializes differently from a string.
What to sign
The signature is EIP-712 typed data:{
"domain": {
"name": "Xenarch Pay Links",
"version": "1",
"chainId": 8453,
"verifyingContract": "0x0000000000000000000000000000000000000000"
},
"primaryType": "PayLink",
"types": {
"PayLink": [
{"name": "to", "type": "address"},
{"name": "amount", "type": "string"},
{"name": "currency", "type": "string"},
{"name": "network", "type": "string"},
{"name": "kind", "type": "string"},
{"name": "templateHash", "type": "bytes32"},
{"name": "createdAt", "type": "uint256"},
{"name": "nonce", "type": "bytes32"}
]
},
"message": {
"to": "<params.to, checksummed>",
"amount": "<params.amount>",
"currency": "<params.currency>",
"network": "<params.network>",
"kind": "<params.kind>",
"templateHash": "<keccak256 of the canonical JSON of params>",
"createdAt": "<created_at>",
"nonce": "<nonce>"
}
}
templateHash is the keccak256 hash of params serialized as canonical JSON: keys sorted, separators , and : with no spaces, UTF-8 with non-ASCII characters left as they are. The Python SDK (xenarch.merchant) and the TypeScript SDK (@xenarch/sdk) implement the same recipe.
Checks the API runs
- Validates
params. The same checks run atPOST /v1/links/validate, which returns{ok, missing, errors}without creating anything. - Checks
created_atagainst the server clock. - Rebuilds the typed data and recovers the signer. It must match the authenticated wallet.
- Checks that
tois the account’s owner wallet or a full co-owner wallet past its 24-hour cooldown. - Checks
webhook_url(https, no private addresses) anddownload_url(allowed hosts).
Idempotency
Send anIdempotency-Key header to make retries safe. A repeat with the same key and the same body returns the link created the first time. The same key with a different body returns 409.
Response
webhook_secret signs this link’s webhooks and authenticates usage reports. The API returns it here and again only when you rotate it. qr_png_url and embed_html are always null today.
Errors
| Status | Meaning |
|---|---|
400 | Invalid params, a clock skew over 300 seconds, a signature that does not match, an ineligible to wallet, or a rejected URL |
401 | Missing or invalid credentials |
403 | The signed-in wallet has the viewer role |
409 | Idempotency-Key reused with a different body |
Body
application/json