{ "swagger": "2.0", "info": { "title": "priceoraclerpc/price_oracle.proto", "version": "version not set" }, "tags": [ { "name": "PriceOracle" } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "paths": { "/v1/taproot-assets/rfq/priceoracle/assetrates": { "get": { "summary": "QueryAssetRates retrieves the exchange rate between a tap asset and BTC for\na specified transaction type, subject asset, and payment asset. The asset\nrate represents the number of tap asset units per BTC.", "operationId": "PriceOracle_QueryAssetRates", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/priceoraclerpcQueryAssetRatesResponse" } }, "default": { "description": "An unexpected error response.", "schema": { "$ref": "#/definitions/rpcStatus" } } }, "parameters": [ { "name": "transaction_type", "description": "transaction_type indicates whether the transaction is a purchase or a\nsale.\n\n - PURCHASE: PURCHASE indicates a purchase transaction.\n - SALE: SALE indicates a sale transaction.", "in": "query", "required": false, "type": "string", "enum": [ "PURCHASE", "SALE" ], "default": "PURCHASE" }, { "name": "subject_asset.asset_id", "description": "The 32-byte asset ID specified as raw bytes (gRPC only).", "in": "query", "required": false, "type": "string", "format": "byte" }, { "name": "subject_asset.asset_id_str", "description": "The 32-byte asset ID encoded as a hex string (use this for REST).", "in": "query", "required": false, "type": "string" }, { "name": "subject_asset.group_key", "description": "The 32-byte asset group key specified as raw bytes (gRPC only).", "in": "query", "required": false, "type": "string", "format": "byte" }, { "name": "subject_asset.group_key_str", "description": "The 32-byte asset group key encoded as hex string (use this for\nREST).", "in": "query", "required": false, "type": "string" }, { "name": "subject_asset_max_amount", "description": "subject_asset_max_amount is the maximum amount of the subject asset that\ncould be involved in the transaction.", "in": "query", "required": false, "type": "string", "format": "uint64" }, { "name": "payment_asset.asset_id", "description": "The 32-byte asset ID specified as raw bytes (gRPC only).", "in": "query", "required": false, "type": "string", "format": "byte" }, { "name": "payment_asset.asset_id_str", "description": "The 32-byte asset ID encoded as a hex string (use this for REST).", "in": "query", "required": false, "type": "string" }, { "name": "payment_asset.group_key", "description": "The 32-byte asset group key specified as raw bytes (gRPC only).", "in": "query", "required": false, "type": "string", "format": "byte" }, { "name": "payment_asset.group_key_str", "description": "The 32-byte asset group key encoded as hex string (use this for\nREST).", "in": "query", "required": false, "type": "string" }, { "name": "payment_asset_max_amount", "description": "payment_asset_max_amount is the maximum amount of the payment asset that\ncould be involved in the transaction. This field is optional. If set to\nzero, it is considered unset.", "in": "query", "required": false, "type": "string", "format": "uint64" }, { "name": "asset_rates_hint.subjectAssetRate.coefficient", "description": "The coefficient is the fractional value scaled-up as an integer. This\ninteger is represented as a string as it may be too large to fit in a\nuint64.", "in": "query", "required": false, "type": "string" }, { "name": "asset_rates_hint.subjectAssetRate.scale", "description": "The scale is the component that determines how many decimal places\nthe coefficient should be divided by to obtain the fractional value.", "in": "query", "required": false, "type": "integer", "format": "int64" }, { "name": "asset_rates_hint.paymentAssetRate.coefficient", "description": "The coefficient is the fractional value scaled-up as an integer. This\ninteger is represented as a string as it may be too large to fit in a\nuint64.", "in": "query", "required": false, "type": "string" }, { "name": "asset_rates_hint.paymentAssetRate.scale", "description": "The scale is the component that determines how many decimal places\nthe coefficient should be divided by to obtain the fractional value.", "in": "query", "required": false, "type": "integer", "format": "int64" }, { "name": "asset_rates_hint.expiry_timestamp", "description": "expiry_timestamp is the Unix timestamp in seconds after which the asset\nrates are no longer valid.", "in": "query", "required": false, "type": "string", "format": "uint64" }, { "name": "intent", "description": "intent informs the price oracle about the stage of the payment flow that\nlead to the price rate query. This is used to provide context for the\nasset rates being requested, allowing the price oracle to tailor the\nresponse based on the specific use case, such as paying an invoice or\nreceiving a payment and the different stages involved in those. This\nfield will only be set by tapd v0.7.0 and later.\n\n - INTENT_UNSPECIFIED: INTENT_UNSPECIFIED is used to indicate that the intent of the price rate\nquery is not specified. This is the fallback default value and should not\nbe used in production code. It is primarily used for backward\ncompatibility with older versions of the protocol that did not include\nintent information.\n - INTENT_PAY_INVOICE_HINT: INTENT_PAY_INVOICE_HINT is used to indicate that the user is requesting\na price rate hint for paying an invoice. This is typically used by the\npayer of an invoice to provide a suggestion of the expected asset rate to\nthe RFQ peer (edge node) that will determine the actual rate for the\npayment.\n - INTENT_PAY_INVOICE: INTENT_PAY_INVOICE is used to indicate that a peer wants to pay an\ninvoice with assets. This is typically used by the edge node that\nfacilitates the swap from assets to BTC for the payer of an invoice. This\nintent is used to provide the actual asset rate for the payment, which\nmay differ from the hint provided by the payer.\n - INTENT_PAY_INVOICE_QUALIFY: INTENT_PAY_INVOICE_QUALIFY is used to indicate that the payer of an\ninvoice has received an asset rate from their RFQ peer (edge node) and is\nqualifying the rate for the payment. This is typically used by the payer\nof an invoice to ensure that the asset rate provided by their peer (edge\nnode) is acceptable before proceeding with the payment.\n - INTENT_RECV_PAYMENT_HINT: INTENT_RECV_PAYMENT_HINT is used to indicate that the user is requesting\na price rate hint for receiving a payment through an invoice. This is\ntypically used by the creator of an invoice to provide a suggestion of\nthe expected asset rate to the RFQ peer (edge node) that will determine\nthe actual rate used for creating an invoice.\n - INTENT_RECV_PAYMENT: INTENT_RECV_PAYMENT is used to indicate that a peer wants to create an\ninvoice to receive a payment with assets. This is typically used by the\nedge node that facilitates the swap from BTC to assets for the receiver\nof a payment. This intent is used to provide the actual asset rate for\nthe invoice creation, which may differ from the hint provided by the\nreceiver.\n - INTENT_RECV_PAYMENT_QUALIFY: INTENT_RECV_PAYMENT_QUALIFY is used to indicate that the creator of an\ninvoice received an asset rate from their RFQ peer (edge node) and is\nqualifying the rate for the creation of the invoice. This is typically\nused by the creator of an invoice to ensure that the asset rate provided\nby their peer (edge node) is acceptable before proceeding with creating\nthe invoice.", "in": "query", "required": false, "type": "string", "enum": [ "INTENT_UNSPECIFIED", "INTENT_PAY_INVOICE_HINT", "INTENT_PAY_INVOICE", "INTENT_PAY_INVOICE_QUALIFY", "INTENT_RECV_PAYMENT_HINT", "INTENT_RECV_PAYMENT", "INTENT_RECV_PAYMENT_QUALIFY" ], "default": "INTENT_UNSPECIFIED" }, { "name": "counterparty_id", "description": "counterparty_id is the 33-byte public key of the peer that is on the\nopposite side of the transaction. This field will only be set by tapd\nv0.7.0 and later and only if the user initiating the transaction (sending\na payment or creating an invoice) opted in to sharing their peer ID with\nthe price oracle.", "in": "query", "required": false, "type": "string", "format": "byte" }, { "name": "metadata", "description": "metadata is an optional text field that can be used to provide\nadditional metadata about the transaction to the price oracle. This can\ninclude information about the wallet end user that initiated the\ntransaction, or any authentication information that the price oracle\ncan use to give out a more accurate (or discount) asset rate. Though not\nverified or enforced by tapd, the suggested format for this field is a\nJSON string. This field is optional and can be left empty if no metadata\nis available. The maximum length of this field is 32'768 bytes. This\nfield will only be set by tapd v0.7.0 and later.", "in": "query", "required": false, "type": "string" } ], "tags": [ "PriceOracle" ] } } }, "definitions": { "priceoraclerpcAssetRates": { "type": "object", "properties": { "subjectAssetRate": { "$ref": "#/definitions/priceoraclerpcFixedPoint", "description": "subjectAssetRate is the number of subject asset units per BTC represented\nas a fixed-point number. This field is also commonly referred to as the\nsubject asset to BTC (conversion) rate. When the subject asset is BTC,\nthis field should be set to 100 billion, as one BTC is equivalent to 100\nbillion msats." }, "paymentAssetRate": { "$ref": "#/definitions/priceoraclerpcFixedPoint", "description": "paymentAssetRate is the number of payment asset units per BTC represented\nas a fixed-point number. This field is also commonly referred to as the\npayment asset to BTC (conversion) rate. When the payment asset is BTC,\nthis field should be set to 100 billion, as one BTC is equivalent to 100\nbillion msats." }, "expiry_timestamp": { "type": "string", "format": "uint64", "description": "expiry_timestamp is the Unix timestamp in seconds after which the asset\nrates are no longer valid." } }, "description": "AssetRates represents the exchange rates for subject and payment assets\nrelative to BTC, expressed as fixed-point numbers. It includes the rates\nfor both assets and an expiration timestamp indicating when the rates\nare no longer valid." }, "priceoraclerpcAssetSpecifier": { "type": "object", "properties": { "asset_id": { "type": "string", "format": "byte", "description": "The 32-byte asset ID specified as raw bytes (gRPC only)." }, "asset_id_str": { "type": "string", "description": "The 32-byte asset ID encoded as a hex string (use this for REST)." }, "group_key": { "type": "string", "format": "byte", "description": "The 32-byte asset group key specified as raw bytes (gRPC only)." }, "group_key_str": { "type": "string", "description": "The 32-byte asset group key encoded as hex string (use this for\nREST)." } }, "description": "AssetSpecifier is a union type for specifying an asset by either its asset ID\nor group key." }, "priceoraclerpcFixedPoint": { "type": "object", "properties": { "coefficient": { "type": "string", "description": "The coefficient is the fractional value scaled-up as an integer. This\ninteger is represented as a string as it may be too large to fit in a\nuint64." }, "scale": { "type": "integer", "format": "int64", "description": "The scale is the component that determines how many decimal places\nthe coefficient should be divided by to obtain the fractional value." } }, "description": "FixedPoint is a scaled integer representation of a fractional number.\n\nThis type consists of two integer fields: a coefficient and a scale.\nUsing this format enables precise and consistent representation of fractional\nnumbers while avoiding floating-point data types, which are prone to\nprecision errors.\n\nThe relationship between the fractional representation and its fixed-point\nrepresentation is expressed as:\n```\nV = F_c / (10^F_s)\n```\nwhere:\n\n* `V` is the fractional value.\n\n* `F_c` is the coefficient component of the fixed-point representation. It is\n the scaled-up fractional value represented as an integer.\n\n* `F_s` is the scale component. It is an integer specifying how\n many decimal places `F_c` should be divided by to obtain the fractional\n representation." }, "priceoraclerpcIntent": { "type": "string", "enum": [ "INTENT_UNSPECIFIED", "INTENT_PAY_INVOICE_HINT", "INTENT_PAY_INVOICE", "INTENT_PAY_INVOICE_QUALIFY", "INTENT_RECV_PAYMENT_HINT", "INTENT_RECV_PAYMENT", "INTENT_RECV_PAYMENT_QUALIFY" ], "default": "INTENT_UNSPECIFIED", "description": "Intent is an enum informing the price oracle about the intent of the price\nrate query. This is used to provide context for the asset rates being\nrequested, allowing the price oracle to tailor the response based on the\nspecific use case, such as paying an invoice or receiving a payment and the\ndifferent stages involved in those.\n\n - INTENT_UNSPECIFIED: INTENT_UNSPECIFIED is used to indicate that the intent of the price rate\nquery is not specified. This is the fallback default value and should not\nbe used in production code. It is primarily used for backward\ncompatibility with older versions of the protocol that did not include\nintent information.\n - INTENT_PAY_INVOICE_HINT: INTENT_PAY_INVOICE_HINT is used to indicate that the user is requesting\na price rate hint for paying an invoice. This is typically used by the\npayer of an invoice to provide a suggestion of the expected asset rate to\nthe RFQ peer (edge node) that will determine the actual rate for the\npayment.\n - INTENT_PAY_INVOICE: INTENT_PAY_INVOICE is used to indicate that a peer wants to pay an\ninvoice with assets. This is typically used by the edge node that\nfacilitates the swap from assets to BTC for the payer of an invoice. This\nintent is used to provide the actual asset rate for the payment, which\nmay differ from the hint provided by the payer.\n - INTENT_PAY_INVOICE_QUALIFY: INTENT_PAY_INVOICE_QUALIFY is used to indicate that the payer of an\ninvoice has received an asset rate from their RFQ peer (edge node) and is\nqualifying the rate for the payment. This is typically used by the payer\nof an invoice to ensure that the asset rate provided by their peer (edge\nnode) is acceptable before proceeding with the payment.\n - INTENT_RECV_PAYMENT_HINT: INTENT_RECV_PAYMENT_HINT is used to indicate that the user is requesting\na price rate hint for receiving a payment through an invoice. This is\ntypically used by the creator of an invoice to provide a suggestion of\nthe expected asset rate to the RFQ peer (edge node) that will determine\nthe actual rate used for creating an invoice.\n - INTENT_RECV_PAYMENT: INTENT_RECV_PAYMENT is used to indicate that a peer wants to create an\ninvoice to receive a payment with assets. This is typically used by the\nedge node that facilitates the swap from BTC to assets for the receiver\nof a payment. This intent is used to provide the actual asset rate for\nthe invoice creation, which may differ from the hint provided by the\nreceiver.\n - INTENT_RECV_PAYMENT_QUALIFY: INTENT_RECV_PAYMENT_QUALIFY is used to indicate that the creator of an\ninvoice received an asset rate from their RFQ peer (edge node) and is\nqualifying the rate for the creation of the invoice. This is typically\nused by the creator of an invoice to ensure that the asset rate provided\nby their peer (edge node) is acceptable before proceeding with creating\nthe invoice." }, "priceoraclerpcQueryAssetRatesErrResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "error is the error message." }, "code": { "type": "integer", "format": "int64", "description": "code is the error code." } }, "description": "QueryAssetRatesErrResponse is the error response to a QueryAssetRates call." }, "priceoraclerpcQueryAssetRatesOkResponse": { "type": "object", "properties": { "asset_rates": { "$ref": "#/definitions/priceoraclerpcAssetRates", "description": "asset_rates is the asset exchange rates for the transaction." } }, "description": "QueryAssetRatesOkResponse is the successful response to a\nQueryAssetRates call." }, "priceoraclerpcQueryAssetRatesResponse": { "type": "object", "properties": { "ok": { "$ref": "#/definitions/priceoraclerpcQueryAssetRatesOkResponse", "description": "ok is the successful response to the query." }, "error": { "$ref": "#/definitions/priceoraclerpcQueryAssetRatesErrResponse", "description": "error is the error response to the query." } }, "description": "QueryAssetRatesResponse is the response from a QueryAssetRates RPC call." }, "priceoraclerpcTransactionType": { "type": "string", "enum": [ "PURCHASE", "SALE" ], "default": "PURCHASE", "description": "TransactionType is an enum representing the type of transaction.\n\n - PURCHASE: PURCHASE indicates a purchase transaction.\n - SALE: SALE indicates a sale transaction." }, "protobufAny": { "type": "object", "properties": { "@type": { "type": "string" } }, "additionalProperties": {} }, "rpcStatus": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/protobufAny" } } } } } }