@coin-voyage/paykit-headless 0.0.1 → 0.0.2

package/README.md

@@ -1,32 +1,64 @@
 # @coin-voyage/paykit-headless
 
-Headless helpers for CoinVoyage PayKit and x402 payments.
+Headless helpers for CoinVoyage PayKit and x402 payments in agent or server runtimes.
 
-## x402 Agent Payments
+## What This Package Does
 
-Install the package in the agent runtime:
+`@coin-voyage/paykit-headless` is intended for agents and backend services that need to pay
+CoinVoyage x402 `PAYMENT-REQUIRED` challenges without a browser wallet UI.
+
+For EVM and Solana payments, it wraps the default x402 EVM and SVM clients and provides a single
+agent-oriented helper for fetching a challenge, signing the selected `accepts[]` entry, and retrying
+the protected resource.
+
+For Sui payments, it adds CoinVoyage-specific support that generic x402 clients do not provide yet:
+it can select a `sui:mainnet` accept, build or sign the required Sui transaction payload, and return a
+valid `PAYMENT-SIGNATURE` header for CoinVoyage's verifier.
+
+## Installation
 
 ```bash
 npm install @coin-voyage/paykit-headless
 ```
 
+## Exports
+
+The package exposes two public entry points:
+
+```ts
+import { readResponseBody } from "@coin-voyage/paykit-headless"
+import {
+  executeX402AgentPayment,
+  createSuiX402PaymentSignatureHeader,
+  decodeX402PaymentRequiredHeader,
+  type X402AgentPaymentRequest,
+} from "@coin-voyage/paykit-headless/x402"
+```
+
+Do not import internal files such as `x402/agent` or `x402/sui`; use the `x402` barrel.
+
+## Agent Payment Flow
+
 Use `executeX402AgentPayment` when the agent should fetch a `PAYMENT-REQUIRED` challenge, create a
-`PAYMENT-SIGNATURE`, and retry the protected resource:
+`PAYMENT-SIGNATURE`, and retry the protected resource.
 
 ```ts
 import { executeX402AgentPayment } from "@coin-voyage/paykit-headless/x402"
 
+const coinType = "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC"
+const privateKey = process.env.AGENT_SUI_PRIVATE_KEY
+const url = new URL("https://example.com/api/agent/payment-required")
+url.searchParams.set("preferred_chain_type", "SUI")
+url.searchParams.set("preferred_chain_id", "30000000000002")
+url.searchParams.set("preferred_token_address", coinType)
+
 const result = await executeX402AgentPayment({
-  url:
-    "https://example.com/api/agent/payment-required" +
-    "?preferred_chain_type=SUI" +
-    "&preferred_chain_id=30000000000002" +
-    "&preferred_token_address=0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
+  url: url.toString(),
+  chainType: "SUI",
   network: "sui:mainnet",
-  asset: "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
+  asset: coinType,
   maxAmount: "20000",
-  chainType: "SUI",
-  privateKey: process.env.X402_AGENT_SUI_PRIVATE_KEY,
+  privateKey,
 })
 
 if (!result.ok) {
@@ -34,49 +66,96 @@ if (!result.ok) {
 }
 ```
 
-Do not request `?preferred_chain_type=SUI` by itself. If you send an `X402RequirementRequest`, include
-`preferred_chain_type` and `preferred_token_address` together. If you do not have a preferred token,
-omit all preference fields and choose from the returned `accepts[]` entries.
+`privateKey` must match `chainType`:
+
+| `chainType` | Expected key |
+| --- | --- |
+| `EVM` | EVM private key for `eip155:*` accepts |
+| `SOL` | Solana private key for `solana:*` accepts |
+| `SUI` | Sui Ed25519 private key for `sui:*` accepts |
 
-For a challenge that was already fetched, pass the `PAYMENT-REQUIRED` header:
+The agent filters `accepts[]` by `chainType`, then by `network`, `asset`, `paymentIdentifier`, and
+`maxAmount` when those fields are provided.
+
+## Payment Requirement Preferences
+
+`X402RequirementRequest` is optional as a whole. If you send it, include both
+`preferred_chain_type` and `preferred_token_address`.
+
+Valid tailored request:
+
+```json
+{
+  "preferred_chain_type": "SUI",
+  "preferred_chain_id": 30000000000002,
+  "preferred_token_address": "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC"
+}
+```
+
+Do not request only `?preferred_chain_type=SUI`. If you do not need a tailored token response, omit all
+preference fields and choose from the returned `accepts[]`.
+
+## Existing PAYMENT-REQUIRED Header
+
+If you already fetched a challenge, pass the header to `executeX402AgentPayment`:
+
+```ts
+const result = await executeX402AgentPayment({
+  url: "https://example.com/api/agent/payment-required",
+  paymentRequiredHeader,
+  chainType: "SUI",
+  network: "sui:mainnet",
+  asset: coinType,
+  maxAmount: "20000",
+  privateKey,
+})
+```
+
+For Sui-only integrations that only need the signature header:
 
 ```ts
 import { createSuiX402PaymentSignatureHeader } from "@coin-voyage/paykit-headless/x402"
 
 const { paymentSignature } = await createSuiX402PaymentSignatureHeader(paymentRequiredHeader, {
   network: "sui:mainnet",
-  asset: "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
+  asset: coinType,
   maxAmount: "20000",
-  privateKey: process.env.X402_AGENT_SUI_PRIVATE_KEY,
-  rpcUrl: process.env.X402_AGENT_SUI_RPC_URL,
+  privateKey,
+  rpcUrl: process.env.SUI_RPC_URL,
 })
 ```
 
-## Sui Payload Contract
+## Sui PAYMENT-SIGNATURE Payload
 
 Sui x402 support uses a CoinVoyage-specific payload carried in the standard base64
-`PAYMENT-SIGNATURE` header. The package:
+`PAYMENT-SIGNATURE` header. The SDK:
 
 - Selects the returned `sui:mainnet` `accepts[]` entry without changing `scheme`, `network`,
   `asset`, `amount`, `payTo`, or `paymentIdentifier`.
-- Builds a Sui programmable transaction block that transfers the exact raw `amount` of the exact
-  coin type to `payTo`.
+- Builds a Sui programmable transaction block when the backend does not provide transaction bytes.
+- Transfers the exact raw `amount` of the exact Sui coin type to `payTo`.
 - Signs the transaction with the configured Sui Ed25519 key.
-- Encodes `payload.transaction`, `payload.signatures`, `payload.signature`, and `payload.payer`.
+- Encodes the signed transaction bytes, signature, payer address, selected accept, and CoinVoyage Sui
+  payload fields into `PAYMENT-SIGNATURE`.
 
 If the server provides prepared Sui transaction bytes in `accept.transactionBytes`, `accept.txBytes`,
-`accept.extra.sui.transactionBytes`, or `accept.extra.sui.txBytes`, the package signs those bytes
-instead of constructing a transfer transaction.
+`accept.extra.sui.transactionBytes`, or `accept.extra.sui.txBytes`, the SDK signs those bytes instead
+of constructing a transfer transaction. It is valid for the backend `extra` object to contain only
+`paymentIdentifier`; in that case the SDK builds the Sui PTB from the payer's owned coins.
 
-## Required Keys
+## Current Limits
 
-Use rail-specific private keys when possible:
+- Native ETH and native SOL accepts are not supported by the headless agent. Use token accepts such as
+  USDC.
+- Sui accepts require this SDK or another client that implements CoinVoyage's Sui
+  `PAYMENT-SIGNATURE` payload.
+- The `maxAmount` value is compared against the raw token amount, not display units.
 
-```bash
-X402_AGENT_EVM_PRIVATE_KEY=
-X402_AGENT_SVM_PRIVATE_KEY=
-X402_AGENT_SUI_PRIVATE_KEY=
-```
+## Key Handling
+
+The package does not read private keys or RPC URLs from environment variables. Your application is
+responsible for loading the correct key and passing it as `privateKey`.
 
-Pass the private key that matches the request `chainType`. `X402_AGENT_PRIVATE_KEY` can be used as a
-local fallback, but separate rail-specific keys are safer for agents.
+For each payment attempt, pass the key that matches `chainType`. For example, pass a Sui Ed25519 key
+when `chainType` is `"SUI"`, an EVM private key when `chainType` is `"EVM"`, and a Solana private key
+when `chainType` is `"SOL"`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@coin-voyage/paykit-headless",
   "description": "Headless CoinVoyage PayKit clients and protocol helpers.",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "private": false,
   "sideEffects": false,
   "author": "Lars <lars@coinvoyage.io>",