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

# 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.

```bash theme={null}
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"'"
  }'
```

```json 201 theme={null}
{
  "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"
}
```

Most integrations create links with the [CLI or an SDK](https://docs.xenarch.com/payments/pay-links.md), 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

| 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](https://docs.xenarch.com/payments/pay-links.md#the-params-tree) 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. |

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:

```json theme={null}
{
  "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

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](https://docs.xenarch.com/payments/webhooks.md) and authenticates [usage reports](https://docs.xenarch.com/payments/subscriptions.md#metered-billing). 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 |


## OpenAPI

````yaml POST /v1/links
openapi: 3.1.0
info:
  title: Xenarch API
  version: 0.1.0
servers:
  - url: https://api.xenarch.dev
security: []
paths:
  /v1/links:
    post:
      tags:
        - pay-links
      summary: Create Link
      description: Create a pay link from parameters signed by the seller's wallet.
      operationId: create_link_v1_links_post
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Idempotency-Key
        - name: authorization
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayLinkCreateRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayLinkCreateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PayLinkCreateRequest:
      properties:
        params:
          additionalProperties: true
          type: object
          title: Params
          description: 'The link parameters: kind, amount and the fields of that kind.'
        nonce:
          type: string
          pattern: ^0x[0-9a-fA-F]{64}$
          title: Nonce
          description: 32-byte random nonce as 0x-prefixed hex.
        created_at:
          type: integer
          title: Created At
          description: >-
            Unix time in seconds when the client built the link. The server
            clamps it to within 5 minutes of its own clock.
        signed_params:
          type: string
          pattern: ^0x[0-9a-fA-F]{130}$
          title: Signed Params
          description: >-
            65-byte EIP-712 signature over the parameters by the seller's
            wallet, as 0x-prefixed hex.
        download_url:
          anyOf:
            - type: string
              maxLength: 2048
            - type: 'null'
          title: Download Url
          description: >-
            Optional https download link for digital delivery, on an allowed
            host. Not part of the signed parameters. Shown only on the confirmed
            receipt.
      type: object
      required:
        - params
        - nonce
        - created_at
        - signed_params
      title: PayLinkCreateRequest
    PayLinkCreateResponse:
      properties:
        link_id:
          type: string
          title: Link Id
        link:
          type: string
          title: Link
        qr_png_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Qr Png Url
        embed_html:
          anyOf:
            - type: string
            - type: 'null'
          title: Embed Html
        webhook_secret:
          type: string
          title: Webhook Secret
        signed_params:
          type: string
          title: Signed Params
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
        - link_id
        - link
        - webhook_secret
        - signed_params
        - created_at
      title: PayLinkCreateResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.