{"openapi":"3.1.0","info":{"title":"Slipstream Beta API","description":"This is a beta version of API for submitting Bitcoin transactions via Slipstream.<br>\n        If you plan to execute a large volume of transactions and are interested in volume discounting packages, please contact [foundation@mara.com](mailto:foundation@mara.com).<br><br>Slipstreams minimum fee rate is the higher of either 1x the current mempool priority fee rate or 1 sats/vByte.<br><br>Full RBF (Replace-by-Fee) and CPFP (Child-Pays-for-Parent) supported.","license":{"name":"Apache 2.0","url":"https://www.apache.org/licenses/LICENSE-2.0.html"},"version":"0.1.0-beta"},"paths":{"/api/system":{"get":{"tags":["slipstream"],"summary":"Get System Info","description":"Returns general information about the Slipstream API, including version, chain name, block height, and fee rate floor.","operationId":"get_info","responses":{"200":{"description":"success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InfoResponse"}}}}}}},"/api/block-info":{"get":{"tags":["slipstream"],"summary":"Get Block Info","description":"Returns structured blockchain status info.","operationId":"get_block_info","responses":{"200":{"description":"success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockInfo"}}}}}}},"/api/rates":{"get":{"tags":["slipstream"],"summary":"Get effective fee rate info","description":"Returns the effective fee rate information for the requested client code, if provided.","operationId":"get_rate","parameters":[{"name":"client_code","in":"query","description":"Filter by client code","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateInfoSuccessResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"is_success":false,"message":"Requested client code is invalid"}}}}}}},"/api/transactions/status":{"get":{"tags":["slipstream"],"summary":"Retrieves detailed information about a transaction using its transaction ID","description":"Returns the transaction's confirmation status, fee, and position in the mempool or block.","operationId":"status_check","parameters":[{"name":"tx_id","in":"query","description":"Enter transaction ID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionInfo"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"is_success":false,"message":"Requested transaction is invalid"}}}}}}},"/api/transactions":{"post":{"tags":["slipstream"],"summary":"Submits a Bitcoin transactions.","description":"Submits a single Bitcoin transaction hex for validation and mempool submission.","operationId":"submit_tx","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TxSubmitRequest"},"example":{"client_code":"<Optional code to identify the user>","tx_hex":"<raw_transaction_hex_string>"}}},"required":true},"responses":{"200":{"description":"Transaction submitted successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TxSubmitResponse"},"example":{"message":"<txid>","status":"success"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TxSubmitResponse"},"example":{"message":"<tx submission errors>","status":"error"}}}}}}},"/api/transactions/packages":{"post":{"tags":["slipstream"],"summary":"Submits a batch of Bitcoin transactions.","description":"Submits a batch of Bitcoin transactions as a package. Each transaction is automatically checked for fee rate thresholds and sanctions compliance.\n\n✅ **Working Example:**\n\n*submitpackage [\"<parent1_hex>\",............, \"<parentN_hex>\", \"<child_hex>\"]*\n\n- The **child_hex** transaction spends outputs from all listed **parent** transactions.\n- The **parent1** through **parentN** transactions are independent of each other.\n- The **order of transactions** is important: parents must come before the child.\n\n- Each package must include **at least 2** and **no more than 25** transactions.\n\n⚠️ **Note:**\n\nWhen using the **submitpackage** RPC, provide the transaction hexes starting with the parents followed by the child transaction.","operationId":"submit_package","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageSubmitRequest"},"example":{"client_code":"<Optional code to identify the user>","tx_hexes":["<hex1>","<hex2>","..."]}}},"required":true},"responses":{"200":{"description":"Package submitted successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageSubmitResponse"},"example":{"result":{"package_msg":"success","replaced-transactions":[],"tx-results":{"0f7ce620992f82e7916859664b51b46138e14b2f96bb4908bc9aeebe26627228":{"fees":{"base":0.0000389,"effective-feerate":0.00035363,"effective-includes":["0f7ce620992f82e7916859664b51b46138e14b2f96bb4908bc9aeebe26627228"]},"txid":"f0d29b7aa669faa92a36e1173f436c5843ea1dbf3427f982c93cef6a52aca0cf","vsize":110},"4cd895e64bb26a48c6cc630c8d0c2aee13a80b39e6b746daaf3deed013be70c7":{"fees":{"base":0,"effective-feerate":0,"effective-includes":["4cd895e64bb26a48c6cc630c8d0c2aee13a80b39e6b746daaf3deed013be70c7"]},"txid":"25b888236160c2e0d696a5dca6878f9142110c6926fae9029febf89cf33140dc","vsize":110}}},"status":"success"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageSubmitResponse"},"example":{"error":"<package submission errors>","status":"error"}}}}}}},"/api/mempool/tests":{"post":{"tags":["slipstream"],"summary":"Checks if the transaction violates the consensus or policy rules","description":"Returns result of mempool acceptance tests indicating if raw transaction (serialized, hex-encoded) would be accepted by mempool.","operationId":"test_mempool_accept","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestMempoolAcceptRequest"},"example":{"tx_hexes":["<hex1>","<hex2>","..."]}}},"required":true},"responses":{"200":{"description":"success","content":{"application/json":{"schema":{"type":"array","items":{}}}}}}}}},"components":{"schemas":{"BlockInfo":{"type":"object","description":"Block info model","required":["block_height","fee_rate","submit_fee_rate","network"],"properties":{"block_height":{"type":"integer","format":"int64","description":"The current height of the latest block in the blockchain.","example":834128,"minimum":0},"fee_rate":{"type":"number","format":"double","description":"The fee rate at which a typical slipstream transaction would currently be mined. In sats/vbyte.","example":4},"submit_fee_rate":{"type":"number","format":"double","description":"The minimum fee to submit into the `Slipstream` mempool. Admission into the mempool does not guarantee a transaction will ever be mined. Submitted slipstream transactions are mined on a best-effort basis.  Denominated in sat/vByte.","example":2},"network":{"type":"string","description":"The name of the blockchain network.","example":"main"}}},"ErrorResponse":{"type":"object","description":"Rate info error model","required":["is_success","message"],"properties":{"is_success":{"type":"boolean","description":"Indicates whether the operation was successful."},"message":{"type":"string","description":"A descriptive error message explaining the failure or issue."}}},"InfoResponse":{"type":"object","description":"Info model","required":["name","version","chain","block_height","slipstream_fee_rate_floor","features"],"properties":{"name":{"type":"string","description":"The name of the API or service.","example":"Marathon Slipstream API"},"version":{"type":"string","description":"The current version of the API or service.","example":"0.41"},"chain":{"type":"string","description":"The name of the blockchain network.","example":"main"},"block_height":{"type":"integer","format":"int64","description":"The current height of the latest block in the blockchain.","example":834128,"minimum":0},"slipstream_fee_rate_floor":{"type":"number","format":"double","description":"The fee rate at which a typical slipstream transaction would currently be mined. In sats/vbyte.","example":14.2},"features":{"type":"array","items":{"type":"string"},"description":"A list of features currently supported by the API.","example":["Private mempool submission","Direct mempool submission","Real-time block height updates","Dynamic fee rate calculation"]}}},"PackageSubmitRequest":{"type":"object","description":"Package submit request model","required":["tx_hexes"],"properties":{"tx_hexes":{"type":"array","items":{"type":"string"},"description":"List of transaction hexes: `[parent1, parent2, child]` that needs to be submitted to our private mempool."},"client_code":{"type":["string","null"],"description":"An optional client-specific code used to apply a reduced fee rate threshold."},"skip_mempool_submission":{"type":["boolean","null"],"description":"The transaction will be submitted only to the database, not to the mempool. However, mempool validation checks will still be performed before storing the transaction."}}},"PackageSubmitResponse":{"type":"object","description":"Package submit response model","required":["status"],"properties":{"status":{"type":"string","description":"Typically a string indicating whether the submission was successful, such as \"success\" or \"error\"."},"result":{"description":"This field contains additional details or the output of the submission, and is optional."},"error":{"type":["string","null"],"description":"This field is optional and contains a string describing the error that occurred during the submission process."}}},"Position":{"type":"object","required":["block"],"properties":{"block":{"type":"integer","format":"int32","description":"Position of the block where the transaction currently in the mempool.","example":0}}},"RateInfoSuccessResponse":{"type":"object","description":"Rate info success model","required":["market_rate","multiplier","multiplier_discount_percent","discounted_multiplier","submit_fee_rate","slipstream_rate","effective_rate"],"properties":{"market_rate":{"type":"number","format":"double","description":"The current projected Bitcoin fee rate to be mined in a block by the standard P2P Bitcoin network — not including `Slipstream` fee premium; denominated in sat/vByte.","example":1},"multiplier":{"type":"number","format":"double","description":"The multiplier represents the `Slipstream` premium markup; applied to the market rate to determine the `slipstream_rate`.","example":2},"multiplier_discount_percent":{"type":"integer","format":"int32","description":"If applicable, the discount applied to the portion of the multiplier greater than 1 (the premium portion).\n\nNote: Discounts are available for those processing large transaction volume. If you are a regular user of `Slipstream` or plan on processing a large volume of transactions, contact foundation@mara.com for more information about our discount codes.","example":10},"discounted_multiplier":{"type":"number","format":"double","description":"The `discounted_multiplier` is calculated as the product of the premium portion of the `multiplier` and `multiplier_discount_percent` (if applicable).It represents the discounted `Slipstream` premium markup.\n\n`discounted_multiplier` = ((`multiplier` - 1) * (1 - (`multiplier_discount_percent` / 100.0)) + 1)\n\nNote: Even if discounted 100%, you will still have to pay market rate as the discount only applies to the slipstream premium markup.","example":1.9},"submit_fee_rate":{"type":"number","format":"double","description":"The minimum fee to submit into the `Slipstream` mempool. Admission into the mempool does not guarantee a transaction will ever be mined. Submitted slipstream transactions are mined on a best-effort basis.  Denominated in sat/vByte. See `effective_rate`.\n\n`submit_fee_rate` = 1.0 * `discounted_multiplier`","example":1.9},"slipstream_rate":{"type":"number","format":"double","description":"The fee rate at which a typical slipstream transaction would currently be mined; denominated in sat/vByte.\n\n`slipstream_rate` = `market_rate` * `multiplier`","example":2},"effective_rate":{"type":"number","format":"double","description":"The rate at which a typical slipstream transaction would currently be mined.  This includes all premiums and discounts if `client_code` is supplied.\n\n`effective_rate` = `market_rate` * `discounted_multiplier`\n\nIn order to be mined, the non-premium portion of `Slipstream` transaction fees must outbid any other p2p relayed transactions.\n\nExample:  `market_rate` is currently 1 sat/vByte, `multiplier` is 2 and user has a discount of 10%\n\n1. `effective_rate` for slipstream transaction is 1.9 sat/vByte\n\n2. transaction is competing against standard P2P transactions at a rate of 1 sat/vByte for blockspace.\n\nNote: If your transaction is not paying enough fees to be mined, you may always use Replace by Fee (RBF) to pay more fees and increase the chances of it being mined.","example":1.9}}},"Status":{"type":"object","required":["confirmed"],"properties":{"confirmed":{"type":"boolean","description":"This indicates that the transaction has been confirmed or not on the blockchain.","example":true},"block_height":{"type":["integer","null"],"format":"int64","description":"The height of the block in which this transaction was confirmed.","example":101469},"block_time":{"type":["integer","null"],"format":"int64","description":"The timestamp of when the block was added to the blockchain, in Unix time format.","example":1757484672},"block_hash":{"type":["string","null"],"description":"The hash of the block containing this transaction.","example":"000000000000000076a1c227e544ad11bd88a539212de03d8d498be8399149e9"}}},"TestMempoolAcceptRequest":{"type":"object","description":"Test Mempool Accept request model","required":["tx_hexes"],"properties":{"tx_hexes":{"type":"array","items":{"type":"string"},"description":"List of transaction hexes: `[hex1, hex2, hex3]` that needs to be submitted to our private mempool."}}},"TransactionInfo":{"type":"object","description":"Transaction info model","required":["message","market_rate","functional_rate","last_24h_odds","last_7d_odds","is_next_block","transaction"],"properties":{"message":{"type":"string","description":"Returns the status of the transaction.","example":"Transaction confirmed in block 101469"},"market_rate":{"type":"number","format":"double","description":"The current projected Bitcoin fee rate to be mined in a block by the standard P2P Bitcoin network — not including `Slipstream` fee premium; denominated in sat/vByte.","example":1},"functional_rate":{"type":"number","format":"double","description":"The rate at which a `Slipstream` transaction compete against standard P2P transactions for blockspace; denominated in sat/vByte.","example":1.52},"last_24h_odds":{"type":"string","description":"Odds of inclusion in percentage at which a Slipstream transaction compete against standard P2P transactions for blockspace for last 24 hours.","example":2.65},"last_7d_odds":{"type":"string","description":"Odds of inclusion in percentage at which a `Slipstream` transaction compete against standard P2P transactions for blockspace for last 7 days.","example":4.05},"is_next_block":{"type":"boolean","description":"Is the transaction to mine in next block ?","example":true},"transaction":{"$ref":"#/components/schemas/TxInfo"},"submission_type":{"type":["string","null"],"description":"`tx_submission` or `package_submission` when known."},"package_txids":{"type":["array","null"],"items":{"type":"string"},"description":"All transaction IDs in the package when `submission_type` is `package_submission`."}}},"TxInfo":{"type":"object","description":"TX info response model","required":["txid","size","weight","fee","vsize","status"],"properties":{"txid":{"type":"string","description":"This is the transaction ID (a unique identifier for the transaction).","example":"9fa1c54aaccad96b6c36ff975045dfc3fbe1498e0ee03b5fdceaa684f9485b0b"},"size":{"type":"integer","format":"int64","description":"The total size of the transaction in bytes.","example":239},"weight":{"type":"integer","format":"int64","description":"The transaction's weight (between vsize*4-3 and vsize*4)","example":752},"fee":{"type":"integer","format":"int64","description":"The transaction fee paid for this transaction in sats.","example":18900},"vsize":{"type":"integer","format":"int64","description":"The virtual transaction size (differs from size for witness transactions)","example":188},"status":{"$ref":"#/components/schemas/Status"},"firstSeen":{"type":["integer","null"],"format":"int64","description":"The Unix timestamp when this transaction was first seen in the mempool.","example":1757484672},"position":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/Position"}]}}},"TxSubmitRequest":{"type":"object","description":"Transaction submit request model","required":["tx_hex"],"properties":{"tx_hex":{"type":"string","description":"This is the transaction hex that needs to be submitted to our private mempool."},"client_code":{"type":["string","null"],"description":"An optional client-specific code used to apply a reduced fee rate threshold."},"skip_mempool_submission":{"type":["boolean","null"],"description":"The transaction will be submitted only to the database, not to the mempool. However, mempool validation checks will still be performed before storing the transaction."}}},"TxSubmitResponse":{"type":"object","description":"Transaction submit response model","required":["status","message"],"properties":{"status":{"type":"string","description":"Typically a string indicating whether the submission was successful, such as \"success\" or \"error\"."},"message":{"type":"string","description":"This can include context on success or failure, such as transaction ID or error description."}}}}}}