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

# Get Link

> Read one pay link. The owner's dashboard session gets full detail with stats. Any other caller gets the public subset the hosted checkout renders.

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

```json 200 (public) theme={null}
{
  "link_id": "JJjIwDyV4N1CG9g8AHMxfdJ9",
  "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"}
  },
  "signed_params": "0x...",
  "status": "active",
  "kind": "checkout",
  "created_at": "2026-11-17T12:00:00Z",
  "expires_at": null,
  "paid_and_single_use": false,
  "latest_state": "CONFIRMED",
  "latest_payment": {
    "tx_hash": "0x...",
    "block_number": 38120455,
    "status": "confirmed",
    "value_usdc": "25.00",
    "expected_usdc": "25.00",
    "from_address": "0xBuyerWallet...",
    "confirmed_at": "2026-11-17T12:04:10Z",
    "reference_id": null
  },
  "cap_min_micro": null,
  "cap_suggested_micro": null,
  "period_cap_suggested_micro": null,
  "period_count_suggested": null
}
```

## Two views

* **Public subset.** No authentication. This is what the hosted checkout at `pay.xenarch.com` reads: the signed params, status, expiry, the latest payment and, for metered subscriptions, the suggested spending caps. Each public read counts as a view of the link.
* **Owner detail.** Returned when the request carries the `xen_session` cookie of the wallet that owns the link. It adds `stats` (views, paid count, revenue, payer wallets, last payment time), `metadata`, `suggested_cap_usdc` and `suggested_period_cap_usdc`. A merchant API key does not return owner detail on this endpoint.

The API re-checks `signed_params` against `params` on every read and returns `403` if they no longer match.

## Fields

| Field | Description |
| - | - |
| `status` | `active`, `expired` or `revoked`. An active link past `expires_at` reads as `expired`. |
| `latest_state` | Where the checkout should land: `AWAIT_PAY`, `TX_SUBMITTED`, `CONFIRMED`, `UNDERPAID`, `OVERPAID`, `EXPIRED`, `REVOKED` or `PAID` |
| `latest_payment` | The most recent payment on the link, or `null`. `status` is `confirmed`, `underpaid` or `overpaid`. Amounts are decimal USDC strings. `reference_id` is the invoice number on auto-numbered invoices. |
| `paid_and_single_use` | `true` once a single-use link has been paid |

Use `latest_payment` to show state in your UI. To fulfill orders, rely on a verified [webhook](https://docs.xenarch.com/payments/webhooks.md).

## Errors

| Status | Meaning |
| - | - |
| `403` | The stored params no longer match the signature |
| `404` | No link with this id |


## OpenAPI

````yaml GET /v1/links/{link_id}
openapi: 3.1.0
info:
  title: Xenarch API
  version: 0.1.0
servers:
  - url: https://api.xenarch.dev
security: []
paths:
  /v1/links/{link_id}:
    get:
      tags:
        - pay-links
      summary: Get Link
      description: >-
        Return a pay link. The owner gets the full record. Anyone else gets the
        public fields the checkout page shows.
      operationId: get_link_v1_links__link_id__get
      parameters:
        - name: link_id
          in: path
          required: true
          schema:
            type: string
            title: Link Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/PayLinkDetailResponse'
                  - $ref: '#/components/schemas/PublicPayLinkResponse'
                title: Response Get Link V1 Links  Link Id  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PayLinkDetailResponse:
      properties:
        link_id:
          type: string
          title: Link Id
        params:
          additionalProperties: true
          type: object
          title: Params
        signed_params:
          type: string
          title: Signed Params
        status:
          type: string
          enum:
            - active
            - expired
            - revoked
          title: Status
        kind:
          type: string
          title: Kind
        created_at:
          type: string
          format: date-time
          title: Created At
        expires_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Expires At
        paid_and_single_use:
          type: boolean
          title: Paid And Single Use
          default: false
        latest_state:
          type: string
          enum:
            - AWAIT_PAY
            - TX_SUBMITTED
            - CONFIRMED
            - UNDERPAID
            - OVERPAID
            - EXPIRED
            - REVOKED
            - PAID
          title: Latest State
          default: AWAIT_PAY
        latest_payment:
          anyOf:
            - $ref: '#/components/schemas/PayLinkLatestPayment'
            - type: 'null'
        stats:
          $ref: '#/components/schemas/PayLinkStats'
        events:
          items:
            $ref: '#/components/schemas/PayLinkEventItem'
          type: array
          title: Events
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
        suggested_cap_usdc:
          anyOf:
            - type: string
            - type: 'null'
          title: Suggested Cap Usdc
        suggested_period_cap_usdc:
          anyOf:
            - type: string
            - type: 'null'
          title: Suggested Period Cap Usdc
      type: object
      required:
        - link_id
        - params
        - signed_params
        - status
        - kind
        - created_at
        - expires_at
        - stats
        - events
      title: PayLinkDetailResponse
    PublicPayLinkResponse:
      properties:
        link_id:
          type: string
          title: Link Id
        params:
          additionalProperties: true
          type: object
          title: Params
        signed_params:
          type: string
          title: Signed Params
        status:
          type: string
          enum:
            - active
            - expired
            - revoked
          title: Status
        kind:
          type: string
          title: Kind
        created_at:
          type: string
          format: date-time
          title: Created At
        expires_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Expires At
        paid_and_single_use:
          type: boolean
          title: Paid And Single Use
          default: false
        latest_state:
          type: string
          enum:
            - AWAIT_PAY
            - TX_SUBMITTED
            - CONFIRMED
            - UNDERPAID
            - OVERPAID
            - EXPIRED
            - REVOKED
            - PAID
          title: Latest State
          default: AWAIT_PAY
        latest_payment:
          anyOf:
            - $ref: '#/components/schemas/PayLinkLatestPayment'
            - type: 'null'
        cap_min_micro:
          anyOf:
            - type: integer
            - type: 'null'
          title: Cap Min Micro
        cap_suggested_micro:
          anyOf:
            - type: integer
            - type: 'null'
          title: Cap Suggested Micro
        period_cap_suggested_micro:
          anyOf:
            - type: integer
            - type: 'null'
          title: Period Cap Suggested Micro
        period_count_suggested:
          anyOf:
            - type: integer
            - type: 'null'
          title: Period Count Suggested
      type: object
      required:
        - link_id
        - params
        - signed_params
        - status
        - kind
        - created_at
        - expires_at
      title: PublicPayLinkResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PayLinkLatestPayment:
      properties:
        tx_hash:
          type: string
          title: Tx Hash
        block_number:
          type: integer
          title: Block Number
        status:
          type: string
          enum:
            - confirmed
            - underpaid
            - overpaid
          title: Status
        value_usdc:
          type: string
          title: Value Usdc
        expected_usdc:
          type: string
          title: Expected Usdc
        from_address:
          type: string
          title: From Address
        confirmed_at:
          type: string
          format: date-time
          title: Confirmed At
        reference_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Reference Id
      type: object
      required:
        - tx_hash
        - block_number
        - status
        - value_usdc
        - expected_usdc
        - from_address
        - confirmed_at
      title: PayLinkLatestPayment
    PayLinkStats:
      properties:
        views:
          type: integer
          title: Views
          default: 0
        form_starts:
          type: integer
          title: Form Starts
          default: 0
        paid:
          type: integer
          title: Paid
          default: 0
        revenue_usd:
          type: string
          title: Revenue Usd
          default: '0'
        avg_time_to_pay_sec:
          anyOf:
            - type: integer
            - type: 'null'
          title: Avg Time To Pay Sec
        payer_wallets:
          items:
            type: string
          type: array
          title: Payer Wallets
          default: []
        last_payment_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Last Payment At
      type: object
      title: PayLinkStats
    PayLinkEventItem:
      properties:
        event_type:
          type: string
          title: Event Type
        payload:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Payload
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
        - event_type
        - created_at
      title: PayLinkEventItem
    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.