Skip to content

Latest commit

 

History

History
382 lines (290 loc) · 10.2 KB

README.md

File metadata and controls

382 lines (290 loc) · 10.2 KB
Raw

image

HTTP-Nostr

HTTP-Nostr is designed to bridge the gap between the decentralized Nostr protocol and traditional HTTP endpoints with NIP-47 in mind. It offers seamless integration, allowing for real-time interaction with the Nostr network through a well-defined HTTP API. Developers/Nostr clients can fetch NIP-47 info, publish NIP-47 requests, or subscribe to events based on filters to create client side applications on Nostr without worrying about websockets.

For subscriptions/NIP-47 requests, HTTP-Nostr accepts a webhook URL to notify about the new events/response event.

🤙 Usage

Fetch NWC Info

Every NWC-enabled wallet has a pubkey according to the NWC specification. This GET request returns a pubkey's NWC capabilities (if any)

POST /nip47/info

Request Body

name type data type description
relayUrl optional string If no relay is provided, it uses the default relay (wss://relay.getalby.com/v1)
walletPubkey required string Pubkey of the NWC Wallet Provider

Response

{
  "event": {
    "id": "a16ye1391c22xx........xxxxx",
    "pubkey": "a16y69effexxxx........xxxxx",
    "created_at": 1708336682,
    "kind": 13194,
    "tags": [],
    "content": "pay_invoice, pay_keysend, get_balance, get_info, make_invoice, lookup_invoice, list_transactions",
    "sig": "<signature>"
  }
}

Publish NWC Request

Publishes the NWC request event and returns the response

Without webhook

POST /nip47

Request Body

name type data type description
relayUrl optional string If no relay is provided, it uses the default relay (wss://relay.getalby.com/v1)
walletPubkey required string Pubkey of the NWC Wallet Provider
event required JSON object (see example) Signed request event

Event Example

{
  "id": "a16ycf4a01bcxx........xxxxx",
  "pubkey": "a16y69effexxxx........xxxxx",
  "created_at": 1700000021,
  "kind": 23194,
  "tags": [
    [
      "p",
      "a16y6sfa01bcxx........xxxxx"
    ]
  ],
  "content": "<encrypted content>",
  "sig":"<signature>"
}
// Source: https://pkg.go.dev/github.com/nbd-wtf/go-nostr@v0.30.0#Event

Response

{
  "event": {
    "id": "a16ycf4a01bcxx........xxxxx",
    "pubkey": "a16y69effexxxx........xxxxx",
    "created_at": 1709033612,
    "kind": 23195,
    "tags": [
      [
        "p",
        "f490f5xxxxx........xxxxx"
      ],
      [
        "e",
        "a41aefxxxxx........xxxxx"
      ]
    ],
    "content": "<encrypted content>",
    "sig": "<signature>",
  },
  "state": "PUBLISHED"
}

With webhook

POST /nip47/webhook

Request Body

name type data type description
relayUrl optional string If no relay is provided, it uses the default relay (wss://relay.getalby.com/v1)
webhookUrl required string Webhook URL to publish the response event
walletPubkey required string Pubkey of the NWC Wallet Provider
event required JSON object (see example) Signed request event

Response

{
  "state": "WEBHOOK_RECEIVED"
}

Response to webhook

{
  "id": "a16ycf4a01bcxx........xxxxx",
  "pubkey": "a16y69effexxxx........xxxxx",
  "created_at": 1709033612,
  "kind": 23195,
  "tags": [
    [
      "p",
      "f490f5xxxxx........xxxxx"
    ],
    [
      "e",
      "a41aefxxxxx........xxxxx"
    ]
  ],
  "content": "<encrypted content>",
  "sig": "<signature>",
}

Publish Event

Publishes any signed event to the specified relay.

POST /publish

Request Body

name type data type description
relayUrl optional string If no relay is provided, it uses the default relay (wss://relay.getalby.com/v1)
event required JSON object (see example) Signed event

Response

{
  "eventId": "a16ycf4a01bcxx........xxxxx",
  "relayUrl": "wss://relay.custom.com/v1",
  "state": "PUBLISHED",
}

Subscribe to Events

Notifies about new events matching the filter provided via webhooks.

POST /subscriptions

Request Body

name type data type description
relayUrl optional string If no relay is provided, it uses the default relay
webhookUrl required string Webhook URL to publish events
filter required JSON object (see example) Filters to subscribe to

Filter Example

{
  "ids": ["id1", "id2"],
  "kinds": [1,2],
  "authors": ["author1", "author2"],
  "since": 1721212121,
  "until": 1721212121,
  "limit": 10,
  "search": "example search",
  "#tag1": ["value1", "value2"],
  "#tag2": ["value3"],
  "#tag3": ["value4", "value5", "value6"],
}
// Source: https://pkg.go.dev/github.com/nbd-wtf/go-nostr@v0.30.0#Filter

Response

{
  "subscription_id": "f370d1fc-x0x0-x0x0-x0x0-8f68fa12f32c",
  "webhookUrl": "https://your.webhook.url"
}

Response to Webhook URL

{
  "id": "a16ycf4a01bcxx........xxxxx",
  "pubkey": "a16y69effexxxx........xxxxx",
  "created_at": 1709033612,
  "kind": 23195,
  "tags": [
    [
      "p",
      "f490f5xxxxx........xxxxx"
    ],
    [
      "e",
      "a41aefxxxxx........xxxxx"
    ]
  ],
  "content": "<encrypted content>",
  "sig": "<signature>"
}

Subscribe to NWC Notifications

Notifies about 23196 kind events (NWC notifications) of the connection pubkey from the wallet service.

POST /nip47/notifications

Request Body

name type data type description
relayUrl optional string If no relay is provided, it uses the default relay
webhookUrl required string Webhook URL to publish events
walletPubkey required string Pubkey of the NWC Wallet Provider
connectionPubkey required string Public key of the user (derived from secret in NWC connection string)

Response

{
  "subscription_id": "f370d1fc-x0x0-x0x0-x0x0-8f68fa12f32c",
  "webhookUrl": "https://your.webhook.url"
}

Response to Webhook URL

{
  "id": "a16ycf4a01bcxx........xxxxx",
  "pubkey": "a16y69effexxxx........xxxxx",
  "created_at": 1709033612,
  "kind": 23196,
  "tags": [
    [
      "p",
      "f490f5xxxxx........xxxxx"
    ],
    [
      "e",
      "a41aefxxxxx........xxxxx"
    ]
  ],
  "content": "<encrypted content>",
  "sig": "<signature>"
}

Delete Subscriptions

Delete previously requested subscriptions.

DELETE /subscriptions/:id

Parameter

name type data type description
id required string UUID received on subscribing to a relay

Response

{
  "message": "Subscription stopped successfully",
  "state": "CLOSED"
}

🚀 Installation

Requirements

The application has no runtime dependencies. (simple Go executable).

As data storage PostgreSQL should be used.

$ cp .env.example .env
# edit the config for your needs
vim .env

🛠️ Development

go run cmd/server/main.go

⚙️ Configuration parameters

  • PORT: the port on which the app should listen on (default: 8080)
  • DEFAULT_RELAY_URL: the relay the app should subscribe to if nothing is provided (default: "wss://relay.getalby.com/v1")
  • DATABASE_URI: postgres connection string

⭐ Contributing

Contributions to HTTP-Nostr are welcome! Whether it's bug reports, feature requests, or contributions to code, please feel free to make your suggestions known.

📄 License

HTTP-Nostr is released under the MIT License. See the LICENSE file for more details.