mirror of
https://github.com/nostr-protocol/nips.git
synced 2024-12-22 16:35:52 -05:00
working
This commit is contained in:
Coach Chuck
parent
70ede5e67d
commit
b6f3e249cd
229
105.md
Normal file
229
105.md
Normal file
|
|
@ -0,0 +1,229 @@
|
||||||
|
NIP-105
|
||||||
|
======
|
||||||
|
|
||||||
|
API Service Marketplace
|
||||||
|
-------------------------------
|
||||||
|
|
||||||
|
`draft` `optional` `author:coachchuckff` `author:unclejim21` `author:cmdruid`
|
||||||
|
|
||||||
|
This NIP defines `kind:31402` (a _parameterized replaceable event_) for broadcasting API services, endpoints and their costs in mSats. API services are offered ala carte to be paid via lightning invoices.
|
||||||
|
|
||||||
|
API service providers will issue a `kind:31402` event as an API service offering. Clients can fetch `s` (service) tag offerings, call their endpoints, and pay per use. Creating an API service marketplace.
|
||||||
|
|
||||||
|
## Protocol flow
|
||||||
|
|
||||||
|
1. API Service provider creates and hosts API service offerings, they then issue a `kind:31402` event for each `s` ( service ) tag.
|
||||||
|
2. Client fetches API offerings by `s` tag.
|
||||||
|
3. Client chooses a provider(s) and POSTs to their `endpoint`. The POST body should match exactly what is required by the underlying API less the API key. ( Or following the note's `schema` )
|
||||||
|
4. The service provider should validate their request and return a lightning invoice with a `successAction` url. The `successAction` url should be formatted as such: `<endpoint>/<invoice_hash>/get_result`
|
||||||
|
5. The client pays.
|
||||||
|
6. The client will poll the `successAction` until the service provider has returned the result(s) matching exactly what the underlying API will produce ( Or following the note's `outputSchema` ).
|
||||||
|
|
||||||
|
## Server Functions
|
||||||
|
### Create Invoice
|
||||||
|
|
||||||
|
Initally, the client will make a POST request to the `endpoint`. The POST body should be exactly what the underlying API is expecting less the API key. This information should also be represented in the `schema` portion of the `content` field.
|
||||||
|
|
||||||
|
The service provider will then do the following:
|
||||||
|
|
||||||
|
1. Validate their API request
|
||||||
|
2. Issue a lightning invoice
|
||||||
|
|
||||||
|
The issued lightning invoice will contain a `successAction` url formatted as so:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
tag: "url",
|
||||||
|
url: `https://example.api/chat/${paymentHash}/get_result`,
|
||||||
|
description: "Open to get the confirmation code for your purchase."
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
From here the service provider can either listen and execute their API request "on-payment" or wait until the client calls `get_results`.
|
||||||
|
|
||||||
|
### Get Results
|
||||||
|
|
||||||
|
Once the client has gotten the `successAction` url, they can issue a GET request. The service provider should respond in one of three ways:
|
||||||
|
|
||||||
|
1. 200 ( DONE ) - the service provider returns the results of the API as if it was coming from the product itself ( Errors included )
|
||||||
|
2. 202 ( WORKING ) - the service provider returns a status that indicates the results are not ready yet.
|
||||||
|
3. 402 ( NOT PAID YET ) - the service provider should respond with a 402 error if the client has not paid yet.
|
||||||
|
|
||||||
|
It is up to the Client to poll the `successAction` until a terminal result is reached.
|
||||||
|
|
||||||
|
## Event Reference and Examples
|
||||||
|
|
||||||
|
### Offering Event
|
||||||
|
|
||||||
|
`kind:31402`
|
||||||
|
|
||||||
|
`.content` should be a JSON stringified version of the following JSON:
|
||||||
|
```typescript
|
||||||
|
enum OfferingStatus {
|
||||||
|
up = 'UP',
|
||||||
|
down = 'DOWN',
|
||||||
|
closed = 'CLOSED'
|
||||||
|
}
|
||||||
|
|
||||||
|
interface OfferingContent = {
|
||||||
|
endpoint: string, // The POST endpoint you call to pay/fetch
|
||||||
|
status: OfferingStatus, // UP/DOWN/CLOSED
|
||||||
|
cost: number, // The cost per call in mSats
|
||||||
|
schema?: Object, // Reccomended - JSON schema for the POST body of the endpoint
|
||||||
|
outputSchema?: Object, // Reccomended - JSON schema for the response of the call
|
||||||
|
description?: string // Optional - Description for the end user
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
`.tag` MUST include the following:
|
||||||
|
|
||||||
|
- `s`, the service tag should simply be the underlying API endpoint of the service provided. For example if you are offering a ChatGPT service, you would set `s` = `https://api.openai.com/v1/chat/completions`. This way the service they are buying is implicit.
|
||||||
|
- `d`, following **parameterized replaceable events** in [NIP-01](https://github.com/nostr-protocol/nips/blob/master/01.md), this tag allows this event to be replaceable. Since there should only be one service per pubkey, the `d` tag should match the `s` tag.
|
||||||
|
|
||||||
|
### Example Service Event
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
|
||||||
|
const content = {
|
||||||
|
endpoint: "https://example.api/chat/",
|
||||||
|
status: "UP",
|
||||||
|
cost: 5000,
|
||||||
|
schema: {...},
|
||||||
|
outputSchema: {...},
|
||||||
|
description: "This will call the ChatGPT endpoint"
|
||||||
|
}
|
||||||
|
|
||||||
|
const event = {
|
||||||
|
"kind": 31402,
|
||||||
|
"created_at": 1675642635,
|
||||||
|
"content": JSON.stringify(content),
|
||||||
|
"tags": [
|
||||||
|
["s", "https://api.openai.com/v1/chat/completions"]
|
||||||
|
["d", "https://api.openai.com/v1/chat/completions"],
|
||||||
|
],
|
||||||
|
"pubkey": "<pubkey>",
|
||||||
|
"id": "<id>"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Example Schema
|
||||||
|
|
||||||
|
The following is for the `gpt-3.5-turbo` input schema:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "object",
|
||||||
|
"properties": {
|
||||||
|
"model": {
|
||||||
|
"type": "string",
|
||||||
|
"enum": ["gpt-3.5-turbo"]
|
||||||
|
},
|
||||||
|
"messages": {
|
||||||
|
"type": "array",
|
||||||
|
"items": {
|
||||||
|
"type": "object",
|
||||||
|
"properties": {
|
||||||
|
"role": {
|
||||||
|
"type": "string",
|
||||||
|
"enum": ["system", "user"]
|
||||||
|
},
|
||||||
|
"content": {
|
||||||
|
"type": "string"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"required": ["role", "content"]
|
||||||
|
},
|
||||||
|
"minItems": 1
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"required": ["model", "messages"]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The following is for the `gpt-3.5-turbo` output schema:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "object",
|
||||||
|
"required": ["id", "object", "created", "model", "choices", "usage"],
|
||||||
|
"properties": {
|
||||||
|
"id": {
|
||||||
|
"type": "string",
|
||||||
|
"pattern": "^chatcmpl-[a-zA-Z0-9-]+$"
|
||||||
|
},
|
||||||
|
"object": {
|
||||||
|
"type": "string",
|
||||||
|
"enum": ["chat.completion"]
|
||||||
|
},
|
||||||
|
"created": {
|
||||||
|
"type": "integer"
|
||||||
|
},
|
||||||
|
"model": {
|
||||||
|
"type": "string"
|
||||||
|
},
|
||||||
|
"choices": {
|
||||||
|
"type": "array",
|
||||||
|
"items": {
|
||||||
|
"type": "object",
|
||||||
|
"required": ["index", "message"],
|
||||||
|
"properties": {
|
||||||
|
"index": {
|
||||||
|
"type": "integer"
|
||||||
|
},
|
||||||
|
"message": {
|
||||||
|
"type": "object",
|
||||||
|
"required": ["role", "content"],
|
||||||
|
"properties": {
|
||||||
|
"role": {
|
||||||
|
"type": "string",
|
||||||
|
"enum": ["assistant"]
|
||||||
|
},
|
||||||
|
"content": {
|
||||||
|
"type": "string"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"finish_reason": {
|
||||||
|
"type": "string",
|
||||||
|
"enum": ["stop"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"usage": {
|
||||||
|
"type": "object",
|
||||||
|
"required": ["prompt_tokens", "completion_tokens", "total_tokens"],
|
||||||
|
"properties": {
|
||||||
|
"prompt_tokens": {
|
||||||
|
"type": "integer"
|
||||||
|
},
|
||||||
|
"completion_tokens": {
|
||||||
|
"type": "integer"
|
||||||
|
},
|
||||||
|
"total_tokens": {
|
||||||
|
"type": "integer"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
### Safey
|
||||||
|
|
||||||
|
It is not mandatory, but to raise the barrier to entry, clients should screen service provider's NIP-05 identifier. The domain used in their NIP-05, should be the same domain used for their endpoint.
|
||||||
|
|
||||||
|
Clients may wish to create a whitelist of trusted service providers once tested.
|
||||||
|
|
||||||
|
### Problems
|
||||||
|
|
||||||
|
- No data integrity - service providers can store/redistribute any data passed to them
|
||||||
|
- Service providers could take payment and never return the product
|
||||||
|
- Service providers are not gaurenteed to call the endpoint specified in the `s` tag
|
||||||
|
- No recourse for errored API fetches
|
||||||
|
- The `cost` field may not match the actual final price
|
||||||
|
- No proof of purchase
|
||||||
|
|
||||||
|
### Example Implementations
|
||||||
|
|
||||||
|
- [Server](https://github.com/Team-Pleb-TabConf-2023/nip-105-server)
|
||||||
|
- [Client](https://github.com/Team-Pleb-TabConf-2023/nip-105-client)
|
||||||
Loading…
Reference in New Issue
Block a user