Skip to main content
POST
Most integrations create links with the CLI or an SDK, which build the params tree, compute the signature and call this endpoint for you. Use this page if you sign on your own.

Authentication

Send one of:
  • Authorization: Bearer xm_live_..., a merchant API key. The signer must be the account’s owner wallet.
  • The xen_session cookie from Sign-In with Ethereum. The signer must be the wallet you signed in with.
A wallet with the viewer role cannot create links (403).

Body

Send amounts and other numbers inside 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:
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

  1. Validates params. The same checks run at POST /v1/links/validate, which returns {ok, missing, errors} without creating anything.
  2. Checks created_at against the server clock.
  3. Rebuilds the typed data and recovers the signer. It must match the authenticated wallet.
  4. Checks that to is the account’s owner wallet or a full co-owner wallet past its 24-hour cooldown.
  5. Checks webhook_url (https, no private addresses) and download_url (allowed hosts).

Idempotency

Send an Idempotency-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

Headers

Idempotency-Key
string | null
authorization
string | null

Body

application/json
params
Params · object
required

The link parameters: kind, amount and the fields of that kind.

nonce
string
required

32-byte random nonce as 0x-prefixed hex.

Pattern: ^0x[0-9a-fA-F]{64}$
created_at
integer
required

Unix time in seconds when the client built the link. The server clamps it to within 5 minutes of its own clock.

signed_params
string
required

65-byte EIP-712 signature over the parameters by the seller's wallet, as 0x-prefixed hex.

Pattern: ^0x[0-9a-fA-F]{130}$
download_url
string | null

Optional https download link for digital delivery, on an allowed host. Not part of the signed parameters. Shown only on the confirmed receipt.

Maximum string length: 2048

Response

Successful Response

webhook_secret
string
required
signed_params
string
required
created_at
string<date-time>
required
qr_png_url
string | null
embed_html
string | null