> ## 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 pay links

> Create USDC pay links from the CLI, the TypeScript or Python SDK, or POST /v1/links. Your wallet signs the terms. Payments go straight to it.

Every pay link carries a signature from your wallet over its terms: who receives the money, how much, in which currency, on which network, and what kind of link it is. The API checks that signature when you create the link and again every time the checkout page loads it. Xenarch cannot change the terms of a link you signed.

You can create links in the dashboard at [dash.xenarch.dev](https://dash.xenarch.dev), or with the tools below.

## Before you start

* A Xenarch account and a wallet linked to it. Sign in with that wallet.
* The receiving wallet (`to`) must be the account's owner wallet or a full co-owner wallet. A wallet you link later can receive money 24 hours after you link it.
* The wallet that signs the link must be the wallet you are signed in with. With a merchant API key, it is the account's owner wallet.

## The params tree

A link is described by a `params` object. Each field is a tagged value of the form `{"state": "lit", "value": ...}`. Five fields are required:

| Field | Value |
| - | - |
| `to` | Your receiving wallet address |
| `amount` | Decimal string in USDC, such as `"25.00"`, or `"open"` for pay what you want |
| `currency` | `"USDC"` |
| `network` | `"base"` |
| `kind` | `"checkout"`, `"subscription"`, `"invoice"` or `"donation"` |

Common optional fields:

| Field | Value |
| - | - |
| `product_name` | Product or line label shown at checkout |
| `description` | Free text shown at checkout |
| `type` | `one_time` (default), `per_day`, `per_week`, `per_month` or `per_year` |
| `renewal` | Subscriptions only: `reminder` or `permit`. See [Subscriptions](https://docs.xenarch.com/payments/subscriptions.md). |
| `min_amount`, `max_amount` | Bounds for an `"open"` amount |
| `single_use` | `true` to accept one payment only. Defaults to `false`. |
| `expiry` | ISO 8601 timestamp. Without it the link does not expire. |
| `return_url` | Where the buyer goes after a confirmed payment |
| `cancel_url` | Where the "back to seller" link points |
| `webhook_url` | HTTPS endpoint for [webhook events](https://docs.xenarch.com/payments/webhooks.md) |
| `fundraising_goal`, `fundraising_show_progress` | Donation links: goal amount and progress bar |
| `metadata` | Key and value map for your own references. Do not put personal data in it. |

The full, versioned field list is public:

```bash theme={null}
curl https://api.xenarch.dev/v1/links/schema
```

> [!NOTE]
>
> The schema response includes `"max_amount_usd": "1.00"`. It is a display hint for clients. The create endpoint does not reject larger fixed amounts.

## Create with the CLI

The `xenarch` CLI (npm `xenarch` 1.4.0) builds the params tree, validates it, signs it with your wallet and creates the link.

```bash theme={null}
npx xenarch wallet import          # or: wallet generate, wallet connect
npx xenarch agent login            # Sign-In with Ethereum, saves a 7-day session
npx xenarch links create           # interactive prompts
```

Non-interactive, with flat field values (the CLI fills `to`, `currency` and `network` from your wallet and defaults):

```bash theme={null}
npx xenarch links create \
  --params '{"amount": "25.00", "kind": "checkout", "product_name": "Consulting hour"}' \
  --confirm
```

Without `--confirm`, a non-interactive run prints the terms it would sign and exits without creating anything. Other commands: `xenarch links list`, `links get <id>`, `links revoke <id>`, `links events <id>`, `links webhook set <id> --url <https-url>`.

## Create with the TypeScript SDK

```bash theme={null}
npm install @xenarch/sdk
```

```ts theme={null}
import { Xenarch } from "@xenarch/sdk";

// Reuses the session and local wallet saved by `xenarch agent login`
const sdk = await Xenarch.fromConfig();

const 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" },
};

const check = await sdk.merchant.links.validate(params);   // { ok, missing, errors }
const link = await sdk.merchant.links.create(params, { confirm: true });

console.log(link.link);            // https://pay.xenarch.com/l/<link_id>
console.log(link.webhook_secret);  // whsec_... store it now
```

You can also build the client with `createXenarch({ sessionToken, privateKey })`, where `sessionToken` is the `xen_session` value and `privateKey` is the signing wallet's key. `create` validates first and throws `PayLinkValidationError` when fields are missing. `create` and `revoke` require `{ confirm: true }` unless you build the client with `requireConfirm: false`.

## Create with the Python SDK

```bash theme={null}
pip install xenarch
```

```python theme={null}
from xenarch.merchant import MerchantClient

# Reuses the session and local wallet saved by `xenarch agent login`
mc = MerchantClient.from_config()

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"},
}

link = mc.links.create(params, confirm=True)
print(link["link"], link["webhook_secret"])
```

`MerchantClient(session_token, private_key=..., api_base="https://api.xenarch.dev")` takes explicit credentials instead. The Python merchant client needs Python 3.12 or later.

## Create with the REST API

`POST /v1/links` takes the params tree plus a signature from your wallet. See [Create link](https://docs.xenarch.com/api-reference/links/create.md) for the request body and the EIP-712 message to sign. Authenticate with your dashboard session or a merchant API key:

```bash theme={null}
-H "Authorization: Bearer xm_live_..."
```

Create merchant API keys in the dashboard or with `xenarch keys create`. A key can call the pay link, payment and subscriber endpoints. It cannot link wallets or mint more keys.

## What you get back

| Field | Meaning |
| - | - |
| `link_id` | 24-character id |
| `link` | Hosted checkout URL, `https://pay.xenarch.com/l/<link_id>` |
| `webhook_secret` | `whsec_` secret that signs webhooks for this link. The API returns it here and again only when you rotate it. |
| `signed_params` | Your signature |
| `created_at` | Creation time |

## Digital delivery

To hand over a file after payment, pass a top-level `download_url` in the create request (not inside `params`). It stays hidden until the payment is confirmed and then appears on the receipt. It must be an `https` URL on an allowed host, such as Google Drive, Dropbox, GitHub, Gumroad, WeTransfer, MEGA, Cloudflare R2, Amazon S3, Bunny CDN or `cdn.xenarch.dev`.

## Manage links

* `GET /v1/links` lists your links. See [List links](https://docs.xenarch.com/api-reference/links/list.md).
* `GET /v1/links/{link_id}` returns one link. See [Get link](https://docs.xenarch.com/api-reference/links/get.md).
* `DELETE /v1/links/{link_id}` revokes a link. Payers can no longer pay it. Revoking is permanent.


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