Skip to content

Latest commit

 

History

History
1173 lines (961 loc) · 32.7 KB

client.md

File metadata and controls

1173 lines (961 loc) · 32.7 KB
Raw

NOSTR API DEFINITION

A nostr request will take the same parameter and give the same response as an http request, but it will use nostr as transport, to do that it will send encrypted events to the server public key, in the event 6 thing are required:

  • rpcName: string containing the name of the method
  • params: a map with the all the url params for the method
  • query: a map with the the url query for the method
  • body: the body of the method request
  • requestId: id of the request to be able to get a response

The nostr server will send back a message response, and inside the body there will also be a requestId to identify the request this response is answering

NOSTR Methods

These are the nostr methods the client implements to communicate with the API via nostr

HTTP API DEFINITION

Supported HTTP Auths

These are the supported http auth types, to give different type of access to the API users

  • Admin:

    • expected context content
      • admin_id: string

  • App:

    • expected context content
      • app_id: string

  • Guest:

    • expected context content

  • GuestWithPub:

    • expected context content
      • app_id: string
      • pub: string

  • Metrics:

    • expected context content
      • operator_id: string

  • User:

    • expected context content
      • app_id: string
      • app_user_id: string
      • user_id: string

HTTP Methods

These are the http methods the client implements to communicate with the API

  • AddApp

    • auth type: Admin
    • http method: post
    • http route: /api/admin/app/add
    • input: AddAppRequest
    • output: AuthApp

  • AddAppInvoice

  • AddAppUser

  • AddAppUserInvoice

  • AddProduct

  • AuthApp

    • auth type: Admin
    • http method: post
    • http route: /api/admin/app/auth
    • input: AuthAppRequest
    • output: AuthApp

  • AuthorizeDebit

  • BanDebit

    • auth type: User
    • http method: post
    • http route: /api/user/debit/ban
    • input: DebitOperation
    • This methods has an empty response body

  • BanUser

  • BatchUser

    • auth type: User
    • http method: post
    • http route: /api/user/batch
    • This methods has an empty request body
    • This methods has an empty response body

  • CreateOneTimeInviteLink

  • DecodeInvoice

  • EditDebit

    • auth type: User
    • http method: post
    • http route: /api/user/debit/edit
    • input: DebitAuthorizationRequest
    • This methods has an empty response body

  • EncryptionExchange

    • auth type: Guest
    • http method: post
    • http route: /api/encryption/exchange
    • input: EncryptionExchangeRequest
    • This methods has an empty response body

  • EnrollAdminToken

    • auth type: User
    • http method: post
    • http route: /api/guest/npub/enroll/admin
    • input: EnrollAdminTokenRequest
    • This methods has an empty response body

  • GetApp

    • auth type: App
    • http method: post
    • http route: /api/app/get
    • This methods has an empty request body
    • output: Application

  • GetAppUser

  • GetAppUserLNURLInfo

  • GetAppsMetrics

  • GetDebitAuthorizations

    • auth type: User
    • http method: get
    • http route: /api/user/debit/get
    • This methods has an empty request body
    • output: DebitAuthorizations

  • GetHttpCreds

    • auth type: User
    • http method: post
    • http route: /api/user/http_creds
    • This methods has an empty request body
    • output: HttpCreds

  • GetInviteLinkState

  • GetLNURLChannelLink

    • auth type: User
    • http method: post
    • http route: /api/user/lnurl_channel/url
    • This methods has an empty request body
    • output: LnurlLinkResponse

  • GetLiveDebitRequests

    • auth type: User
    • http method: post
    • http route: /api/user/debit/sub
    • This methods has an empty request body
    • output: LiveDebitRequest

  • GetLiveUserOperations

    • auth type: User
    • http method: post
    • http route: /api/user/operations/sub
    • This methods has an empty request body
    • output: LiveUserOperation

  • GetLndMetrics

  • GetLnurlPayInfo

    • auth type: Guest
    • http method: get
    • http route: /api/guest/lnurl_pay/info
    • the request url query can take the following string items:
      • k1
    • This methods has an empty request body
    • output: LnurlPayInfoResponse

  • GetLnurlPayLink

    • auth type: User
    • http method: get
    • http route: /api/user/lnurl_pay/link
    • This methods has an empty request body
    • output: LnurlLinkResponse

  • GetLnurlWithdrawInfo

    • auth type: Guest
    • http method: get
    • http route: /api/guest/lnurl_withdraw/info
    • the request url query can take the following string items:
      • k1
    • This methods has an empty request body
    • output: LnurlWithdrawInfoResponse

  • GetLnurlWithdrawLink

    • auth type: User
    • http method: get
    • http route: /api/user/lnurl_withdraw/link
    • This methods has an empty request body
    • output: LnurlLinkResponse

  • GetMigrationUpdate

    • auth type: User
    • http method: post
    • http route: /api/user/migrations/sub
    • This methods has an empty request body
    • output: MigrationUpdate

  • GetNPubLinkingState

  • GetPaymentState

  • GetSeed

    • auth type: Admin
    • http method: get
    • http route: /api/admin/seed
    • This methods has an empty request body
    • output: LndSeed

  • GetUsageMetrics

    • auth type: Metrics
    • http method: post
    • http route: /api/reports/usage
    • This methods has an empty request body
    • output: UsageMetrics

  • GetUserInfo

    • auth type: User
    • http method: post
    • http route: /api/user/info
    • This methods has an empty request body
    • output: UserInfo

  • GetUserOperations

  • HandleLnurlAddress

    • auth type: Guest
    • http method: get
    • http route: /.well-known/lnurlp/:address_name
    • the request url params are the following string items:
      • address_name
    • This methods has an empty request body
    • output: LnurlPayInfoResponse

  • HandleLnurlPay

    • auth type: Guest
    • http method: get
    • http route: /api/guest/lnurl_pay/handle
    • the request url query can take the following string items:
      • amount
      • k1
      • lnurl
      • nostr
    • This methods has an empty request body
    • output: HandleLnurlPayResponse

  • HandleLnurlWithdraw

    • auth type: Guest
    • http method: get
    • http route: /api/guest/lnurl_withdraw/handle
    • the request url query can take the following string items:
      • k1
      • pr
    • This methods has an empty request body
    • This methods has an empty response body

  • Health

    • auth type: Guest
    • http method: get
    • http route: /api/health
    • This methods has an empty request body
    • This methods has an empty response body

  • LinkNPubThroughToken

    • auth type: GuestWithPub
    • http method: post
    • http route: /api/guest/npub/link
    • input: LinkNPubThroughTokenRequest
    • This methods has an empty response body

  • ListChannels

    • auth type: Admin
    • http method: get
    • http route: /api/admin/channels
    • This methods has an empty request body
    • output: LndChannels

  • LndGetInfo

  • NewAddress

  • NewInvoice

  • NewProductInvoice

    • auth type: User
    • http method: get
    • http route: /api/user/product/get/invoice
    • the request url query can take the following string items:
      • id
    • This methods has an empty request body
    • output: NewInvoiceResponse

  • OpenChannel

  • PayAddress

  • PayAppUserInvoice

  • PayInvoice

  • RequestNPubLinkingToken

  • ResetDebit

    • auth type: User
    • http method: post
    • http route: /api/user/debit/reset
    • input: DebitOperation
    • This methods has an empty response body

  • ResetNPubLinkingToken

  • RespondToDebit

    • auth type: User
    • http method: post
    • http route: /api/user/debit/finish
    • input: DebitResponse
    • This methods has an empty response body

  • SendAppUserToAppPayment

  • SendAppUserToAppUserPayment

  • SetMockAppBalance

    • auth type: App
    • http method: post
    • http route: /api/app/mock/blance/set
    • input: SetMockAppBalanceRequest
    • This methods has an empty response body

  • SetMockAppUserBalance

    • auth type: App
    • http method: post
    • http route: /api/app/mock/user/blance/set
    • input: SetMockAppUserBalanceRequest
    • This methods has an empty response body

  • SetMockInvoiceAsPaid

    • auth type: Guest
    • http method: post
    • http route: /api/lnd/mock/invoice/paid
    • input: SetMockInvoiceAsPaidRequest
    • This methods has an empty response body

  • UpdateCallbackUrl

  • UseInviteLink

    • auth type: GuestWithPub
    • http method: post
    • http route: /api/guest/invite
    • input: UseInviteLinkRequest
    • This methods has an empty response body

  • UserHealth

    • auth type: User
    • http method: post
    • http route: /api/user/health
    • This methods has an empty request body
    • This methods has an empty response body

INPUTS AND OUTPUTS

Messages

The content of requests and response from the methods

AddAppInvoiceRequest

AddAppRequest

  • allow_user_creation: boolean
  • name: string

AddAppUserInvoiceRequest

  • http_callback_url: string
  • invoice_req: NewInvoiceRequest
  • payer_identifier: string
  • receiver_identifier: string

AddAppUserRequest

  • balance: number
  • fail_if_exists: boolean
  • identifier: string

AddProductRequest

  • name: string
  • price_sats: number

AppMetrics

  • app: Application
  • available: number
  • fees: number
  • invoices: number
  • operations: ARRAY of: UserOperation
  • received: number
  • spent: number
  • total_fees: number
  • users: UsersInfo

AppUser

  • identifier: string
  • info: UserInfo
  • max_withdrawable: number

Application

  • balance: number
  • id: string
  • name: string
  • npub: string

AppsMetrics

AppsMetricsRequest

  • from_unix: number *this field is optional
  • include_operations: boolean *this field is optional
  • to_unix: number *this field is optional

AuthApp

AuthAppRequest

  • allow_user_creation: boolean *this field is optional
  • name: string

BanUserRequest

  • user_id: string

BanUserResponse

BannedAppUser

  • app_id: string
  • app_name: string
  • nostr_pub: string
  • user_identifier: string

CallbackUrl

  • url: string

ClosedChannel

  • capacity: number
  • channel_id: string
  • closed_height: number

ClosureMigration

  • closes_at_unix: number

CreateOneTimeInviteLinkRequest

  • sats: number *this field is optional

CreateOneTimeInviteLinkResponse

  • invitation_link: string

DebitAuthorization

  • authorized: boolean
  • debit_id: string
  • npub: string
  • rules: ARRAY of: DebitRule

DebitAuthorizationRequest

  • authorize_npub: string
  • request_id: string *this field is optional
  • rules: ARRAY of: DebitRule

DebitAuthorizations

DebitExpirationRule

  • expires_at_unix: number

DebitOperation

  • npub: string

DebitResponse

DebitRule

DecodeInvoiceRequest

  • invoice: string

DecodeInvoiceResponse

  • amount: number

Empty

EncryptionExchangeRequest

  • deviceId: string
  • publicKey: string

EnrollAdminTokenRequest

  • admin_token: string

FrequencyRule

  • amount: number
  • interval: IntervalType
  • number_of_intervals: number

GetAppUserLNURLInfoRequest

  • base_url_override: string
  • user_identifier: string

GetAppUserRequest

  • user_identifier: string

GetInviteTokenStateRequest

  • invite_token: string

GetInviteTokenStateResponse

  • used: boolean

GetNPubLinking

  • user_identifier: string

GetPaymentStateRequest

  • invoice: string

GetProductBuyLinkResponse

  • link: string

GetUserOperationsRequest

  • latestIncomingInvoice: number
  • latestIncomingTx: number
  • latestIncomingUserToUserPayment: number
  • latestOutgoingInvoice: number
  • latestOutgoingTx: number
  • latestOutgoingUserToUserPayment: number
  • max_size: number

GetUserOperationsResponse

GraphPoint

  • x: number
  • y: number

HandleLnurlPayResponse

  • pr: string
  • routes: ARRAY of: Empty

HttpCreds

  • token: string
  • url: string

LinkNPubThroughTokenRequest

  • token: string

LiveDebitRequest

LiveUserOperation

LndChannels

LndGetInfoRequest

  • nodeId: number

LndGetInfoResponse

  • alias: string

LndMetrics

LndMetricsRequest

  • from_unix: number *this field is optional
  • to_unix: number *this field is optional

LndNodeMetrics

  • chain_balance: ARRAY of: GraphPoint
  • channel_balance: ARRAY of: GraphPoint
  • closed_channels: ARRAY of: ClosedChannel
  • closing_channels: number
  • external_balance: ARRAY of: GraphPoint
  • forwarding_events: number
  • forwarding_fees: number
  • offline_channels: number
  • online_channels: number
  • open_channels: ARRAY of: OpenChannel
  • pending_channels: number

LndSeed

  • seed: ARRAY of: string

LnurlLinkResponse

  • k1: string
  • lnurl: string

LnurlPayInfoResponse

  • allowsNostr: boolean
  • callback: string
  • maxSendable: number
  • metadata: string
  • minSendable: number
  • nostrPubkey: string
  • tag: string

LnurlWithdrawInfoResponse

  • balanceCheck: string
  • callback: string
  • defaultDescription: string
  • k1: string
  • maxWithdrawable: number
  • minWithdrawable: number
  • payLink: string
  • tag: string

MigrationUpdate

NPubLinking

NewAddressRequest

NewAddressResponse

  • address: string

NewInvoiceRequest

  • amountSats: number
  • memo: string
  • zap: string *this field is optional

NewInvoiceResponse

  • invoice: string

OpenChannel

  • active: boolean
  • capacity: number
  • channel_id: string
  • label: string
  • lifetime: number
  • local_balance: number
  • remote_balance: number

OpenChannelRequest

  • closeAddress: string
  • destination: string
  • fundingAmount: number
  • pushAmount: number

OpenChannelResponse

  • channelId: string

PayAddressRequest

  • address: string
  • amoutSats: number
  • satsPerVByte: number

PayAddressResponse

  • network_fee: number
  • operation_id: string
  • service_fee: number
  • txId: string

PayAppUserInvoiceRequest

  • amount: number
  • debit_npub: string *this field is optional
  • invoice: string
  • user_identifier: string

PayInvoiceRequest

  • amount: number
  • debit_npub: string *this field is optional
  • invoice: string

PayInvoiceResponse

  • amount_paid: number
  • network_fee: number
  • operation_id: string
  • preimage: string
  • service_fee: number

PaymentState

  • amount: number
  • network_fee: number
  • paid_at_unix: number
  • service_fee: number

Product

  • id: string
  • name: string
  • noffer: string
  • price_sats: number

RelaysMigration

  • relays: ARRAY of: string

RequestNPubLinkingTokenRequest

  • user_identifier: string

RequestNPubLinkingTokenResponse

  • token: string

RoutingEvent

  • event_type: string
  • failure_string: string
  • forward_fail_event: boolean
  • incoming_amt_msat: number
  • incoming_channel_id: number
  • incoming_htlc_id: number
  • offchain: boolean
  • outgoing_amt_msat: number
  • outgoing_channel_id: number
  • outgoing_htlc_id: number
  • settled: boolean
  • timestamp_ns: number

SendAppUserToAppPaymentRequest

  • amount: number
  • from_user_identifier: string

SendAppUserToAppUserPaymentRequest

  • amount: number
  • from_user_identifier: string
  • to_user_identifier: string

SetMockAppBalanceRequest

  • amount: number

SetMockAppUserBalanceRequest

  • amount: number
  • user_identifier: string

SetMockInvoiceAsPaidRequest

  • amount: number
  • invoice: string

UsageMetric

  • auth_in_nano: number
  • batch: boolean
  • batch_size: number
  • handle_in_nano: number
  • nostr: boolean
  • parsed_in_nano: number
  • processed_at_ms: number
  • rpc_name: string
  • validate_in_nano: number

UsageMetrics

UseInviteLinkRequest

  • invite_token: string

UserInfo

  • balance: number
  • bridge_url: string
  • callback_url: string
  • max_withdrawable: number
  • ndebit: string
  • network_max_fee_bps: number
  • network_max_fee_fixed: number
  • noffer: string
  • service_fee_bps: number
  • userId: string
  • user_identifier: string

UserOperation

  • amount: number
  • confirmed: boolean
  • identifier: string
  • inbound: boolean
  • internal: boolean
  • network_fee: number
  • operationId: string
  • paidAtUnix: number
  • service_fee: number
  • tx_hash: string
  • type: UserOperationType

UserOperations

  • fromIndex: number
  • operations: ARRAY of: UserOperation
  • toIndex: number

UsersInfo

  • always_been_inactive: number
  • balance_avg: number
  • balance_median: number
  • negative_balance: number
  • no_balance: number
  • total: number

Enums

The enumerators used in the messages

AddressType

  • NESTED_PUBKEY_HASH
  • TAPROOT_PUBKEY
  • WITNESS_PUBKEY_HASH

IntervalType

  • DAY
  • MONTH
  • WEEK

UserOperationType

  • INCOMING_INVOICE
  • INCOMING_TX
  • INCOMING_USER_TO_USER
  • OUTGOING_INVOICE
  • OUTGOING_TX
  • OUTGOING_USER_TO_USER