PathClient

Construction, options, and how the transport handles versions, idempotency and signing.

Construction

import { PathClient } from '@pathprotocol/sdk';

const path = new PathClient({
  baseUrl: 'https://api.example.com',
  apiVersion: '2026-10-04.genesis',
  credential: {
    kid: 'member_2026_01',
    privateKeyHex: process.env.PATH_MEMBER_KEY!,
    memberSlug: 'your-member',
  },
  timeoutMs: 15_000,
});

Options

Option	Type	Default	Notes
`baseUrl`	`string`	—	Operator base URL. Trailing slash optional
`apiVersion`	`string`	The version the SDK was built against	Pin it explicitly
`credential`	object	none	Omit for public-only use
`fetch`	`typeof fetch`	global	Inject for testing or a custom agent
`timeoutMs`	`number`	`15000`	Aborts the request

`credential`

Field	Notes
`kid`	Your key id, as registered with the network
`privateKeyHex`	Ed25519 seed, 32 bytes, hex. Never in client code
`memberSlug`	Your member slug, used in signed answers

Calling a credentialed method without one throws before any request is made, with a message naming the option — a network round trip to discover a missing configuration value is wasted time.

What the transport does for you

Versions. Path-Version and Path-Protocol-Version on every request.

Signing. For credentialed calls, builds Path-Key-Id, Path-Timestamp and Path-Signature over method, path, timestamp and body digest.

Idempotency. Pass a key to createRequest and it becomes Path-Idempotency-Key. A replay returns the original object — which is what you want on the retry after a timeout, when you do not know whether the first call landed.

Errors. Non-2xx responses become PathApiError carrying the code, the message and the request_id.

Timeouts. Via AbortController, so an unreachable operator fails in seconds rather than hanging.

Public without a credential

const anyone = new PathClient({ baseUrl: 'https://api.example.com' });

await anyone.discovery();
await anyone.keys();
await anyone.readRequest('7fk2m9pq3vx8');
await anyone.readReceipt('rcpt_9a41c8f2b731');
await anyone.resolver('path:4a91c2f7e8d3');
await anyone.readInstruction('pi_4b81f2c7');

That set is the relationship profile — a complete path from key to capability that requires membership of nothing.

Methods

Method	Credential
`discovery()` · `discoveryAt(origin)` · `keys()`	—	Discovery
`sonar` · `resolver` · `finder`	mixed	Reachability
`issueAttestation` · `getAttestation` · ownership bindings	✓	Subjects
`setStandingIntent` · `addReceiveTarget`	✓	Addresses
`instruction` · `readInstruction` · `revokeInstruction`	mixed	Instructions
`createRequest` · `readRequest` · `revokeRequest` · `markPaid`	mixed	Requests
`createCheckoutSession` · `attemptCheckout` · `completeCheckout` · `revokeCheckout`	✓	Checkout
`createConnection` · `consumeConnection` · delegations	✓	Connections
`issueReceipt` · `readReceipt` · `transitionReceipt`	mixed	Receipts

Multiple operators

One client per operator. Do not sign a request to operator B with a credential issued by operator A.

const own = new PathClient({ baseUrl: OUR_API, credential });
const peer = new PathClient({ baseUrl: 'https://api.member-b.com' });