Skip to content

Commit 04ed523

Browse files
melvincarvalhomelvincarvalho
committed
docs: update payment docs with balance flow and demo
1 parent bbb82bc commit 04ed523

1 file changed

Lines changed: 31 additions & 3 deletions

File tree

‎docs/payments.md‎

Lines changed: 31 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,12 +29,40 @@ Any resource can be payment-gated by adding a `PaymentCondition` to its ACL:
2929
When a client requests the resource:
3030

3131
1. Server evaluates the ACL and finds the `PaymentCondition`
32-
2. Server responds with `402 Payment Required` and payment details in the body
33-
3. Client completes payment and retries with proof
34-
4. Server verifies and grants access
32+
2. Server checks the agent's balance in the webledger
33+
3. If balance >= cost — deducts and serves the resource (200)
34+
4. If balance < cost — responds with `402 Payment Required` and payment details
35+
36+
To fund their balance, users deposit via the `/pay/.deposit` endpoint using a TXO URI (currently testnet4 for development). The balance is tracked in the webledger at `/.well-known/webledgers/webledgers.json`.
3537

3638
**Design: fail-closed** — if the server encounters a condition type it doesn't support, access is denied. Unsupported conditions are never silently ignored.
3739

40+
#### Quick Demo
41+
42+
```bash
43+
# Start JSS with payments (testnet4 by default)
44+
jss start --pay --pay-cost 10
45+
46+
# Create an article and payment-gated ACL
47+
curl -X PUT http://localhost:3000/premium/article.jsonld \
48+
-H "Content-Type: application/ld+json" \
49+
-d '{"@type": "Article", "headline": "Premium Content"}'
50+
51+
curl -X PUT http://localhost:3000/premium/article.jsonld.acl \
52+
-H "Content-Type: application/ld+json" \
53+
-d '{"@context":{"acl":"http://www.w3.org/ns/auth/acl#"},"@graph":[{"@type":"acl:Authorization","acl:agent":{"@id":"did:nostr:YOUR_PUBKEY"},"acl:accessTo":{"@id":"/premium/article.jsonld"},"acl:mode":[{"@id":"acl:Read"}],"acl:condition":{"@type":"PaymentCondition","amount":"10","currency":"sats"}}]}'
54+
55+
# Try to read → 402 Payment Required
56+
curl -H "Authorization: Nostr <nip98-token>" http://localhost:3000/premium/article.jsonld
57+
58+
# Deposit testnet4 sats
59+
curl -X POST -H "Authorization: Nostr <nip98-token>" \
60+
http://localhost:3000/pay/.deposit -d 'txo:tbtc4:txid:vout'
61+
62+
# Try again → 200 OK + article
63+
curl -H "Authorization: Nostr <nip98-token>" http://localhost:3000/premium/article.jsonld
64+
```
65+
3866
### Pay Route (Full Backend)
3967

4068
Monetize API endpoints with per-request satoshi payments. Resources under `/pay/*` require NIP-98 authentication and a positive balance.

0 commit comments

Comments
 (0)