Skip to content

feat: add proxy type #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
vittominacori merged 1 commit into from
Mar 10, 2026
Merged

feat: add proxy type #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,4 +40,4 @@ jobs:
uses: ./.github/actions/setup

- name: Run Test
run: npm test
run: npm run test:coverage
50 changes: 28 additions & 22 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,9 @@ Links are hosted at [https://openpayment.link](https://openpayment.link).
## Install

```bash
npm install openpayment # SDK
npm install -g openpayment # CLI (global)
npm install openpayment # SDK
npm install -g openpayment # CLI (global)
npx skills add https://github.com/noncept/openpayment # SKILL
```

## CLI
Expand All @@ -20,6 +21,7 @@ openpayment create \
--price "<AMOUNT>" \
--payTo "<EVM_ADDRESS>" \
--network "<NETWORK>" \
[--resourceUrl "<HTTPS_URL_FOR_PROXY>"] \
--description "<DESCRIPTION>"
```

Expand Down Expand Up @@ -80,14 +82,15 @@ Example:

### CLI flags

| Flag | Required | Description |
| --------------- | -------- | ------------------------------------------- |
| `--type` | Yes | `SINGLE_USE`, `MULTI_USE`, or `VARIABLE` |
| `--price` | Yes | Amount in USDC, e.g. `10` or `0.50` |
| `--payTo` | Yes | Recipient EVM address (`0x` + 40 hex chars) |
| `--network` | Yes | CAIP-2 network ID |
| `--description` | No | Payment description, max 500 chars |
| `--json` | No | Print JSON output only |
| Flag | Required | Description |
| --------------- | ----------- | ------------------------------------------------------------------- |
| `--type` | Yes | `SINGLE_USE`, `MULTI_USE`, `VARIABLE`, or `PROXY` |
| `--price` | Yes | Amount in USDC, e.g. `10` or `0.50` |
| `--payTo` | Yes | Recipient EVM address (`0x` + 40 hex chars) |
| `--network` | Yes | CAIP-2 network ID |
| `--resourceUrl` | Conditional | Required when `--type` is `PROXY`; upstream API URL (`https://...`) |
| `--description` | No | Payment description, max 500 chars |
| `--json` | No | Print JSON output only |

## SDK

Expand All @@ -110,13 +113,14 @@ The `create()` function validates input locally before making any network call a

### Input fields

| Field | Type | Required | Description |
| ------------- | ------------------ | -------- | ----------------------------------------- |
| `type` | `string` | Yes | `SINGLE_USE`, `MULTI_USE`, or `VARIABLE` |
| `price` | `string \| number` | Yes | Positive USDC amount, e.g. `"10"` or `10` |
| `payTo` | `string` | Yes | Recipient EVM address |
| `network` | `string` | Yes | CAIP-2 network ID |
| `description` | `string` | No | Payment description, max 500 chars |
| Field | Type | Required | Description |
| ------------- | ------------------ | ----------- | --------------------------------------------------------------- |
| `type` | `string` | Yes | `SINGLE_USE`, `MULTI_USE`, `VARIABLE`, or `PROXY` |
| `price` | `string \| number` | Yes | Positive USDC amount, e.g. `"10"` or `10` |
| `payTo` | `string` | Yes | Recipient EVM address |
| `network` | `string` | Yes | CAIP-2 network ID |
| `description` | `string` | No | Payment description, max 500 chars |
| `resourceUrl` | `string` | Conditional | Required when `type` is `PROXY`; must be a valid `https://` URL |

### Return value

Expand All @@ -129,11 +133,12 @@ The `create()` function validates input locally before making any network call a

## Payment types

| Type | Use case |
| ------------ | ----------------------------------------------------------------------- |
| `SINGLE_USE` | One-time payment with fixed price (e.g., a specific order, invoice) |
| `MULTI_USE` | Fixed price, can be paid multiple times (e.g., recurring product) |
| `VARIABLE` | Reusable link; payer chooses amount per payment (e.g., tips, donations) |
| Type | Use case |
| ------------ | ----------------------------------------------------------------------------------------------- |
| `SINGLE_USE` | One-time payment with fixed price (e.g., a specific order, invoice) |
| `MULTI_USE` | Fixed price, can be paid multiple times (e.g., recurring product) |
| `VARIABLE` | Reusable link; payer chooses amount per payment (e.g., tips, donations) |
| `PROXY` | Fixed-price multi-use payment; after settlement, OpenPayment fetches a private upstream API URL |

## Networks

Expand All @@ -155,3 +160,4 @@ Support for custom ERC-20 tokens will be added soon.

- Website: https://openpayment.link
- GitHub: https://github.com/noncept/openpayment
- SKILL: [SKILL.md](./skills/openpayment/SKILL.md)
16 changes: 13 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,14 @@ Global CLI:
npm i -g openpayment
```

Install [SKILL](./skills/openpayment/SKILL.md):

```bash
npx skills add https://github.com/noncept/openpayment
```

> If you are an AI Agent, check [AGENTS.md](./AGENTS.md).

## SDK Usage

```ts
Expand All @@ -44,7 +52,7 @@ const result = await create({
type: "SINGLE_USE",
price: "10",
payTo: "0xYourWalletAddress",
network: "eip155:84532",
network: "eip155:8453",
description: "Example payment",
});

Expand Down Expand Up @@ -72,7 +80,7 @@ openpayment create \
--type "SINGLE_USE" \
--price "10" \
--payTo "0xYourWalletAddress" \
--network "eip155:84532" \
--network "eip155:8453" \
--description "Example payment"
```

Expand Down Expand Up @@ -128,16 +136,18 @@ Example:
- `SINGLE_USE` (one-time)
- `MULTI_USE` (reusable fixed amount)
- `VARIABLE` (reusable custom amount)
- `PROXY` (reusable fixed amount + upstream API proxy call after settlement)
- `price`: positive decimal string/number (example: `10`, `0.01`)
- `payTo`: EVM address (`0x` + 40 hex chars)
- `network`: `eip155:8453` or `eip155:84532`
- `description`: optional string, max 500 chars
- `resourceUrl`: required only for `PROXY` (`https://...`)

## Links:

- [OpenPayment website](https://openpayment.link/)
- [AGENTS.md](./AGENTS.md)
- [OpenClaw Skill](./skills/openpayment/SKILL.md)
- [SKILL.md](./skills/openpayment/SKILL.md)

## License

Expand Down
66 changes: 33 additions & 33 deletions package-lock.json
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

7 changes: 4 additions & 3 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "openpayment",
"description": "OpenPayment SDK and CLI for creating x402 payment links",
"version": "0.1.1",
"version": "0.1.2",
"type": "module",
"private": true,
"main": "./dist/index.js",
Expand Down Expand Up @@ -31,6 +31,7 @@
"build": "tsc -p tsconfig.json",
"build:watch": "tsc -p tsconfig.json --watch --preserveWatchOutput",
"test": "npm run build && node --test test/**/*.test.mjs",
"test:coverage": "npm run build && node --test --experimental-test-coverage test/**/*.test.mjs",
"lint": "eslint .",
"lint:fix": "eslint . --fix",
"format": "prettier --write .",
Expand Down Expand Up @@ -66,8 +67,8 @@
"license": "MIT",
"devDependencies": {
"@eslint/js": "^10.0.1",
"@types/node": "^24.11.0",
"eslint": "^10.0.2",
"@types/node": "^24.12.0",
"eslint": "^10.0.3",
"globals": "^17.4.0",
"prettier": "^3.8.1",
"rimraf": "^6.1.3",
Expand Down
Loading