# OpenAPI Reference

The OpenAPI reference is the exact HTTP contract for direct PayChain integrations. Use it when you need endpoint paths, request bodies, response schemas, query parameters, and error shapes.

{% hint style="info" %}
**Reference note:** The OpenAPI contract is external-only. Dashboard session routes, admin routes, internal routes, mock routes, and health endpoints are excluded.
{% endhint %}

### Where to find it

| Format        | Location                                |
| ------------- | --------------------------------------- |
| JSON contract | `/docs/openapi` on the PayChain web app |
| Repo source   | `apps/web/contracts/openapi.json`       |
| Human guides  | This GitBook space                      |

### How to use OpenAPI with these docs

* Start with Payment flows to choose the right integration pattern.
* Use SDK guide if you are building with Node.js or TypeScript.
* Use REST API guide if you are calling PayChain over HTTPS directly.
* Use this OpenAPI reference when you need exact fields, schemas, and path details.

### Included surfaces

The external contract includes the core merchant integration surfaces:

* Businesses.
* Customers.
* Invoices.
* Public invoice status.
* Balances.
* Transactions.
* Withdrawals.
* Webhook configuration and delivery events.
* Networks.
* Tokens.
* Prices and supported assets.

For human-readable network guidance, see Supported networks and tokens.

### Excluded surfaces

The contract intentionally excludes:

* Admin endpoints.
* Dashboard-only session flows.
* API key creation and rotation flows.
* Internal infrastructure routes.
* Mock/testing-only routes.
* Health and metrics endpoints.

{% hint style="warning" %}
**Security note:** If an endpoint can change admin configuration, create API keys, alter billing state, or manage internal infrastructure, it should not appear in the external OpenAPI contract.
{% endhint %}

### Authentication

External API requests use the `x-api-key` header.

```http
x-api-key: $PAYCHAIN_API_KEY
content-type: application/json
```

Use `Idempotency-Key` on mutating requests.

```http
Idempotency-Key: order_123_invoice
```

### Updating the contract

When endpoint behavior changes, regenerate the external contract from the repo and review it before publishing:

```bash
pnpm --filter @paychain/web contracts:pull
```

Before publishing, confirm:

* No admin paths are included.
* No internal provider or signer details are included.
* Examples use placeholder IDs, addresses, and secrets.
* Webhook routes are included.
* Response schemas match the deployed API.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.paychainhq.io/paychainhq-documentation-page/developer-quickstart/openapi-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.