# General Introduction for Baltex API **What is Baltex?**\ Baltex is a toolkit for crypto apps. It helps you move and trade tokens across different blockchains, do privacy-enhanced swaps, and route trades on decentralized exchanges (DEXs)—all from one place. **Who is it for?** * Wallets and super-apps that want smooth swaps and transfers * Exchanges and brokers adding cross-chain and private options * DeFi projects that need reliable routing and pricing **What you can do with Baltex:** * **Cross-Chain**: Move value from one blockchain to another, even switching tokens along the way. * **Private Swaps**: Swap with enhanced privacy options when that’s important to your users. * **DeFi (DEX) Routing**: Get competitive prices by routing across many DEXs and liquidity sources. **Why teams choose Baltex:** * **One integration, many features** * **Smart routing** to balance price, speed, and reliability * **Clear status tracking**, from start to finish * **Compliance-aware** features and controls * **User-first design**: simple flows your users understand # Operational Wallet Addresses This page lists the official operational wallet addresses used by Baltex across all supported networks. These addresses are used for internal treasury operations, fee collection, and on-chain settlements. **Baltex will never ask you to send funds directly to these addresses.** #### 🟡 Bitcoin (BTC) ``` bc1prnz0cxfrrzjzc9424dlhyfw0ukyx5zah4lg7jj7mv7vexgyea6wsfjfnd8 ``` > Mainnet operations on the Bitcoin network. #### 🔵 Litecoin (LTC) ``` ltc1qv44eklq2h58w5w2e7hsxxmds4wv95fxcf0kc9w ``` > Mainnet operations on the Litecoin network. #### 🔴 Tron (TRX) ``` TRaTQNfvbU8Un7imR4TKAfxb36MBZL2TGN ``` > Mainnet operations on the Tron network. #### 🔵 Ethereum (ETH) ``` 0x5caa2b55aa4ac56d4798ed70eaf35b9b58c32cf2 ``` > Mainnet operations on the Ethereum base layer. *** #### 🟣 Optimism (OP) ``` 0xc1b41cc2d2755c8d519d8ebd8c3dff826941ba1b ``` > Layer 2 operations on the Optimism network. *** #### 🟣 Polygon (MATIC) ``` 0x60c4ded2865d547665db4bb18e485e1b56535ede ``` > Operations on the Polygon PoS network. *** #### 🟡 BNB Chain (BSC) ``` 0x7e52b6f3b7bf4cfa7733ab7915716538371ddaa8 ``` > Operations on BNB Smart Chain (formerly Binance Smart Chain). *** #### 🔵 Base ``` 0x924edc142d3f170b99824cbb821719fbc898fa16 ``` > Layer 2 operations on Coinbase's Base network. *** #### 🔴 Avalanche C-Chain (AVAX-C) ``` 0xc6c92c77278f2eb059e6b3196af184cf4437e361 ``` > Operations on the Avalanche C-Chain (EVM-compatible layer). *** #### 🔵 Arbitrum ``` 0x716994056749711d4306c35e1266b5a92cacf8dc ``` > Layer 2 operations on the Arbitrum One network. #### 🔵 Solana ``` Gtyw72PaH7Ubz1jUNyyDDie6PMHnN5cz9d6v5A9cZzoA ``` > Operations on the Solana network. #### 🟡 Robinhood ``` 0x790ad59440103bd9129201882cf7c597b809c913 ``` > Operations on the Robinhood network. #### 🟡 Plasma ``` 0x1728997fd2e8ae92c4240337a677bc32082409c4 ``` > Operations on the Plasma network. *** ### Summary Table | Network | Chain ID | Address | | ----------------- | -------- | ---------------------------------------------------------------- | | Ethereum | 1 | `0x5caa2b55aa4ac56d4798ed70eaf35b9b58c32cf2` | | Optimism | 10 | `0xc1b41cc2d2755c8d519d8ebd8c3dff826941ba1b` | | BNB Chain | 56 | `0x7e52b6f3b7bf4cfa7733ab7915716538371ddaa8` | | Polygon | 137 | `0x60c4ded2865d547665db4bb18e485e1b56535ede` | | Arbitrum One | 42161 | `0x716994056749711d4306c35e1266b5a92cacf8dc` | | Avalanche C-Chain | 43114 | `0xc6c92c77278f2eb059e6b3196af184cf4437e361` | | Base | 8453 | `0x924edc142d3f170b99824cbb821719fbc898fa16` | | Bitcoin | | `bc1prnz0cxfrrzjzc9424dlhyfw0ukyx5zah4lg7jj7mv7vexgyea6wsfjfnd8` | | Tron | | `TRaTQNfvbU8Un7imR4TKAfxb36MBZL2TGN` | | Robinhood | | `0x790ad59440103bd9129201882cf7c597b809c913` | | Litecoin | | `ltc1qv44eklq2h58w5w2e7hsxxmds4wv95fxcf0kc9w` | | Plasma | | `0x1728997fd2e8ae92c4240337a677bc32082409c4` | | Solana | | `Gtyw72PaH7Ubz1jUNyyDDie6PMHnN5cz9d6v5A9cZzoA` | *** **If you believe an address listed here has been compromised or need to report suspicious activity, contact the compliance team immediately at ** # Cross-Chain API **What it is:**\ A fast, reliable way to move tokens across different blockchains. Think of it like a highway system that finds the best road (bridge + swap) for your trip. **Highlights:** * **Any-to-any routes** (where supported): Move from Chain A/Token X → Chain B/Token Y in one flow. * **Best path selection**: Baltex compares routes for **cost**, **speed**, and **success rate**. * **Transparent estimates**: See expected output and fees before you confirm. * **Status you can trust**: Track every step—sending, bridging, swapping, done. * **Gas help** (where available): Options to land with a bit of native gas on the destination chain. **Common use cases:** * Onboarding users to a new chain with the tokens they need * Moving treasury or liquidity between ecosystems * Powering cross-chain features in wallets and dApps **What users experience:** * Pick what they’re sending and where it’s going * See a clear preview (how much they’ll receive) * Confirm once; Baltex handles the complex parts * Watch progress and get a final confirmation **Why it’s different:** * Fewer hops, less headache * Built for real-world reliability (not just ideal scenarios) # Private Swaps API **What it is:**\ Privacy-enhanced token swaps. Designed for users and teams that want extra confidentiality in how trades are executed and settled. **Highlights:** * **Enhanced privacy options**: Select a privacy level that fits your users needs. * **Reduced traceability**: Helps minimize linkages between senders and receivers. * **Predictable previews**: See expected amounts and timing windows before confirming. * **Safety checks**: Guardrails and compliance-aware flows aligned with your operating region. **Common use cases:** * VIP or enterprise trading features * Privacy-first wallets and apps * Situations where discretion really matters **What users experience:** * Choose the tokens to swap and where to receive them * See a clear estimate of what they’ll get * Confirm once, then receive funds at the destination # DeFi API **What it is:**\ Smart routing for decentralized trades. Baltex searches across DEXs and liquidity sources to aim for great prices and dependable execution. **Highlights:** * **Best-price routing**: Finds competitive routes across multiple DEXs. * **Speed vs. price**: You can prioritize faster settlement or better pricing. * **Clear previews**: Know expected output and fees upfront. * **Reliable outcomes**: Built to reduce failed or stale trades in changing markets. **Common use cases:** * One-tap swaps in wallets * In-app trading for DeFi dashboards * Price-sensitive strategies that still value reliability **What users experience:** * Pick token in → token out * See a preview with expected output * Confirm and receive the result—no extra steps **Why it’s useful:** * Less time stitching together many DEXs * More consistent results for end users * Easy to explain and support # Cross Chain ## Available currencies > Returns a list of available currencies for Cross-Chain exchanges. ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"servers":[{"url":"https://api.baltex.io"}],"security":[{"Partner access key":[]}],"components":{"securitySchemes":{"Partner access key":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"Currency":{"type":"object","properties":{"ticker":{"type":"string","description":"Currency ticker (e.g., btc)"},"network":{"type":"string","description":"Network ticker (e.g., btc, eth)"},"symbol":{"type":"string","description":"Symbol representing the currency"},"name":{"type":"string","description":"Full name of the currency"},"hasMemo":{"type":"boolean","description":"Indicates whether this currency supports memo/extraId"},"requireMemo":{"type":"boolean","description":"Indicates whether memo/extraId is required to complete transactions"},"isFiat":{"type":"boolean","description":"Shows if the currency is fiat (e.g., USD)"},"isStable":{"type":"boolean","description":"Indicates if the currency is a stablecoin"},"supportsFixedRate":{"type":"boolean","description":"True if fixed-rate exchanges are supported"},"enabled":{"type":"boolean","description":"Indicates if currency is currently available for use"},"image":{"type":"string","description":"URL to the currency icon"},"regexAddress":{"type":"string","description":"Regular expression pattern for validating recipient addresses"},"addressExplorer":{"type":"string","description":"Block explorer URL template for addresses (use {} as placeholder)"},"txExplorer":{"type":"string","description":"Block explorer URL template for transactions (use {} as placeholder)"},"confirmations":{"type":"integer","description":"Number of required confirmations for incoming transactions"},"rank":{"type":"integer","description":"Currency ranking priority (use for sorting in UI)"}}}},"responses":{"UnauthorizedError":{"description":"Unauthorized — missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"statusCode":{"type":"integer"}}}}}}}},"paths":{"/v1/cross-chain/available-currencies":{"get":{"description":"Returns a list of available currencies for Cross-Chain exchanges.","operationId":"CexController_getAvailableCurrenciesList_v1","parameters":[],"responses":{"200":{"description":"List of available currencies for cross-chain exchanges","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Currency"}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}},"summary":"Available currencies","tags":["Cross-Chain"]}}}} ``` ## Exchange rate > Returns an exchange rate quote for the specified currencies and networks. ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"servers":[{"url":"https://api.baltex.io"}],"security":[{"Partner access key":[]}],"components":{"securitySchemes":{"Partner access key":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"ExchangeRate":{"type":"object","properties":{"min":{"type":"number","description":"Minimum allowed amount for the exchange"},"max":{"type":"number","nullable":true,"description":"Maximum allowed amount for the exchange (null means no limit)"},"fromAmount":{"type":"number","description":"Requested amount to exchange"},"toAmount":{"type":"number","description":"Estimated amount to receive"},"fromCurrency":{"type":"string","description":"Ticker of the source currency"},"toCurrency":{"type":"string","description":"Ticker of the target currency"},"fromNetwork":{"type":"string","description":"Source network"},"toNetwork":{"type":"string","description":"Target network"},"amountFromUsd":{"type":"string","description":"Amount in USD equivalent (source)"},"amountToUsd":{"type":"string","description":"Amount in USD equivalent (target)"}}}},"responses":{"UnauthorizedError":{"description":"Unauthorized — missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"statusCode":{"type":"integer"}}}}}}}},"paths":{"/v1/cross-chain/rate":{"get":{"description":"Returns an exchange rate quote for the specified currencies and networks.","operationId":"CexController_getRate_v1","parameters":[{"name":"fromCurrency","required":true,"in":"query","description":"Source currency ticker","schema":{"type":"string"}},{"name":"fromNetwork","required":true,"in":"query","description":"Source network","schema":{"type":"string"}},{"name":"toCurrency","required":true,"in":"query","description":"Target currency ticker","schema":{"type":"string"}},{"name":"toNetwork","required":true,"in":"query","description":"Target network","schema":{"type":"string"}},{"name":"amount","required":false,"in":"query","description":"Amount to exchange (default: 1)","schema":{"type":"string"}},{"name":"flow","required":false,"in":"query","description":"Exchange flow type (standard, fixed-rate)","schema":{"enum":["standard","fixed-rate"],"type":"string"}}],"responses":{"200":{"description":"Successful response with exchange rate data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExchangeRate"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}},"summary":"Exchange rate","tags":["Cross-Chain"]}}}} ``` ## Private exchange rate > Returns a private exchange rate for the specified currencies and networks. ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"servers":[{"url":"https://api.baltex.io"}],"security":[{"Partner access key":[]}],"components":{"securitySchemes":{"Partner access key":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"ExchangeRate":{"type":"object","properties":{"min":{"type":"number","description":"Minimum allowed amount for the exchange"},"max":{"type":"number","nullable":true,"description":"Maximum allowed amount for the exchange (null means no limit)"},"fromAmount":{"type":"number","description":"Requested amount to exchange"},"toAmount":{"type":"number","description":"Estimated amount to receive"},"fromCurrency":{"type":"string","description":"Ticker of the source currency"},"toCurrency":{"type":"string","description":"Ticker of the target currency"},"fromNetwork":{"type":"string","description":"Source network"},"toNetwork":{"type":"string","description":"Target network"},"amountFromUsd":{"type":"string","description":"Amount in USD equivalent (source)"},"amountToUsd":{"type":"string","description":"Amount in USD equivalent (target)"}}}},"responses":{"UnauthorizedError":{"description":"Unauthorized — missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"statusCode":{"type":"integer"}}}}}}}},"paths":{"/v1/cross-chain/rate/private":{"get":{"description":"Returns a private exchange rate for the specified currencies and networks.","operationId":"CexController_getPrivateRate_v1","parameters":[{"name":"fromCurrency","required":true,"in":"query","description":"Source currency ticker","schema":{"type":"string"}},{"name":"fromNetwork","required":true,"in":"query","description":"Source network","schema":{"type":"string"}},{"name":"toCurrency","required":true,"in":"query","description":"Target currency ticker","schema":{"type":"string"}},{"name":"toNetwork","required":true,"in":"query","description":"Target network","schema":{"type":"string"}},{"name":"amount","required":false,"in":"query","description":"Amount to exchange (default: 1)","schema":{"type":"string"}},{"name":"privateType","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response with private exchange rate data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExchangeRate"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}},"summary":"Private exchange rate","tags":["Cross-Chain"]}}}} ``` ## Exchange status > Returns the status of any type of exchange by its ID. ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"servers":[{"url":"https://api.baltex.io"}],"security":[{"Partner access key":[]}],"components":{"securitySchemes":{"Partner access key":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"ExchangeStatusWrapper":{"type":"object","properties":{"type":{"type":"string","enum":["standard","private"],"description":"Type of the exchange"},"exchange":{"oneOf":[{"$ref":"#/components/schemas/StandardExchangeStatus"},{"$ref":"#/components/schemas/PrivateExchangeStatus"}]}}},"StandardExchangeStatus":{"type":"object","properties":{"id":{"type":"string","description":"Unique exchange identifier"},"created":{"type":"string","format":"date-time","description":"Exchange creation timestamp"},"exchangeType":{"type":"string","enum":["standard"],"description":"Type of exchange"},"status":{"type":"string","enum":["pending","confirming","exchanging","sending","finished","failed","refunded"],"description":"Current exchange status"},"request":{"$ref":"#/components/schemas/ExchangeRequest"},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeDetails"},"description":"Array of exchange operations"}}},"ExchangeRequest":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Source currency ticker"},"fromNetwork":{"type":"string","description":"Source network"},"toCurrency":{"type":"string","description":"Target currency ticker"},"toNetwork":{"type":"string","description":"Target network"},"amountFromRequested":{"type":"string","description":"Requested amount to send"},"amountToRequested":{"type":"string","description":"Expected amount to receive"},"depositAddress":{"type":"string","description":"Address where user should send funds"},"recipientAddress":{"type":"string","description":"Address where user will receive funds"},"depositMemo":{"type":"string","nullable":true,"description":"Memo for deposit (if required)"},"recipientMemo":{"type":"string","nullable":true,"description":"Memo for recipient (if required)"},"refundAddress":{"type":"string","nullable":true,"description":"Address for refunds"},"refundMemo":{"type":"string","nullable":true,"description":"Memo for refund address"},"flow":{"type":"string","enum":["standard","fixed-rate"],"description":"Exchange flow type"}}},"ExchangeDetails":{"type":"object","properties":{"amountFromReceived":{"type":"string","nullable":true,"description":"Actual amount received from user"},"amountToReceived":{"type":"string","nullable":true,"description":"Actual amount sent to recipient"},"status":{"type":"string","enum":["pending","confirming","exchanging","sending","finished","failed","refunded"],"description":"Current status of the exchange"},"payinHash":{"type":"string","nullable":true,"description":"Transaction hash of incoming payment"},"payoutHash":{"type":"string","nullable":true,"description":"Transaction hash of outgoing payment"},"created":{"type":"string","format":"date-time","description":"Timestamp when exchange was created"}}},"PrivateExchangeStatus":{"type":"object","properties":{"id":{"type":"string","description":"Unique exchange identifier"},"created":{"type":"string","format":"date-time","description":"Exchange creation timestamp"},"exchangeType":{"type":"string","enum":["private"],"description":"Type of exchange"},"status":{"type":"string","enum":["pending","confirming","exchanging","sending","finished","failed","refunded"],"description":"Current exchange status"},"request":{"$ref":"#/components/schemas/ExchangeRequest"},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeDetails"},"description":"Array of exchange operations"}}}},"responses":{"UnauthorizedError":{"description":"Unauthorized — missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"statusCode":{"type":"integer"}}}}}}}},"paths":{"/v1/cross-chain/exchange/status":{"get":{"description":"Returns the status of any type of exchange by its ID.","operationId":"CexController_getExchangeStatus_v1","parameters":[{"name":"id","required":true,"in":"query","description":"Exchange ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Exchange status information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExchangeStatusWrapper"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}},"summary":"Exchange status","tags":["Cross-Chain"]}}}} ``` ## List of exchanges > Returns all exchanges for partner from the last 24 hours with optional filters. ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"servers":[{"url":"https://api.baltex.io"}],"security":[{"Partner access key":[]}],"components":{"securitySchemes":{"Partner access key":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"ExchangeList":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of exchanges"},"data":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/StandardExchangeStatus"},{"$ref":"#/components/schemas/PrivateExchangeStatus"}]},"description":"Array of exchange records"}}},"StandardExchangeStatus":{"type":"object","properties":{"id":{"type":"string","description":"Unique exchange identifier"},"created":{"type":"string","format":"date-time","description":"Exchange creation timestamp"},"exchangeType":{"type":"string","enum":["standard"],"description":"Type of exchange"},"status":{"type":"string","enum":["pending","confirming","exchanging","sending","finished","failed","refunded"],"description":"Current exchange status"},"request":{"$ref":"#/components/schemas/ExchangeRequest"},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeDetails"},"description":"Array of exchange operations"}}},"ExchangeRequest":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Source currency ticker"},"fromNetwork":{"type":"string","description":"Source network"},"toCurrency":{"type":"string","description":"Target currency ticker"},"toNetwork":{"type":"string","description":"Target network"},"amountFromRequested":{"type":"string","description":"Requested amount to send"},"amountToRequested":{"type":"string","description":"Expected amount to receive"},"depositAddress":{"type":"string","description":"Address where user should send funds"},"recipientAddress":{"type":"string","description":"Address where user will receive funds"},"depositMemo":{"type":"string","nullable":true,"description":"Memo for deposit (if required)"},"recipientMemo":{"type":"string","nullable":true,"description":"Memo for recipient (if required)"},"refundAddress":{"type":"string","nullable":true,"description":"Address for refunds"},"refundMemo":{"type":"string","nullable":true,"description":"Memo for refund address"},"flow":{"type":"string","enum":["standard","fixed-rate"],"description":"Exchange flow type"}}},"ExchangeDetails":{"type":"object","properties":{"amountFromReceived":{"type":"string","nullable":true,"description":"Actual amount received from user"},"amountToReceived":{"type":"string","nullable":true,"description":"Actual amount sent to recipient"},"status":{"type":"string","enum":["pending","confirming","exchanging","sending","finished","failed","refunded"],"description":"Current status of the exchange"},"payinHash":{"type":"string","nullable":true,"description":"Transaction hash of incoming payment"},"payoutHash":{"type":"string","nullable":true,"description":"Transaction hash of outgoing payment"},"created":{"type":"string","format":"date-time","description":"Timestamp when exchange was created"}}},"PrivateExchangeStatus":{"type":"object","properties":{"id":{"type":"string","description":"Unique exchange identifier"},"created":{"type":"string","format":"date-time","description":"Exchange creation timestamp"},"exchangeType":{"type":"string","enum":["private"],"description":"Type of exchange"},"status":{"type":"string","enum":["pending","confirming","exchanging","sending","finished","failed","refunded"],"description":"Current exchange status"},"request":{"$ref":"#/components/schemas/ExchangeRequest"},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeDetails"},"description":"Array of exchange operations"}}}},"responses":{"UnauthorizedError":{"description":"Unauthorized — missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"statusCode":{"type":"integer"}}}}}}}},"paths":{"/v1/cross-chain/exchange/list":{"get":{"description":"Returns all exchanges for partner from the last 24 hours with optional filters.","operationId":"CexController_getPartnerExchanges_v1","parameters":[{"name":"status","required":false,"in":"query","description":"Filter by exchange status","schema":{"enum":["pending","confirming","exchanging","sending","finished","failed","refunded"],"type":"string"}},{"name":"fromCurrency","required":false,"in":"query","description":"Filter by source currency ticker","schema":{"type":"string"}},{"name":"fromNetwork","required":false,"in":"query","description":"Filter by source network","schema":{"type":"string"}},{"name":"toCurrency","required":false,"in":"query","description":"Filter by target currency ticker","schema":{"type":"string"}},{"name":"toNetwork","required":false,"in":"query","description":"Filter by target network","schema":{"type":"string"}},{"name":"exchangeType","required":false,"in":"query","description":"Filter by exchange type","schema":{"enum":["standard","private"],"type":"string"}}],"responses":{"200":{"description":"List of exchanges","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExchangeList"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}},"summary":"List of exchanges","tags":["Cross-Chain"]}}}} ``` ## Standard exchange status > Returns the status of a standard exchange by its ID. ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"servers":[{"url":"https://api.baltex.io"}],"security":[{"Partner access key":[]}],"components":{"securitySchemes":{"Partner access key":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"StandardExchangeStatus":{"type":"object","properties":{"id":{"type":"string","description":"Unique exchange identifier"},"created":{"type":"string","format":"date-time","description":"Exchange creation timestamp"},"exchangeType":{"type":"string","enum":["standard"],"description":"Type of exchange"},"status":{"type":"string","enum":["pending","confirming","exchanging","sending","finished","failed","refunded"],"description":"Current exchange status"},"request":{"$ref":"#/components/schemas/ExchangeRequest"},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeDetails"},"description":"Array of exchange operations"}}},"ExchangeRequest":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Source currency ticker"},"fromNetwork":{"type":"string","description":"Source network"},"toCurrency":{"type":"string","description":"Target currency ticker"},"toNetwork":{"type":"string","description":"Target network"},"amountFromRequested":{"type":"string","description":"Requested amount to send"},"amountToRequested":{"type":"string","description":"Expected amount to receive"},"depositAddress":{"type":"string","description":"Address where user should send funds"},"recipientAddress":{"type":"string","description":"Address where user will receive funds"},"depositMemo":{"type":"string","nullable":true,"description":"Memo for deposit (if required)"},"recipientMemo":{"type":"string","nullable":true,"description":"Memo for recipient (if required)"},"refundAddress":{"type":"string","nullable":true,"description":"Address for refunds"},"refundMemo":{"type":"string","nullable":true,"description":"Memo for refund address"},"flow":{"type":"string","enum":["standard","fixed-rate"],"description":"Exchange flow type"}}},"ExchangeDetails":{"type":"object","properties":{"amountFromReceived":{"type":"string","nullable":true,"description":"Actual amount received from user"},"amountToReceived":{"type":"string","nullable":true,"description":"Actual amount sent to recipient"},"status":{"type":"string","enum":["pending","confirming","exchanging","sending","finished","failed","refunded"],"description":"Current status of the exchange"},"payinHash":{"type":"string","nullable":true,"description":"Transaction hash of incoming payment"},"payoutHash":{"type":"string","nullable":true,"description":"Transaction hash of outgoing payment"},"created":{"type":"string","format":"date-time","description":"Timestamp when exchange was created"}}}},"responses":{"UnauthorizedError":{"description":"Unauthorized — missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"statusCode":{"type":"integer"}}}}}}}},"paths":{"/v1/cross-chain/exchange/status/standard":{"get":{"description":"Returns the status of a standard exchange by its ID.","operationId":"CexController_getStandardExchangeStatus_v1","parameters":[{"name":"id","required":true,"in":"query","description":"Exchange ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Standard exchange status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardExchangeStatus"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}},"summary":"Standard exchange status","tags":["Cross-Chain"]}}}} ``` ## Private exchange status > Returns the status of a private exchange by its ID. ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"servers":[{"url":"https://api.baltex.io"}],"security":[{"Partner access key":[]}],"components":{"securitySchemes":{"Partner access key":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"PrivateExchangeStatus":{"type":"object","properties":{"id":{"type":"string","description":"Unique exchange identifier"},"created":{"type":"string","format":"date-time","description":"Exchange creation timestamp"},"exchangeType":{"type":"string","enum":["private"],"description":"Type of exchange"},"status":{"type":"string","enum":["pending","confirming","exchanging","sending","finished","failed","refunded"],"description":"Current exchange status"},"request":{"$ref":"#/components/schemas/ExchangeRequest"},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeDetails"},"description":"Array of exchange operations"}}},"ExchangeRequest":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Source currency ticker"},"fromNetwork":{"type":"string","description":"Source network"},"toCurrency":{"type":"string","description":"Target currency ticker"},"toNetwork":{"type":"string","description":"Target network"},"amountFromRequested":{"type":"string","description":"Requested amount to send"},"amountToRequested":{"type":"string","description":"Expected amount to receive"},"depositAddress":{"type":"string","description":"Address where user should send funds"},"recipientAddress":{"type":"string","description":"Address where user will receive funds"},"depositMemo":{"type":"string","nullable":true,"description":"Memo for deposit (if required)"},"recipientMemo":{"type":"string","nullable":true,"description":"Memo for recipient (if required)"},"refundAddress":{"type":"string","nullable":true,"description":"Address for refunds"},"refundMemo":{"type":"string","nullable":true,"description":"Memo for refund address"},"flow":{"type":"string","enum":["standard","fixed-rate"],"description":"Exchange flow type"}}},"ExchangeDetails":{"type":"object","properties":{"amountFromReceived":{"type":"string","nullable":true,"description":"Actual amount received from user"},"amountToReceived":{"type":"string","nullable":true,"description":"Actual amount sent to recipient"},"status":{"type":"string","enum":["pending","confirming","exchanging","sending","finished","failed","refunded"],"description":"Current status of the exchange"},"payinHash":{"type":"string","nullable":true,"description":"Transaction hash of incoming payment"},"payoutHash":{"type":"string","nullable":true,"description":"Transaction hash of outgoing payment"},"created":{"type":"string","format":"date-time","description":"Timestamp when exchange was created"}}}},"responses":{"UnauthorizedError":{"description":"Unauthorized — missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"statusCode":{"type":"integer"}}}}}}}},"paths":{"/v1/cross-chain/exchange/status/private":{"get":{"description":"Returns the status of a private exchange by its ID.","operationId":"CexController_getPrivateExchangeStatus_v1","parameters":[{"name":"id","required":true,"in":"query","description":"Exchange ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Private exchange status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrivateExchangeStatus"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}},"summary":"Private exchange status","tags":["Cross-Chain"]}}}} ``` ## Create standard exchange > Creates a standard exchange. ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"servers":[{"url":"https://api.baltex.io"}],"security":[{"Partner access key":[]}],"components":{"securitySchemes":{"Partner access key":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"CreateExchangeRequestDto":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Source currency ticker"},"toCurrency":{"type":"string","description":"Target currency ticker"},"fromNetwork":{"type":"string","description":"Source network"},"toNetwork":{"type":"string","description":"Target network"},"fromAmount":{"type":"string","description":"Amount to exchange"},"address":{"type":"string","description":"Recipient address"},"memo":{"type":"string","description":"Memo for recipient (if required)"},"refundAddress":{"type":"string","description":"Refund address"},"refundMemo":{"type":"string","description":"Refund memo"},"flow":{"type":"string","enum":["standard","fixed-rate"],"description":"Exchange flow type"},"rateId":{"type":"string","description":"RateId is needed so that you can freeze the estimate from the /rate method for fixed-rate exchange. It is valid for 1 minute from the moment it is received."}},"required":["fromCurrency","toCurrency","fromNetwork","toNetwork","fromAmount","flow"]},"CreateExchangeResponse":{"type":"object","properties":{"id":{"type":"string","description":"Unique exchange identifier"},"status":{"type":"string","enum":["pending"],"description":"Initial exchange status"},"exchangeType":{"type":"string","enum":["standard"],"description":"Type of exchange"},"created":{"type":"string","format":"date-time","description":"Exchange creation timestamp"},"request":{"type":"object","properties":{"fromCurrency":{"type":"string"},"fromNetwork":{"type":"string"},"toCurrency":{"type":"string"},"toNetwork":{"type":"string"},"amountFromRequested":{"type":"string"},"amountToRequested":{"type":"string"},"depositAddress":{"type":"string","description":"Address where user should deposit funds"},"recipientAddress":{"type":"string","description":"Address where user will receive funds"},"flow":{"type":"string"}}},"exchanges":{"type":"array","items":{},"description":"Empty array initially, populated as exchange progresses"}}}},"responses":{"UnauthorizedError":{"description":"Unauthorized — missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"statusCode":{"type":"integer"}}}}}}}},"paths":{"/v1/cross-chain/exchange":{"post":{"description":"Creates a standard exchange.","operationId":"CexController_createExchange_v1","parameters":[],"requestBody":{"required":true,"description":"Standard exchange data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateExchangeRequestDto"}}}},"responses":{"201":{"description":"Exchange created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateExchangeResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}},"summary":"Create standard exchange","tags":["Cross-Chain"]}}}} ``` ## Create private exchange > Creates a private exchange order. ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"servers":[{"url":"https://api.baltex.io"}],"security":[{"Partner access key":[]}],"components":{"securitySchemes":{"Partner access key":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"CreatePrivateExchangeRequestDto":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Source currency ticker"},"toCurrency":{"type":"string","description":"Target currency ticker"},"fromNetwork":{"type":"string","description":"Source network"},"toNetwork":{"type":"string","description":"Target network"},"fromAmount":{"type":"string","description":"Amount to exchange"},"memo":{"type":"string","description":"Extra ID for recipient (if required)"},"privateType":{"type":"string","description":"There are two types of private exchanges: 'privatePlus' - an intermediary network for XMR only; 'efficient' - the fastest and cheapest intermediary networks."},"address":{"type":"string","description":"Recipient address"},"refundAddress":{"type":"string","description":"Refund address"},"refundMemo":{"type":"string","description":"Extra ID for refund address (if required)"}},"required":["fromCurrency","toCurrency","fromNetwork","toNetwork","fromAmount"]},"CreatePrivateExchangeResponse":{"type":"object","properties":{"id":{"type":"string","description":"Unique exchange identifier"},"created":{"type":"string","format":"date-time","description":"Exchange creation timestamp"},"exchangeType":{"type":"string","enum":["private"],"description":"Type of exchange"},"status":{"type":"string","enum":["pending"],"description":"Initial exchange status"},"request":{"type":"object","properties":{"fromCurrency":{"type":"string"},"fromNetwork":{"type":"string"},"toCurrency":{"type":"string"},"toNetwork":{"type":"string"},"amountFromRequested":{"type":"string"},"amountToRequested":{"type":"string"},"depositAddress":{"type":"string","description":"Address where user should deposit funds"},"recipientAddress":{"type":"string","description":"Address where user will receive funds"},"flow":{"type":"string"}}},"exchanges":{"type":"array","items":{},"description":"Empty array initially, populated as exchange progresses"}}}},"responses":{"UnauthorizedError":{"description":"Unauthorized — missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"statusCode":{"type":"integer"}}}}}}}},"paths":{"/v1/cross-chain/exchange/private":{"post":{"description":"Creates a private exchange order.","operationId":"CexController_createPrivateExchange_v1","parameters":[],"requestBody":{"required":true,"description":"Private exchange order data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePrivateExchangeRequestDto"}}}},"responses":{"201":{"description":"Private exchange created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePrivateExchangeResponse"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}},"summary":"Create private exchange","tags":["Cross-Chain"]}}}} ``` ## Rates > Returns exchange rates in XML format. This is a publicly accessible endpoint that does not require authentication. ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"servers":[{"url":"https://api.baltex.io"}],"paths":{"/v1/rates":{"get":{"description":"Returns exchange rates in XML format. This is a publicly accessible endpoint that does not require authentication.","operationId":"RatesController_getRates_v1","parameters":[],"responses":{"200":{"description":"Exchange rates in XML format"}},"summary":"Rates","tags":["Cross-Chain"]}}}} ``` # De Fi ## Currency info > Returns a currency info for the specified network and address if it exists. ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"servers":[{"url":"https://api.baltex.io"}],"security":[{"Partner access key":[]}],"components":{"securitySchemes":{"Partner access key":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"DeFiCurrency":{"type":"object","properties":{"name":{"type":"string","description":"Full name of the token"},"address":{"type":"string","description":"Token contract address"},"decimals":{"type":"integer","description":"Number of decimal places for the token"},"symbol":{"type":"string","description":"Token symbol"},"network":{"type":"string","description":"Network ticker"},"enabled":{"type":"boolean","description":"Indicates if token is currently available for swaps"},"image":{"type":"string","description":"URL to the token icon"}}}},"responses":{"UnauthorizedError":{"description":"Unauthorized — missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"statusCode":{"type":"integer"}}}}}}}},"paths":{"/v1/defi/currency/info":{"get":{"description":"Returns a currency info for the specified network and address if it exists.","operationId":"DexController_getCurrencyInfo_v1","parameters":[{"name":"network","required":true,"in":"query","description":"Network ticker (Currently available: eth, sol, sui, sei, arbitrum, base, bsc, cchain, celo, linea, matic, op, sonic, uni)","schema":{"type":"string"}},{"name":"address","required":true,"in":"query","description":"Token contract address","schema":{"type":"string"}}],"responses":{"200":{"description":"Currency information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeFiCurrency"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}},"summary":"Currency info","tags":["DeFi"]}}}} ``` ## Available currencies > Returns a list of available currencies for the specified network. ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"servers":[{"url":"https://api.baltex.io"}],"security":[{"Partner access key":[]}],"components":{"securitySchemes":{"Partner access key":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"DeFiCurrency":{"type":"object","properties":{"name":{"type":"string","description":"Full name of the token"},"address":{"type":"string","description":"Token contract address"},"decimals":{"type":"integer","description":"Number of decimal places for the token"},"symbol":{"type":"string","description":"Token symbol"},"network":{"type":"string","description":"Network ticker"},"enabled":{"type":"boolean","description":"Indicates if token is currently available for swaps"},"image":{"type":"string","description":"URL to the token icon"}}}},"responses":{"UnauthorizedError":{"description":"Unauthorized — missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"statusCode":{"type":"integer"}}}}}}}},"paths":{"/v1/defi/available-currencies":{"get":{"description":"Returns a list of available currencies for the specified network.","operationId":"DexController_getAvailableCurrenciesList_v1","parameters":[{"name":"network","required":true,"in":"query","description":"Network ticker (Currently available: eth, sol, sui, sei, arbitrum, base, bsc, cchain, celo, linea, matic, op, sonic, uni)","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number for pagination","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page","schema":{"type":"string"}}],"responses":{"200":{"description":"List of available currencies for DeFi","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DeFiCurrency"}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}},"summary":"Available currencies","tags":["DeFi"]}}}} ``` ## Swap quote > Returns a quote for swapping tokens on a specified network. ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"servers":[{"url":"https://api.baltex.io"}],"security":[{"Partner access key":[]}],"components":{"securitySchemes":{"Partner access key":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"SwapQuote":{"type":"object","properties":{"fromAmount":{"type":"string","description":"Amount to swap from"},"usdFromAmount":{"type":"string","description":"USD value of from amount"},"toAmount":{"type":"string","description":"Estimated amount to receive"},"usdToAmount":{"type":"string","description":"USD value of to amount"},"receivedAmount":{"type":"string","description":"Actual amount user will receive after fees"},"fee":{"type":"string","description":"Fee amount"},"routes":{"type":"array","items":{"$ref":"#/components/schemas/SwapRoute"},"description":"Swap routes with DEX details"},"priceImpact":{"type":"string","description":"Price impact percentage"}}},"SwapRoute":{"type":"object","properties":{"percentage":{"type":"number","description":"Percentage of total swap using this route"},"subRoutes":{"type":"array","items":{"$ref":"#/components/schemas/SwapSubRoute"},"description":"Individual steps in the swap route"}}},"SwapSubRoute":{"type":"object","properties":{"from":{"type":"string","description":"Source token address in this step"},"to":{"type":"string","description":"Target token address in this step"},"dexes":{"type":"array","items":{"$ref":"#/components/schemas/SwapDexInfo"},"description":"DEXes used in this swap step"}}},"SwapDexInfo":{"type":"object","properties":{"name":{"type":"string","description":"DEX name"},"address":{"type":"string","description":"DEX contract address"},"fee":{"type":"number","description":"DEX fee percentage"},"percentage":{"type":"number","description":"Percentage of swap going through this DEX"}}}},"responses":{"UnauthorizedError":{"description":"Unauthorized — missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"statusCode":{"type":"integer"}}}}}}}},"paths":{"/v1/defi/quote":{"get":{"description":"Returns a quote for swapping tokens on a specified network.","operationId":"DexController_getQuote_v1","parameters":[{"name":"network","required":true,"in":"query","description":"Network name (Currently available: eth, sol, sui, sei, arbitrum, base, bsc, cchain, celo, linea, matic, op, sonic, uni)","schema":{"type":"string"}},{"name":"fromTokenAddress","required":true,"in":"query","description":"Source token contract address","schema":{"type":"string"}},{"name":"toTokenAddress","required":true,"in":"query","description":"Target token contract address","schema":{"type":"string"}},{"name":"amount","required":true,"in":"query","description":"Amount to swap","schema":{"type":"string"}},{"name":"slippage","required":true,"in":"query","description":"Allowed slippage in percent","schema":{"type":"string"}},{"name":"referrerFee","required":true,"in":"query","description":"Referrer fee in percent","schema":{"type":"string"}}],"responses":{"200":{"description":"Swap quote","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SwapQuote"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}},"summary":"Swap quote","tags":["DeFi"]}}}} ``` ## List of exchanges > Returns all DEX exchanges for partner from the last 24 hours with optional filters. ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"servers":[{"url":"https://api.baltex.io"}],"security":[{"Partner access key":[]}],"components":{"securitySchemes":{"Partner access key":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"DexExchangeList":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of exchanges"},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/DexExchange"},"description":"Array of DEX exchanges"}}},"DexExchange":{"type":"object","properties":{"id":{"type":"string","description":"Unique exchange identifier"},"created":{"type":"string","format":"date-time","description":"Exchange creation timestamp"},"updated":{"type":"string","format":"date-time","description":"Exchange last update timestamp"},"network":{"type":"string","description":"Network where exchange occurred"},"fromTokenAddress":{"type":"string","description":"Source token contract address"},"toTokenAddress":{"type":"string","description":"Target token contract address"},"amountFrom":{"type":"string","description":"Amount sent"},"amountTo":{"type":"string","description":"Amount received"},"addressFrom":{"type":"string","description":"Sender wallet address"},"addressTo":{"type":"string","nullable":true,"description":"Recipient wallet address"},"commissionPercentage":{"type":"string","description":"Commission percentage"},"status":{"type":"string","enum":["pending","confirming","finished","failed"],"description":"Exchange status"},"hash":{"type":"string","description":"Transaction hash"}}}},"responses":{"UnauthorizedError":{"description":"Unauthorized — missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"statusCode":{"type":"integer"}}}}}}}},"paths":{"/v1/defi/exchange/list":{"get":{"description":"Returns all DEX exchanges for partner from the last 24 hours with optional filters.","operationId":"DexController_getPartnerDexExchanges_v1","parameters":[{"name":"status","required":false,"in":"query","description":"Filter by exchange status","schema":{"type":"string"}},{"name":"fromTokenAddress","required":false,"in":"query","description":"Filter by source token address","schema":{"type":"string"}},{"name":"toTokenAddress","required":false,"in":"query","description":"Filter by target token address","schema":{"type":"string"}},{"name":"network","required":false,"in":"query","description":"Filter by network","schema":{"type":"string"}}],"responses":{"200":{"description":"List of DEX exchanges","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DexExchangeList"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}},"summary":"List of exchanges","tags":["DeFi"]}}}} ``` ## Swap tokens > Build a transaction hash from the provided data and returns it to sign. ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"servers":[{"url":"https://api.baltex.io"}],"security":[{"Partner access key":[]}],"components":{"securitySchemes":{"Partner access key":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"SwapDexTransactionDto":{"type":"object","properties":{"account":{"type":"string","description":"Sender address"},"fromTokenAddress":{"type":"string","description":"Source token contract address"},"toTokenAddress":{"type":"string","description":"Target token contract address"},"amount":{"type":"string","description":"Amount to swap"},"slippage":{"type":"string","description":"Allowed slippage"},"referrerFee":{"type":"string","description":"Referrer fee"},"network":{"type":"string","description":"Network name (Currently available: eth, sol, sui, sei, arbitrum, base, bsc, cchain, celo, linea, matic, op, sonic, uni)"}},"required":["account","fromTokenAddress","toTokenAddress","amount","slippage","referrerFee","network"]}},"responses":{"UnauthorizedError":{"description":"Unauthorized — missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"statusCode":{"type":"integer"}}}}}}}},"paths":{"/v1/defi/transaction/swap":{"post":{"description":"Build a transaction hash from the provided data and returns it to sign.","operationId":"DexController_swapTransaction_v1","parameters":[],"requestBody":{"required":true,"description":"Swap transaction data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SwapDexTransactionDto"}}}},"responses":{"201":{"description":"Transaction hash(es) created","content":{"application/json":{"schema":{"oneOf":[{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":1,"description":"Array containing swap raw transaction hash only (approval not required)"},{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":2,"description":"Array containing approval (1st string) and swap transaction (2nd string) raw transactions"}]}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}},"summary":"Swap tokens","tags":["DeFi"]}}}} ``` ## Send approve transaction > Broadcasts the client-signed transaction hash to the network to approve token spending. ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"servers":[{"url":"https://api.baltex.io"}],"security":[{"Partner access key":[]}],"components":{"securitySchemes":{"Partner access key":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"SendDexApproveTransactionDto":{"type":"object","properties":{"network":{"type":"string","description":"Network name"},"rawApproveTx":{"type":"string","description":"Raw approve transaction"}},"required":["network","rawApproveTx"]}},"responses":{"UnauthorizedError":{"description":"Unauthorized — missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"statusCode":{"type":"integer"}}}}}}}},"paths":{"/v1/defi/send/approve":{"post":{"description":"Broadcasts the client-signed transaction hash to the network to approve token spending.","operationId":"DexController_sendApproveTransaction_v1","parameters":[],"requestBody":{"required":true,"description":"Approve transaction data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendDexApproveTransactionDto"}}}},"responses":{"201":{"description":"Approve transaction sent successfully","content":{"application/json":{"schema":{"type":"string","description":"Transaction hash"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}},"summary":"Send approve transaction","tags":["DeFi"]}}}} ``` ## Send transaction > Broadcasts the client-signed transaction hash to the network to execute the swap. ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"servers":[{"url":"https://api.baltex.io"}],"security":[{"Partner access key":[]}],"components":{"securitySchemes":{"Partner access key":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"SendDexTransactionDto":{"type":"object","properties":{"account":{"type":"string","description":"Receiver address"},"amountFrom":{"type":"string","description":"Amount sent from sender"},"amountTo":{"type":"string","description":"Amount to be received"},"fromTokenAddress":{"type":"string","description":"Source token contract address"},"toTokenAddress":{"type":"string","description":"Target token contract address"},"network":{"type":"string","description":"Network name (Currently available: eth, sol, sui, sei, arbitrum, base, bsc, cchain, celo, linea, matic, op, sonic, uni)"},"commissionPercentage":{"type":"string","description":"Commission percentage"},"rawTx":{"type":"string","description":"Raw transaction data"},"hash":{"type":"string","description":"Transaction hash"},"to":{"type":"string","description":"Recipient address (again, for compatibility)"},"isExchange":{"type":"boolean","description":"If it is an approve transaction or any other transaction other than a swap, the flag must be false."}},"required":["account","amountFrom","amountTo","fromTokenAddress","toTokenAddress","network","commissionPercentage"]}},"responses":{"UnauthorizedError":{"description":"Unauthorized — missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"error":{"type":"string"},"statusCode":{"type":"integer"}}}}}}}},"paths":{"/v1/defi/send/swap":{"post":{"description":"Broadcasts the client-signed transaction hash to the network to execute the swap.","operationId":"DexController_sendTransaction_v1","parameters":[],"requestBody":{"required":true,"description":"Transaction data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendDexTransactionDto"}}}},"responses":{"201":{"description":"Transaction sent successfully","content":{"application/json":{"schema":{"type":"string","description":"Transaction hash"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}},"summary":"Send transaction","tags":["DeFi"]}}}} ``` # Models ## The Currency object ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"components":{"schemas":{"Currency":{"type":"object","properties":{"ticker":{"type":"string","description":"Currency ticker (e.g., btc)"},"network":{"type":"string","description":"Network ticker (e.g., btc, eth)"},"symbol":{"type":"string","description":"Symbol representing the currency"},"name":{"type":"string","description":"Full name of the currency"},"hasMemo":{"type":"boolean","description":"Indicates whether this currency supports memo/extraId"},"requireMemo":{"type":"boolean","description":"Indicates whether memo/extraId is required to complete transactions"},"isFiat":{"type":"boolean","description":"Shows if the currency is fiat (e.g., USD)"},"isStable":{"type":"boolean","description":"Indicates if the currency is a stablecoin"},"supportsFixedRate":{"type":"boolean","description":"True if fixed-rate exchanges are supported"},"enabled":{"type":"boolean","description":"Indicates if currency is currently available for use"},"image":{"type":"string","description":"URL to the currency icon"},"regexAddress":{"type":"string","description":"Regular expression pattern for validating recipient addresses"},"addressExplorer":{"type":"string","description":"Block explorer URL template for addresses (use {} as placeholder)"},"txExplorer":{"type":"string","description":"Block explorer URL template for transactions (use {} as placeholder)"},"confirmations":{"type":"integer","description":"Number of required confirmations for incoming transactions"},"rank":{"type":"integer","description":"Currency ranking priority (use for sorting in UI)"}}}}}} ``` ## The ExchangeRate object ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"components":{"schemas":{"ExchangeRate":{"type":"object","properties":{"min":{"type":"number","description":"Minimum allowed amount for the exchange"},"max":{"type":"number","nullable":true,"description":"Maximum allowed amount for the exchange (null means no limit)"},"fromAmount":{"type":"number","description":"Requested amount to exchange"},"toAmount":{"type":"number","description":"Estimated amount to receive"},"fromCurrency":{"type":"string","description":"Ticker of the source currency"},"toCurrency":{"type":"string","description":"Ticker of the target currency"},"fromNetwork":{"type":"string","description":"Source network"},"toNetwork":{"type":"string","description":"Target network"},"amountFromUsd":{"type":"string","description":"Amount in USD equivalent (source)"},"amountToUsd":{"type":"string","description":"Amount in USD equivalent (target)"}}}}}} ``` ## The ExchangeRequest object ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"components":{"schemas":{"ExchangeRequest":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Source currency ticker"},"fromNetwork":{"type":"string","description":"Source network"},"toCurrency":{"type":"string","description":"Target currency ticker"},"toNetwork":{"type":"string","description":"Target network"},"amountFromRequested":{"type":"string","description":"Requested amount to send"},"amountToRequested":{"type":"string","description":"Expected amount to receive"},"depositAddress":{"type":"string","description":"Address where user should send funds"},"recipientAddress":{"type":"string","description":"Address where user will receive funds"},"depositMemo":{"type":"string","nullable":true,"description":"Memo for deposit (if required)"},"recipientMemo":{"type":"string","nullable":true,"description":"Memo for recipient (if required)"},"refundAddress":{"type":"string","nullable":true,"description":"Address for refunds"},"refundMemo":{"type":"string","nullable":true,"description":"Memo for refund address"},"flow":{"type":"string","enum":["standard","fixed-rate"],"description":"Exchange flow type"}}}}}} ``` ## The ExchangeDetails object ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"components":{"schemas":{"ExchangeDetails":{"type":"object","properties":{"amountFromReceived":{"type":"string","nullable":true,"description":"Actual amount received from user"},"amountToReceived":{"type":"string","nullable":true,"description":"Actual amount sent to recipient"},"status":{"type":"string","enum":["pending","confirming","exchanging","sending","finished","failed","refunded"],"description":"Current status of the exchange"},"payinHash":{"type":"string","nullable":true,"description":"Transaction hash of incoming payment"},"payoutHash":{"type":"string","nullable":true,"description":"Transaction hash of outgoing payment"},"created":{"type":"string","format":"date-time","description":"Timestamp when exchange was created"}}}}}} ``` ## The StandardExchangeStatus object ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"components":{"schemas":{"StandardExchangeStatus":{"type":"object","properties":{"id":{"type":"string","description":"Unique exchange identifier"},"created":{"type":"string","format":"date-time","description":"Exchange creation timestamp"},"exchangeType":{"type":"string","enum":["standard"],"description":"Type of exchange"},"status":{"type":"string","enum":["pending","confirming","exchanging","sending","finished","failed","refunded"],"description":"Current exchange status"},"request":{"$ref":"#/components/schemas/ExchangeRequest"},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeDetails"},"description":"Array of exchange operations"}}},"ExchangeRequest":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Source currency ticker"},"fromNetwork":{"type":"string","description":"Source network"},"toCurrency":{"type":"string","description":"Target currency ticker"},"toNetwork":{"type":"string","description":"Target network"},"amountFromRequested":{"type":"string","description":"Requested amount to send"},"amountToRequested":{"type":"string","description":"Expected amount to receive"},"depositAddress":{"type":"string","description":"Address where user should send funds"},"recipientAddress":{"type":"string","description":"Address where user will receive funds"},"depositMemo":{"type":"string","nullable":true,"description":"Memo for deposit (if required)"},"recipientMemo":{"type":"string","nullable":true,"description":"Memo for recipient (if required)"},"refundAddress":{"type":"string","nullable":true,"description":"Address for refunds"},"refundMemo":{"type":"string","nullable":true,"description":"Memo for refund address"},"flow":{"type":"string","enum":["standard","fixed-rate"],"description":"Exchange flow type"}}},"ExchangeDetails":{"type":"object","properties":{"amountFromReceived":{"type":"string","nullable":true,"description":"Actual amount received from user"},"amountToReceived":{"type":"string","nullable":true,"description":"Actual amount sent to recipient"},"status":{"type":"string","enum":["pending","confirming","exchanging","sending","finished","failed","refunded"],"description":"Current status of the exchange"},"payinHash":{"type":"string","nullable":true,"description":"Transaction hash of incoming payment"},"payoutHash":{"type":"string","nullable":true,"description":"Transaction hash of outgoing payment"},"created":{"type":"string","format":"date-time","description":"Timestamp when exchange was created"}}}}}} ``` ## The PrivateExchangeStatus object ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"components":{"schemas":{"PrivateExchangeStatus":{"type":"object","properties":{"id":{"type":"string","description":"Unique exchange identifier"},"created":{"type":"string","format":"date-time","description":"Exchange creation timestamp"},"exchangeType":{"type":"string","enum":["private"],"description":"Type of exchange"},"status":{"type":"string","enum":["pending","confirming","exchanging","sending","finished","failed","refunded"],"description":"Current exchange status"},"request":{"$ref":"#/components/schemas/ExchangeRequest"},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeDetails"},"description":"Array of exchange operations"}}},"ExchangeRequest":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Source currency ticker"},"fromNetwork":{"type":"string","description":"Source network"},"toCurrency":{"type":"string","description":"Target currency ticker"},"toNetwork":{"type":"string","description":"Target network"},"amountFromRequested":{"type":"string","description":"Requested amount to send"},"amountToRequested":{"type":"string","description":"Expected amount to receive"},"depositAddress":{"type":"string","description":"Address where user should send funds"},"recipientAddress":{"type":"string","description":"Address where user will receive funds"},"depositMemo":{"type":"string","nullable":true,"description":"Memo for deposit (if required)"},"recipientMemo":{"type":"string","nullable":true,"description":"Memo for recipient (if required)"},"refundAddress":{"type":"string","nullable":true,"description":"Address for refunds"},"refundMemo":{"type":"string","nullable":true,"description":"Memo for refund address"},"flow":{"type":"string","enum":["standard","fixed-rate"],"description":"Exchange flow type"}}},"ExchangeDetails":{"type":"object","properties":{"amountFromReceived":{"type":"string","nullable":true,"description":"Actual amount received from user"},"amountToReceived":{"type":"string","nullable":true,"description":"Actual amount sent to recipient"},"status":{"type":"string","enum":["pending","confirming","exchanging","sending","finished","failed","refunded"],"description":"Current status of the exchange"},"payinHash":{"type":"string","nullable":true,"description":"Transaction hash of incoming payment"},"payoutHash":{"type":"string","nullable":true,"description":"Transaction hash of outgoing payment"},"created":{"type":"string","format":"date-time","description":"Timestamp when exchange was created"}}}}}} ``` ## The ExchangeStatusWrapper object ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"components":{"schemas":{"ExchangeStatusWrapper":{"type":"object","properties":{"type":{"type":"string","enum":["standard","private"],"description":"Type of the exchange"},"exchange":{"oneOf":[{"$ref":"#/components/schemas/StandardExchangeStatus"},{"$ref":"#/components/schemas/PrivateExchangeStatus"}]}}},"StandardExchangeStatus":{"type":"object","properties":{"id":{"type":"string","description":"Unique exchange identifier"},"created":{"type":"string","format":"date-time","description":"Exchange creation timestamp"},"exchangeType":{"type":"string","enum":["standard"],"description":"Type of exchange"},"status":{"type":"string","enum":["pending","confirming","exchanging","sending","finished","failed","refunded"],"description":"Current exchange status"},"request":{"$ref":"#/components/schemas/ExchangeRequest"},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeDetails"},"description":"Array of exchange operations"}}},"ExchangeRequest":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Source currency ticker"},"fromNetwork":{"type":"string","description":"Source network"},"toCurrency":{"type":"string","description":"Target currency ticker"},"toNetwork":{"type":"string","description":"Target network"},"amountFromRequested":{"type":"string","description":"Requested amount to send"},"amountToRequested":{"type":"string","description":"Expected amount to receive"},"depositAddress":{"type":"string","description":"Address where user should send funds"},"recipientAddress":{"type":"string","description":"Address where user will receive funds"},"depositMemo":{"type":"string","nullable":true,"description":"Memo for deposit (if required)"},"recipientMemo":{"type":"string","nullable":true,"description":"Memo for recipient (if required)"},"refundAddress":{"type":"string","nullable":true,"description":"Address for refunds"},"refundMemo":{"type":"string","nullable":true,"description":"Memo for refund address"},"flow":{"type":"string","enum":["standard","fixed-rate"],"description":"Exchange flow type"}}},"ExchangeDetails":{"type":"object","properties":{"amountFromReceived":{"type":"string","nullable":true,"description":"Actual amount received from user"},"amountToReceived":{"type":"string","nullable":true,"description":"Actual amount sent to recipient"},"status":{"type":"string","enum":["pending","confirming","exchanging","sending","finished","failed","refunded"],"description":"Current status of the exchange"},"payinHash":{"type":"string","nullable":true,"description":"Transaction hash of incoming payment"},"payoutHash":{"type":"string","nullable":true,"description":"Transaction hash of outgoing payment"},"created":{"type":"string","format":"date-time","description":"Timestamp when exchange was created"}}},"PrivateExchangeStatus":{"type":"object","properties":{"id":{"type":"string","description":"Unique exchange identifier"},"created":{"type":"string","format":"date-time","description":"Exchange creation timestamp"},"exchangeType":{"type":"string","enum":["private"],"description":"Type of exchange"},"status":{"type":"string","enum":["pending","confirming","exchanging","sending","finished","failed","refunded"],"description":"Current exchange status"},"request":{"$ref":"#/components/schemas/ExchangeRequest"},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeDetails"},"description":"Array of exchange operations"}}}}}} ``` ## The ExchangeList object ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"components":{"schemas":{"ExchangeList":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of exchanges"},"data":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/StandardExchangeStatus"},{"$ref":"#/components/schemas/PrivateExchangeStatus"}]},"description":"Array of exchange records"}}},"StandardExchangeStatus":{"type":"object","properties":{"id":{"type":"string","description":"Unique exchange identifier"},"created":{"type":"string","format":"date-time","description":"Exchange creation timestamp"},"exchangeType":{"type":"string","enum":["standard"],"description":"Type of exchange"},"status":{"type":"string","enum":["pending","confirming","exchanging","sending","finished","failed","refunded"],"description":"Current exchange status"},"request":{"$ref":"#/components/schemas/ExchangeRequest"},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeDetails"},"description":"Array of exchange operations"}}},"ExchangeRequest":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Source currency ticker"},"fromNetwork":{"type":"string","description":"Source network"},"toCurrency":{"type":"string","description":"Target currency ticker"},"toNetwork":{"type":"string","description":"Target network"},"amountFromRequested":{"type":"string","description":"Requested amount to send"},"amountToRequested":{"type":"string","description":"Expected amount to receive"},"depositAddress":{"type":"string","description":"Address where user should send funds"},"recipientAddress":{"type":"string","description":"Address where user will receive funds"},"depositMemo":{"type":"string","nullable":true,"description":"Memo for deposit (if required)"},"recipientMemo":{"type":"string","nullable":true,"description":"Memo for recipient (if required)"},"refundAddress":{"type":"string","nullable":true,"description":"Address for refunds"},"refundMemo":{"type":"string","nullable":true,"description":"Memo for refund address"},"flow":{"type":"string","enum":["standard","fixed-rate"],"description":"Exchange flow type"}}},"ExchangeDetails":{"type":"object","properties":{"amountFromReceived":{"type":"string","nullable":true,"description":"Actual amount received from user"},"amountToReceived":{"type":"string","nullable":true,"description":"Actual amount sent to recipient"},"status":{"type":"string","enum":["pending","confirming","exchanging","sending","finished","failed","refunded"],"description":"Current status of the exchange"},"payinHash":{"type":"string","nullable":true,"description":"Transaction hash of incoming payment"},"payoutHash":{"type":"string","nullable":true,"description":"Transaction hash of outgoing payment"},"created":{"type":"string","format":"date-time","description":"Timestamp when exchange was created"}}},"PrivateExchangeStatus":{"type":"object","properties":{"id":{"type":"string","description":"Unique exchange identifier"},"created":{"type":"string","format":"date-time","description":"Exchange creation timestamp"},"exchangeType":{"type":"string","enum":["private"],"description":"Type of exchange"},"status":{"type":"string","enum":["pending","confirming","exchanging","sending","finished","failed","refunded"],"description":"Current exchange status"},"request":{"$ref":"#/components/schemas/ExchangeRequest"},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeDetails"},"description":"Array of exchange operations"}}}}}} ``` ## The CreateExchangeResponse object ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"components":{"schemas":{"CreateExchangeResponse":{"type":"object","properties":{"id":{"type":"string","description":"Unique exchange identifier"},"status":{"type":"string","enum":["pending"],"description":"Initial exchange status"},"exchangeType":{"type":"string","enum":["standard"],"description":"Type of exchange"},"created":{"type":"string","format":"date-time","description":"Exchange creation timestamp"},"request":{"type":"object","properties":{"fromCurrency":{"type":"string"},"fromNetwork":{"type":"string"},"toCurrency":{"type":"string"},"toNetwork":{"type":"string"},"amountFromRequested":{"type":"string"},"amountToRequested":{"type":"string"},"depositAddress":{"type":"string","description":"Address where user should deposit funds"},"recipientAddress":{"type":"string","description":"Address where user will receive funds"},"flow":{"type":"string"}}},"exchanges":{"type":"array","items":{},"description":"Empty array initially, populated as exchange progresses"}}}}}} ``` ## The CreatePrivateExchangeResponse object ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"components":{"schemas":{"CreatePrivateExchangeResponse":{"type":"object","properties":{"id":{"type":"string","description":"Unique exchange identifier"},"created":{"type":"string","format":"date-time","description":"Exchange creation timestamp"},"exchangeType":{"type":"string","enum":["private"],"description":"Type of exchange"},"status":{"type":"string","enum":["pending"],"description":"Initial exchange status"},"request":{"type":"object","properties":{"fromCurrency":{"type":"string"},"fromNetwork":{"type":"string"},"toCurrency":{"type":"string"},"toNetwork":{"type":"string"},"amountFromRequested":{"type":"string"},"amountToRequested":{"type":"string"},"depositAddress":{"type":"string","description":"Address where user should deposit funds"},"recipientAddress":{"type":"string","description":"Address where user will receive funds"},"flow":{"type":"string"}}},"exchanges":{"type":"array","items":{},"description":"Empty array initially, populated as exchange progresses"}}}}}} ``` ## The CreateExchangeRequestDto object ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"components":{"schemas":{"CreateExchangeRequestDto":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Source currency ticker"},"toCurrency":{"type":"string","description":"Target currency ticker"},"fromNetwork":{"type":"string","description":"Source network"},"toNetwork":{"type":"string","description":"Target network"},"fromAmount":{"type":"string","description":"Amount to exchange"},"address":{"type":"string","description":"Recipient address"},"memo":{"type":"string","description":"Memo for recipient (if required)"},"refundAddress":{"type":"string","description":"Refund address"},"refundMemo":{"type":"string","description":"Refund memo"},"flow":{"type":"string","enum":["standard","fixed-rate"],"description":"Exchange flow type"},"rateId":{"type":"string","description":"RateId is needed so that you can freeze the estimate from the /rate method for fixed-rate exchange. It is valid for 1 minute from the moment it is received."}},"required":["fromCurrency","toCurrency","fromNetwork","toNetwork","fromAmount","flow"]}}}} ``` ## The CreatePrivateExchangeRequestDto object ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"components":{"schemas":{"CreatePrivateExchangeRequestDto":{"type":"object","properties":{"fromCurrency":{"type":"string","description":"Source currency ticker"},"toCurrency":{"type":"string","description":"Target currency ticker"},"fromNetwork":{"type":"string","description":"Source network"},"toNetwork":{"type":"string","description":"Target network"},"fromAmount":{"type":"string","description":"Amount to exchange"},"memo":{"type":"string","description":"Extra ID for recipient (if required)"},"privateType":{"type":"string","description":"There are two types of private exchanges: 'privatePlus' - an intermediary network for XMR only; 'efficient' - the fastest and cheapest intermediary networks."},"address":{"type":"string","description":"Recipient address"},"refundAddress":{"type":"string","description":"Refund address"},"refundMemo":{"type":"string","description":"Extra ID for refund address (if required)"}},"required":["fromCurrency","toCurrency","fromNetwork","toNetwork","fromAmount"]}}}} ``` ## The SendDexApproveTransactionDto object ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"components":{"schemas":{"SendDexApproveTransactionDto":{"type":"object","properties":{"network":{"type":"string","description":"Network name"},"rawApproveTx":{"type":"string","description":"Raw approve transaction"}},"required":["network","rawApproveTx"]}}}} ``` ## The SendDexTransactionDto object ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"components":{"schemas":{"SendDexTransactionDto":{"type":"object","properties":{"account":{"type":"string","description":"Receiver address"},"amountFrom":{"type":"string","description":"Amount sent from sender"},"amountTo":{"type":"string","description":"Amount to be received"},"fromTokenAddress":{"type":"string","description":"Source token contract address"},"toTokenAddress":{"type":"string","description":"Target token contract address"},"network":{"type":"string","description":"Network name (Currently available: eth, sol, sui, sei, arbitrum, base, bsc, cchain, celo, linea, matic, op, sonic, uni)"},"commissionPercentage":{"type":"string","description":"Commission percentage"},"rawTx":{"type":"string","description":"Raw transaction data"},"hash":{"type":"string","description":"Transaction hash"},"to":{"type":"string","description":"Recipient address (again, for compatibility)"},"isExchange":{"type":"boolean","description":"If it is an approve transaction or any other transaction other than a swap, the flag must be false."}},"required":["account","amountFrom","amountTo","fromTokenAddress","toTokenAddress","network","commissionPercentage"]}}}} ``` ## The SwapDexTransactionDto object ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"components":{"schemas":{"SwapDexTransactionDto":{"type":"object","properties":{"account":{"type":"string","description":"Sender address"},"fromTokenAddress":{"type":"string","description":"Source token contract address"},"toTokenAddress":{"type":"string","description":"Target token contract address"},"amount":{"type":"string","description":"Amount to swap"},"slippage":{"type":"string","description":"Allowed slippage"},"referrerFee":{"type":"string","description":"Referrer fee"},"network":{"type":"string","description":"Network name (Currently available: eth, sol, sui, sei, arbitrum, base, bsc, cchain, celo, linea, matic, op, sonic, uni)"}},"required":["account","fromTokenAddress","toTokenAddress","amount","slippage","referrerFee","network"]}}}} ``` ## The DeFiCurrency object ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"components":{"schemas":{"DeFiCurrency":{"type":"object","properties":{"name":{"type":"string","description":"Full name of the token"},"address":{"type":"string","description":"Token contract address"},"decimals":{"type":"integer","description":"Number of decimal places for the token"},"symbol":{"type":"string","description":"Token symbol"},"network":{"type":"string","description":"Network ticker"},"enabled":{"type":"boolean","description":"Indicates if token is currently available for swaps"},"image":{"type":"string","description":"URL to the token icon"}}}}}} ``` ## The SwapDexInfo object ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"components":{"schemas":{"SwapDexInfo":{"type":"object","properties":{"name":{"type":"string","description":"DEX name"},"address":{"type":"string","description":"DEX contract address"},"fee":{"type":"number","description":"DEX fee percentage"},"percentage":{"type":"number","description":"Percentage of swap going through this DEX"}}}}}} ``` ## The SwapSubRoute object ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"components":{"schemas":{"SwapSubRoute":{"type":"object","properties":{"from":{"type":"string","description":"Source token address in this step"},"to":{"type":"string","description":"Target token address in this step"},"dexes":{"type":"array","items":{"$ref":"#/components/schemas/SwapDexInfo"},"description":"DEXes used in this swap step"}}},"SwapDexInfo":{"type":"object","properties":{"name":{"type":"string","description":"DEX name"},"address":{"type":"string","description":"DEX contract address"},"fee":{"type":"number","description":"DEX fee percentage"},"percentage":{"type":"number","description":"Percentage of swap going through this DEX"}}}}}} ``` ## The SwapRoute object ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"components":{"schemas":{"SwapRoute":{"type":"object","properties":{"percentage":{"type":"number","description":"Percentage of total swap using this route"},"subRoutes":{"type":"array","items":{"$ref":"#/components/schemas/SwapSubRoute"},"description":"Individual steps in the swap route"}}},"SwapSubRoute":{"type":"object","properties":{"from":{"type":"string","description":"Source token address in this step"},"to":{"type":"string","description":"Target token address in this step"},"dexes":{"type":"array","items":{"$ref":"#/components/schemas/SwapDexInfo"},"description":"DEXes used in this swap step"}}},"SwapDexInfo":{"type":"object","properties":{"name":{"type":"string","description":"DEX name"},"address":{"type":"string","description":"DEX contract address"},"fee":{"type":"number","description":"DEX fee percentage"},"percentage":{"type":"number","description":"Percentage of swap going through this DEX"}}}}}} ``` ## The SwapQuote object ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"components":{"schemas":{"SwapQuote":{"type":"object","properties":{"fromAmount":{"type":"string","description":"Amount to swap from"},"usdFromAmount":{"type":"string","description":"USD value of from amount"},"toAmount":{"type":"string","description":"Estimated amount to receive"},"usdToAmount":{"type":"string","description":"USD value of to amount"},"receivedAmount":{"type":"string","description":"Actual amount user will receive after fees"},"fee":{"type":"string","description":"Fee amount"},"routes":{"type":"array","items":{"$ref":"#/components/schemas/SwapRoute"},"description":"Swap routes with DEX details"},"priceImpact":{"type":"string","description":"Price impact percentage"}}},"SwapRoute":{"type":"object","properties":{"percentage":{"type":"number","description":"Percentage of total swap using this route"},"subRoutes":{"type":"array","items":{"$ref":"#/components/schemas/SwapSubRoute"},"description":"Individual steps in the swap route"}}},"SwapSubRoute":{"type":"object","properties":{"from":{"type":"string","description":"Source token address in this step"},"to":{"type":"string","description":"Target token address in this step"},"dexes":{"type":"array","items":{"$ref":"#/components/schemas/SwapDexInfo"},"description":"DEXes used in this swap step"}}},"SwapDexInfo":{"type":"object","properties":{"name":{"type":"string","description":"DEX name"},"address":{"type":"string","description":"DEX contract address"},"fee":{"type":"number","description":"DEX fee percentage"},"percentage":{"type":"number","description":"Percentage of swap going through this DEX"}}}}}} ``` ## The DexExchange object ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"components":{"schemas":{"DexExchange":{"type":"object","properties":{"id":{"type":"string","description":"Unique exchange identifier"},"created":{"type":"string","format":"date-time","description":"Exchange creation timestamp"},"updated":{"type":"string","format":"date-time","description":"Exchange last update timestamp"},"network":{"type":"string","description":"Network where exchange occurred"},"fromTokenAddress":{"type":"string","description":"Source token contract address"},"toTokenAddress":{"type":"string","description":"Target token contract address"},"amountFrom":{"type":"string","description":"Amount sent"},"amountTo":{"type":"string","description":"Amount received"},"addressFrom":{"type":"string","description":"Sender wallet address"},"addressTo":{"type":"string","nullable":true,"description":"Recipient wallet address"},"commissionPercentage":{"type":"string","description":"Commission percentage"},"status":{"type":"string","enum":["pending","confirming","finished","failed"],"description":"Exchange status"},"hash":{"type":"string","description":"Transaction hash"}}}}}} ``` ## The DexExchangeList object ```json {"openapi":"3.0.0","info":{"title":"Baltex Partner API","version":"1.0.0"},"components":{"schemas":{"DexExchangeList":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of exchanges"},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/DexExchange"},"description":"Array of DEX exchanges"}}},"DexExchange":{"type":"object","properties":{"id":{"type":"string","description":"Unique exchange identifier"},"created":{"type":"string","format":"date-time","description":"Exchange creation timestamp"},"updated":{"type":"string","format":"date-time","description":"Exchange last update timestamp"},"network":{"type":"string","description":"Network where exchange occurred"},"fromTokenAddress":{"type":"string","description":"Source token contract address"},"toTokenAddress":{"type":"string","description":"Target token contract address"},"amountFrom":{"type":"string","description":"Amount sent"},"amountTo":{"type":"string","description":"Amount received"},"addressFrom":{"type":"string","description":"Sender wallet address"},"addressTo":{"type":"string","nullable":true,"description":"Recipient wallet address"},"commissionPercentage":{"type":"string","description":"Commission percentage"},"status":{"type":"string","enum":["pending","confirming","finished","failed"],"description":"Exchange status"},"hash":{"type":"string","description":"Transaction hash"}}}}}} ``` # Baltex Protocol Last Updated: March 12, 2026 ### Abstract Baltex Protocol is the routing and execution layer behind Baltex’s existing partner-facing API stack (Cross‑Chain, Private Swaps, and DeFi). The protocol unifies liquidity access across three execution domains: * centralized exchange orderbooks * on‑chain AMMs/DEX ecosystems * non‑custodial swap providers Partners keep using the same methods—quote, create, and status—while Baltex Protocol expands the underlying routing graph to unlock more viable paths, broader pair coverage, and improved route availability. This document specifies the protocol architecture, routing model, execution lifecycle, privacy relay mechanics, and integration method frame aligned with the current Baltex documentation. ### # 1. Motivation Crypto liquidity is fragmented across chains, venues, and execution rails. A token may be liquid only on one DEX and one network, while the destination asset may exist only on its native chain. Conventional DEX aggregators cannot complete such swaps without manual bridging, multiple transactions, and external coordination. **Baltex Protocol** targets a single-step user experience: * Select Coin X → Coin Y * Receive deposit address or contract call data * Send Coin X * Receive Coin Y to the specified destination address All backend pathfinding and execution across liquidity sources is handled by the protocol.
# 2. Design Goals and Non‑Goals ### 2.1 Goals * Reachability: enable swaps across disconnected liquidity islands (isolated DEX tokens → native L1 assets). * Deterministic lifecycle: stable exchange states and structured progress metadata for partner UX and support. * Operational resilience: durable queues, retries, rate limiting, and graceful degradation under upstream failures. * Minimal integration surface: partners call the same quote/create/status methods across flows. * Privacy‑forward: no mandatory KYC/account flow; private mode provides a relay that breaks direct on‑chain linkage. ### 2.2 Non‑Goals * Trustless atomic cross‑chain swaps (e.g., HTLC-based) are not assumed. * Cryptographic proof of best execution is not assumed. * Censorship resistance guarantees are not assumed. * Base-layer privacy is not implied unless explicitly using private relay modes. # 3. Product Surface Baltex Protocol is not a new partner API category. It is the routing/execution system that powers the existing stack: * Standard Swaps: best‑rate routing across CEX/DEX liquidity. * Private Swaps: dual‑exchange flow with a Monero relay; single‑use deposit addresses; optional L2 paths supported. * DeFi (DEX) Swaps: direct, non‑custodial routing on supported chains with slippage controls. Protocol evolution expands route reachability (more venues, more edges, more candidate paths) while keeping the external method frame stable.
# 4. Architecture ### 4.1 Control Plane vs Data Plane Control plane components compute quotes and route plans from a normalised liquidity graph snapshot. Data plane components execute multi-leg plans and maintain the exchange lifecycle. ```mermaid flowchart LR subgraph CP["Control Plane"] A["API Gateway (x-api-key)"] B["Graph Service snapshot builder)"] C["Constraints & Policy (venue/limits/TTL)"] R["Routing Engine (k-best + scoring)"] A --> R B --> R C --> R end subgraph DP["Data Plane"] S["Swap/Exchange Service (state machine)"] Q[("Durable Queue")] E["Execution Orchestrator (idempotent logs)"] SS["State Store (swaps, legs, audit)"] RA["Recipient Address"] PA["Provider Adapter"] DEX["DEX Adapter"] CEX["CEX Adapter"] S --> Q --> E E --> SS E --> RA E --> PA E --> DEX E --> CEX end R -- "RoutePlan" --> S ``` Figure 1. Control plane vs data plane architecture. #### Components #### Control Plane | Component | Description | | ------------------------ | ---------------------------------------------------------------------------------------- | | **API Gateway** | Entry point for all requests. Authenticates via `x-api-key`. | | **Graph Service** | Builds snapshots of available liquidity venues and token graphs. | | **Constraints & Policy** | Enforces venue restrictions, size limits, and TTL rules. | | **Routing Engine** | Computes optimal routes using k-best path algorithm with scoring. Outputs a `RoutePlan`. | #### Data Plane | Component | Description | | -------------------------- | ---------------------------------------------------------------------------------- | | **Swap/Exchange Service** | Receives the `RoutePlan` and manages swap lifecycle as a state machine. | | **Durable Queue** | Persists swap jobs to ensure reliable, at-least-once delivery to the orchestrator. | | **Execution Orchestrator** | Executes swap legs idempotently, coordinating across adapters and recording logs. | | **State Store** | Persists swap state, individual legs, and a full audit trail. | | **Recipient Address** | Resolves and validates the destination address for the swap output. | | **Provider Adapter** | Generic adapter interface for liquidity providers. | | **DEX Adapter** | Adapter for decentralized exchange integrations. | | **CEX Adapter** | Adapter for centralized exchange integrations. | *** #### Data Flow 1. A request hits the **API Gateway** and is authenticated. 2. The **Graph Service** provides a live liquidity snapshot; **Constraints & Policy** applies limits. 3. The **Routing Engine** computes the best route and emits a `RoutePlan`. 4. The `RoutePlan` is handed to the **Swap/Exchange Service**, which transitions through states. 5. Jobs are durably enqueued in the **Durable Queue**. 6. The **Execution Orchestrator** picks up jobs and dispatches legs to the appropriate adapter (Provider, DEX, or CEX). 7. All state transitions and results are written to the **State Store** for auditability. # 5. Liquidity Graph Model Baltex Protocol represents liquidity access as a directed weighted multigraph. Vertices represent asset states on networks (optionally decorated with venue context), and edges represent executable transformations (DEX swap, CEX trade, provider swap, withdraw/transfer, relay). ```mermaid flowchart LR VS["Venue State (Uniswap V3 Pool)"] A1["Asset State (PEPE@ETH)"] A2["Asset State (USDC@ETH)"] CM["CEX Market (USDC/ZEC)"] RL["Relay Asset (Monero L1)"] A3["Asset State (ZEC@ZEC)"] VS -.-> A1 A1 -- "DEX_SWAP" --> A2 A2 -- "CEX_TRADE" --> CM CM -- "WITHDRAW" --> A3 A1 -- "RELAY (private)" --> RL RL -- "OUTTAKE" --> A3 ``` Figure 2. Simplified liquidity graph taxonomy (illustrative).
#### Components
ComponentDescription
Venue State (Uniswap V3 Pool)Liquidity venue providing the on-chain DEX swap context.
Asset State (PEPE@ETH)Initial asset — PEPE held on the Ethereum network.
Asset State (USDC@ETH)Intermediate asset after DEX swap — USDC on Ethereum.
CEX Market (USDC/PEPE)Centralized exchange market used to trade USDC into the withdrawal path.
Relay Asset (RAND L1)Private relay bridge asset on Monero L1 network, used for the off-exchange path.
Asset State (ZEC@ZEC)Final output asset — ZEC on the Zcash network.
*** #### Execution Paths #### Path 1 — DEX Route
StepActionDescription
1DEX_SWAPSwap PEPE → USDC on Uniswap V3 (Ethereum).
2CEX_TRADETrade USDC on a CEX market (USDT/ZEC pair).
3WITHDRAWWithdraw from CEX to destination as ZEC@ZEC.
#### Path 2 — Private Relay Route
StepActionDescription
1RELAY (private)Route PEPE@ETH through a private L1 relay bridge.
2OUTTAKEExtract the bridged value as ZEC@ZEC on the Zcash network.
*** #### Notes * Both paths originate from **PEPE\@ETH** and terminate at **ZEC\@ZEC**. * The **DEX route** is the public, on-chain path with higher transparency. * The **Relay route** is a private, off-chain path optimized for privacy. * The **Venue State** (Uniswap V3) is only relevant for the DEX path. ### 5.1 Edge attributes (normalized) Each edge is evaluated under constraints and costs, typically including: * limits: min/max amount supported * fee model: venue fees + network fees (estimated) * slippage model: for AMM edges (depth/price impact) * latency model: expected time-to-complete distribution (p50/p90/p99) * reliability score: historical success rate for the edge/venue # 6. Routing & Quote Generation Quotes are computed from a graph snapshot G\_t. The router generates k candidate routes, filters by hard constraints, estimates output ranges, and scores candidates to select an optimal RoutePlan. ```mermaid flowchart LR I["Input (X→Y, amount, constraints)"] LS["Load Snapshot G_t"] GK["Generate k Candidates"] ES["Estimate (out, fees, limits)"] SC["Score (cost/speed/success)"] SB["Select Best RoutePlan"] RQ["Return Quote (+ TTL)"] I --> LS --> GK --> ES --> SC --> SB --> RQ ``` #### Pipeline Stages
#StageDescription
1InputReceives the swap intent: source asset X, destination asset Y, amount, and any caller constraints.
2Load Snapshot G_tLoads the latest graph snapshot of available venues, liquidity, and token pairs at time t.
3Generate k CandidatesRuns k-best path enumeration over the graph to produce a set of candidate routes.
4EstimateFor each candidate, computes expected output amount, fees, and checks against venue limits.
5ScoreRanks candidates using a composite score across cost, execution speed, and success probability.
6Select Best RoutePlanPicks the highest-scoring candidate and assembles it into a structured RoutePlan.
7Return QuoteReturns the quote to the caller with a TTL, after which the RoutePlan is considered stale.
*** #### Input / Output #### Input
FieldDescription
X → YSource and destination asset pair (e.g. USDT@ETH → ZEC@ZEC).
amountThe input amount to be swapped.
constraintsCaller-defined constraints: venue whitelist/blacklist, max fees, deadlines, etc.
#### Output
FieldDescription
RoutePlanThe fully resolved execution plan with ordered legs, venues, and adapters.
TTLExpiry timestamp after which the quote must be re-requested.
*** #### Notes * The snapshot `G_t` is immutable per pipeline run — no live data is fetched mid-execution. * The scoring function weights **cost**, **speed**, and **success rate** and can be tuned per deployment. * If no valid candidate passes the estimation step, the pipeline returns an empty quote with a reason code. ### 6.1 Fixed-rate vs Floating Baltex supports standard (floating) quotes and fixed-rate quotes. Fixed-rate quotes reserve inventory for a limited time; for Cross‑Chain fixed-rate execution, the rateId returned by /rate must be supplied to /exchange and is valid for 1 minute. ### 6.2 Scoring (reference form) A practical scoring objective is multi-factor and can be expressed as: expected\_out − total\_fees − slippage\_risk − reliability\_penalty − time\_penalty. Baltex’s quote engine considers network fees, venue depth, and slippage to identify the lowest-cost viable route. \
# 7. Execution & Lifecycle ### 7.1 Cross‑Chain exchange statuses ```mermaid stateDiagram-v2 [*] --> pending pending --> confirming confirming --> exchanging exchanging --> sending sending --> finished confirming --> failed exchanging --> failed sending --> failed confirming --> refunded exchanging --> refunded sending --> refunded ``` Figure 4. Cross‑Chain exchange status state machine. #### States
StateTypeDescription
pendingTransientSwap awaiting of the inbound deposit.
confirmingTransientInbound transaction detected; waiting for sufficient block confirmations.
exchangingTransientFunds confirmed; executing the swap across venues (DEX/CEX/relay).
sendingTransientSwap complete; outbound transaction is being broadcast to the destination chain.
finishedTerminalOutbound transaction confirmed. Swap successfully completed.
failedTerminalAn unrecoverable error occurred. No refund issued.
refundedTerminalSwap could not be completed; input funds returned to the sender.
*** #### Transitions
FromToTrigger
pendingconfirmingInbound deposit detected on-chain.
confirmingexchangingRequired block confirmations reached.
exchangingsendingSwap execution succeeded across all legs.
sendingfinishedOutbound transaction confirmed on destination chain.
confirming → sendingfailedUnrecoverable error at any stage (e.g. liquidity failure, timeout).
confirming→ sendingrefundedSwap aborted; input funds returned to sender.
*** #### Notes * `failed` and `refunded` are **reachable from any transient state** — any stage of the pipeline can trigger them. * `finished`, `failed`, and `refunded` are all **terminal** — no further transitions occur once reached. * Consumers should poll or subscribe to status updates and treat any terminal state as a final signal. ### 7.2 Execution orchestration (multi-leg) ```mermaid flowchart TD START["Leg_i ready"] PC["Pre-checks (confirmations, limits)"] EX["Execute via adapter (DEX/CEX/provider)"] CR["Confirm / reconcile (tx, order, provider status)"] RT["Retry (backoff) (retryable errors)"] FS["Fail swap (terminal error)"] NX["Persist + enqueue Leg_{i+1}"] START --> PC --> EX --> CR CR -- "retryable" --> RT CR -- "terminal" --> FS CR -- "success" --> NX RT -. "retry" .-> EX ``` #### Stages
#StageDescription
1Leg_i readyThe orchestrator dequeues Leg_i and begins execution.
2Pre-checksValidates confirmations, balance availability, and venue limits before touching any adapter.
3Execute via adapterDispatches the leg to the appropriate adapter: DEX, CEX, or provider.
4Confirm / reconcilePolls or receives a callback to verify the tx, order fill, or provider status.
5aRetry (backoff)On retryable errors, waits with exponential backoff and re-enters the adapter execution.
5bFail swapOn terminal errors, marks the swap as failed and halts the pipeline.
5cPersist + enqueue Leg_{i+1}On success, persists the leg result to the State Store and enqueues the next leg.
*** #### Outcome Branches
OutcomeConditionNext Action
retryableTransient error (e.g. timeout, rate limit, partial fill).Back off and re-execute via adapter.
terminalUnrecoverable error (e.g. insufficient funds, invalid address).Fail the swap immediately.
successLeg fully confirmed and reconciled.Persist result and enqueue Leg_{i+1}.
*** #### Notes * The retry loop re-enters at the **adapter execution** step, not at pre-checks — pre-checks are only run once per leg. * Retry uses **exponential backoff** to avoid thundering-herd pressure on venues. * If `Leg_i` is the final leg, `success` triggers swap completion (`finished`) rather than enqueuing a next leg. * All outcomes are written idempotently to the **State Store** to support crash recovery. ### 7.3 Progress metadata Status responses include an exchanges\[] array of sub-operations with amounts received, hashes, timestamps, and per-operation status. This enables partners to build debuggable progress UIs and support tooling.
# 8. Transaction Types ### 8.1 Standard Swaps Best-rate routing across CEX/DEX liquidity. Quotes are computed from integrated venues and executed through the optimal path. *** ### 8.2 Private Swaps Enhanced privacy via a dual-exchange flow with a randomized Layer-1 relay. Intake and outtake occur at different venues; single-use deposit addresses are used. ```mermaid flowchart LR A["Exchange A (Intake) • Single-use deposit • AML screening • Convert to relay asset"] R["Randomized L1 Relay • Relay asset transfer • Breaks deterministic link"] B["Exchange B (Outtake) • AML screening • Convert to output • Payout to recipient"] A -- "Relay asset" --> R R -- "Relay asset" --> B ``` > **Figure 6.** Private swaps: intake → randomized L1 relay → outtake. *** ### 8.3 Why the Privacy Relay Works (Mechanics) * **Record segregation:** intake and outtake maintain separate records (sender vs receiver), preventing a single party from reconstructing the full path. * **Randomized L1 intermediary:** the relay asset breaks deterministic chain analysis between input and output. * **Single-use addresses:** ephemeral deposit addresses reduce address reuse heuristics. *** ### 8.4 DeFi (DEX) Swaps Direct, non-custodial routing on supported chains and AMMs with explicit slippage controls. Privacy-sensitive users can combine DeFi swaps with private flows before/after the on-chain leg. # 9. Integration Method Frame (Current Stack) Baltex Protocol keeps partner integrations stable. The protocol expands the underlying route graph; the external methods and schemas remain consistent. *** ### 9.1 Authentication Partner endpoints require an API key supplied via the `x-api-key` header. *** ### 9.2 Cross-Chain API (Summary)
MethodPathPurposeNotes
GET/v1/cross-chain/available-currenciesDiscover supported currencies/networks.Includes address regex, explorers, confirmations, fixed-rate support.
GET/v1/cross-chain/rateQuote a standard or fixed-rate exchange.flow=standard|fixed-rate; amount optional.
GET/v1/cross-chain/rate/privateQuote a private exchange.Requires privateType.
POST/v1/cross-chain/exchangeCreate standard exchange.flow required; rateId required for fixed-rate (valid 1 minute).
POST/v1/cross-chain/exchange/privateCreate private exchange.privateType: privatePlus (XMR only) or efficient (fast/cheap relay).
GET/v1/cross-chain/exchange/statusGet exchange status by id.Wrapper for standard/private status.
GET/v1/cross-chain/exchange/listList exchanges (last 24h) with filters.Filter by status, networks, exchangeType.
## 9.3 DeFi API (Summary) Currently documented DeFi networks: `eth`, `sol`, `sui`, `sei`, `arbitrum`, `base`, `bsc`, `cchain`, `celo`, `linea`, `matic`, `op`, `sonic`, `uni`. ***
MethodPathPurposeNotes
GET/v1/defi/currency/infoResolve token metadata by network + address.Returns token info if exists.
GET/v1/defi/available-currenciesList tokens for a network.Supports page/limit pagination; network required.
GET/v1/defi/quoteQuote an on-chain swap route.Requires network, fromTokenAddress, toTokenAddress, amount, slippage, referrerFee.
POST/v1/defi/transaction/swapBuild a transaction hash to sign.Returns tx hash from provided data.
POST/v1/defi/send/approveBroadcast approval tx (if needed).Partner provides signed tx payload.
POST/v1/defi/send/swapBroadcast swap tx.Partner provides signed tx payload.
GET/v1/defi/exchange/listList DEX exchanges (last 24h) with filters.Filter by status, fromToken, toToken, network.
## 9.4 End-to-End Sequence (Concept) Across flows, the partner frame remains: `quote` → `create` → `user deposit/sign` → `status until terminal`. *** ### Sequence Diagram ```mermaid sequenceDiagram participant P as Partner/UI participant A as Baltex API participant R as Router participant E as Executor participant V as Venues P->>A: GET /rate or /defi/quote A->>R: compute best route R-->>A: quote response A-->>P: quote response P->>A: POST /exchange or /defi/transaction/swap A->>E: create swap/exchange + lock plan E->>V: execute legs V-->>E: fills/txs P->>A: GET /exchange/status or /defi/exchange/list A-->>P: status until terminal ``` > **Figure 7.** Unified partner interaction sequence (Cross-Chain + DeFi). *** ### Interaction Steps | # | Actor | Call | Description | | - | ----------------------- | ----------------------------------------------- | ------------------------------------------------------ | | 1 | Partner/UI → Baltex API | `GET /rate` or `/defi/quote` | Request a quote for the desired swap. | | 2 | Baltex API → Router | — | Internally computes the best route. | | 3 | Baltex API → Partner/UI | quote response | Returns quote with rate, fees, and TTL. | | 4 | Partner/UI → Baltex API | `POST /exchange` or `/defi/transaction/swap` | Creates the exchange and locks the plan. | | 5 | Baltex API → Executor | create swap + lock plan | Hands off to the executor for leg dispatch. | | 6 | Executor → Venues | execute legs | Dispatches fills and transactions to liquidity venues. | | 7 | Partner/UI → Baltex API | `GET /exchange/status` or `/defi/exchange/list` | Polls status until a terminal state is reached. | *** ### Notes * The partner frame is **identical for Cross-Chain and DeFi** flows — only the endpoint paths differ. * The **Router** is internal to Baltex API; partners never call it directly. * Step 7 (status polling) should continue until a terminal state (`finished`, `failed`, or `refunded`) is returned. # 10. Compliance & Risk Controls Baltex operates with a risk-based compliance approach: * **Sanctions/geo controls:** access restrictions for sanctioned jurisdictions and TOR egress points where required. * **Partner screening:** integrated partners conduct AML screening, sanctions checks, and ongoing compliance reviews. * **Record separation:** intake and outtake exchanges maintain separate records (sender vs receiver). * **Mixer policy:** private flows are transaction relays and are not custodial mixers. Fiat on/off-ramps, where available, are facilitated by third-party services and governed by their own terms and policies. # 11. Security Considerations (Implementation Checklist) * [ ] Key management for venue adapter credentials (KMS/HSM recommended). * [ ] Deposit confirmation thresholds per network (use confirmations from `available-currencies` metadata). * [ ] Strict address validation (`regexAddress` and memo requirements where applicable). * [ ] Idempotency for create-order requests to prevent duplicates. * [ ] Retry classification (retryable vs terminal) to avoid double-execution. * [ ] Rate limiting and abuse controls per partner key. * [ ] Audit-grade logging with sensitive data minimization/redaction. # 12. Data Model (Reference) The protocol can be modeled with a small set of persistent entities: Swap/Exchange, RoutePlan, Leg, and Asset metadata. *** ### Entity Diagram ```mermaid erDiagram SwapExchange { string id string type "standard | private | defi" string status datetime created object request "from/to, networks, amount" object deposit_instructions string recipient } RoutePlan { string swap_id string snapshot_id array legs number score number ttl } Leg { string leg_id string swap_id string kind "DEX | CEX | provider | relay" string status object external_refs object amounts object timestamps } Asset { string ticker string address string network number decimals string regexAddress array explorers } SwapExchange ||--|| RoutePlan : "1:1" RoutePlan ||--|{ Leg : "1:N" SwapExchange ||--|{ Leg : "1:N" SwapExchange }|--|| Asset : "uses" ``` > **Figure 8.** Reference data model (Swap/Exchange ↔ RoutePlan ↔ Leg). *** ### Entities #### SwapExchange
FieldTypeDescription
idstringUnique exchange identifier.
typeenumstandard, private, or defi.
statusenumCurrent state in the exchange lifecycle.
createddatetimeTimestamp of exchange creation.
requestobjectSwap intent: from/to assets, networks, amount.
deposit_instructionsobjectAddress and memo for the user's inbound deposit.
recipientstringDestination address for the output asset.
#### RoutePlan
FieldTypeDescription
swap_idstringReference to the parent SwapExchange.
snapshot_idstringGraph snapshot used to compute this plan.
legsarrayOrdered list of leg references.
scorenumberComposite score from the routing engine.
ttlnumberExpiry time; plan is stale after this.
#### Leg | Field | Type | Description | | --------------- | ------ | --------------------------------------------- | | `leg_id` | string | Unique leg identifier. | | `swap_id` | string | Reference to the parent SwapExchange. | | `kind` | enum | `DEX`, `CEX`, `provider`, or `relay`. | | `status` | enum | Current execution state of this leg. | | `external_refs` | object | Tx hashes, order IDs, or provider references. | | `amounts` | object | Input/output amounts and fees for this leg. | | `timestamps` | object | Created, updated, and confirmed timestamps. | #### Asset | Field | Type | Description | | -------------- | ------ | ------------------------------------------- | | `ticker` | string | Asset symbol (e.g. `USDT`). | | `address` | string | Contract or native address on the network. | | `network` | string | Network identifier (e.g. `eth`, `sol`). | | `decimals` | number | Token decimal precision. | | `regexAddress` | string | Validation pattern for recipient addresses. | | `explorers` | array | Block explorer URLs for this network. | *** ### Relationships | Relationship | Cardinality | Description | | ------------------------ | ----------- | -------------------------------------------------------------- | | SwapExchange → RoutePlan | 1:1 | Each exchange has exactly one locked route plan. | | RoutePlan → Leg | 1:N | A route plan is composed of one or more ordered legs. | | SwapExchange → Leg | 1:N | A swap directly references all its legs for status tracking. | | SwapExchange → Asset | uses | Exchange references Asset metadata for validation and display. | # 13. Operational Metrics (Illustrative) The following charts are illustrative examples of the metrics typically tracked for routing and execution reliability. Replace with production measurements before public release. *** ### Time-to-Settlement Distribution The chart below shows the cumulative distribution function (CDF) of swap settlement times. It illustrates that the majority of swaps settle within the first 30 seconds, with the distribution approaching 1.0 by \~2 minutes. ```mermaid xychart-beta title "Illustrative time-to-settlement distribution" x-axis "Time to settlement (minutes)" [0.10, 0.25, 0.40, 0.50, 0.60, 0.75, 1.00, 1.25, 1.50, 1.75, 2.00] y-axis "CDF" 0 --> 1 line [0.00, 0.62, 0.82, 0.90, 0.94, 0.96, 0.98, 0.99, 0.995, 0.998, 1.00] ``` > **Figure 9.** Illustrative time-to-settlement CDF (example only). *** ### Completion Rate vs Hop Count The chart below illustrates how swap completion rate decreases as the number of execution legs (hops) increases. Single-leg routes achieve near-perfect completion; 6-leg routes drop to \~93%. mermaid ```mermaid xychart-beta title "Illustrative completion rate vs hop count" x-axis "Hop count (legs)" [1, 2, 3, 4, 5, 6] y-axis "Completion rate" 0.85 --> 1.00 line [0.995, 0.991, 0.985, 0.971, 0.955, 0.930] ``` > **Figure 10.** Illustrative completion rate vs hop count (example only). # 14. Protocol Evolution: Expanded Route Reachability Baltex Protocol extends route reachability by expanding the underlying liquidity graph: * **More venue adapters and liquidity sources:** additional CEX/DEX/provider edges added to the route graph. * **More candidate routes per request:** k-best search runs over a larger graph, surfacing more viable paths. * **Improved fallback and viability filtering:** better handling of venue constraints ensures only executable routes are scored and returned. Partner integrations remain stable: the same `quote`/`create`/`status` methods are used; the protocol primarily changes the set of routable pairs and the quality/availability of routes. # Affiliate Program Terms ## 1.Introduction These Affiliate Program Terms (“**Terms**”) form part of the Baltex Terms of Service and govern your participation in the **Baltex Affiliate Program** (the “**Program**”). By joining the Program, you agree to these Terms. If you do not agree, do not enroll. * **About Baltex.** Baltex provides non-custodial crypto swap tooling and APIs (cross-chain, private swaps, and DEX routing). Baltex is not a custodian and does not hold user funds. ## 2. Definitions * **Affiliate / you** — the individual or entity enrolled in the Program. * **Affiliate Link** — a unique URL or key that attributes eligible transactions to you. * **Tools** — Baltex promotional and technical assets (widgets, banners, APIs, SDKs) that embed or refer users to Baltex. * **Referral / Referred User** — a user who lands via your Affiliate Link and completes an **Eligible Transaction**. * **Eligible Transaction** — a completed, irreversible swap/order that (i) is tracked to your Affiliate Link, (ii) is not cancelled/refunded/charged back, and (iii) is compliant with these Terms and applicable law. ## 3. Enrollment 3.1 **Application.** Apply through the Baltex partner portal or the channel provided by Baltex. Baltex may approve or reject applications at its discretion.\ 3.2 **Account.** You must provide accurate details and keep credentials secure.\ 3.3 **Territory/Jurisdictions.** You may not enroll from, or promote into, prohibited jurisdictions or to sanctioned persons.\ 3.4 **Program Changes.** Baltex may modify, suspend, or terminate the Program at any time on notice. ## 4. Affiliate Tools & Implementation 4.1 **Permitted use.** You may use Baltex Links, widgets, and API endpoints solely to promote Baltex and route users to supported flows. Do not modify Tools beyond configuration options we provide.\ 4.2 **Brand usage.** Baltex grants a limited, revocable, non-exclusive, non-transferable license to use its name/logo solely to promote Baltex under these Terms and any brand guidelines we share. No ownership or broader rights are granted.\ 4.3 **No implied partnership.** Do not present yourself as Baltex, our agent, or as having power to bind us. All messaging must accurately describe Baltex’s non-custodial nature. ## 5. Tracking, Attribution & Cookies 5.1 **How tracking works.** Attribution relies on your Affiliate Link (and, where applicable, cookies or session identifiers).\ 5.2 **Attribution window.** Unless otherwise agreed, the last-click attribution window is **\[24 hours]**. Transactions completed after the window or without valid tracking are not eligible.\ 5.3 **Disputes.** Baltex’s tracking records control in case of attribution discrepancies. ## 6. Commission & Payouts 6.1 **Commission.** For each Eligible Transaction, you earn **\[Commission Rate — e.g., 0.4% of Baltex** Cross Chain **Flow and 0.1% for DeFi Flow]**. The exact rate and covered products are stated in your partner dashboard or IO (insertion order). (Commission models and single-tier structures are common in crypto affiliate programs.) \ 6.2 **Exclusions/Adjustments.** No commission is due on: cancelled, refunded, reversed, fraudulent, self-referred, or non-compliant transactions; transactions outside the attribution window; traffic that breaches these Terms. Baltex may claw back or offset prior payouts for later reversals or fraud.\ 6.3 **Minimum payout & schedule.** Baltex pays in **\[Payout Asset(s): e.g., BTC]**, once your accrued, approved balance exceeds **\[Minimum Payout — e.g., 0.0005 BTC]**. Lower balances roll over. (Low crypto-denominated payout thresholds are typical in the sector.)\ 6.4 **KYC/Tax.** Baltex may require Affiliate KYC/AML screening before any payout and withhold payments where legally required. You are responsible for your taxes. ## 7. Affiliate Conduct (What’s OK / Not OK) 7.1 **You must:** * comply with all laws (marketing, privacy, sanctions, consumer protection), these Terms, and Baltex Terms/Privacy; * make only accurate, lawful claims about Baltex; * disclose affiliate relationships where required (e.g., #ad/#affiliate). \ 7.2 **You must not:** * spam, use forced clicks, cookie stuffing, adware, toolbars, or deceptive overlays; * buy ads on **Baltex-branded** keywords or bid on confusingly similar terms without Baltex’s written consent; * misrepresent features, fabricate “guaranteed earnings,” or provide financial/investment advice; * impersonate Baltex, simulate our UI, or falsely claim partnership/endorsement; * promote Baltex on illegal, hateful, adult, or high-risk properties; * target prohibited jurisdictions or sanctioned persons; * incentivize trades in ways that violate law or these Terms (airdrops/scams, wash trades, self-referrals).\ (Brand-keyword restrictions and harmful-activity bans are standard in affiliate terms.) ## 8. Content & IP 8.1 **Quality standards.** Content must be truthful, up-to-date, and not misleading. Remove or update content upon Baltex’s reasonable request.\ 8.2 **IP ownership.** All Baltex IP remains Baltex’s. You receive no rights other than the limited license in §4.2.\ 8.3 **Take-downs.** Baltex may request removal of infringing or non-compliant content; you will act promptly. ## 9. Privacy & Data Protection 9.1 **Controllers.** You act as an independent controller for your audience and must provide a compliant privacy notice and obtain all required consents (e.g., cookies).\ 9.2 **Sharing.** Do not collect or share personal data with Baltex beyond what the Tools require. Handle all data per applicable privacy laws and Baltex’s Privacy Policy. ## 10. Compliance, Fraud & Audit 10.1 **Anti-fraud.** Baltex may review traffic sources, click-paths, and conversions. We may withhold or adjust commissions for fraud, violation, or anomalous patterns.\ 10.2 **Audit cooperation.** On request, provide reasonable logs or evidence of traffic sources and placements.\ 10.3 **Suspension.** We may suspend links/Tools and hold payments during an investigation. ## 11. Term & Termination 11.1 **Convenience.** Either party may terminate for convenience with **\[7]** days’ written notice.\ 11.2 **For cause.** Baltex may terminate immediately for breach, fraud, legal risk, or platform harm.\ 11.3 **Effect.** After termination, stop using Baltex brand/Tools and remove Affiliate Links. Approved, undisputed commissions accrued up to termination will be paid on the next cycle (subject to lawful holds, chargebacks, or fraud review). Sections **8–15** survive. ## 12. Disclaimers Baltex provides the Program and Tools **“AS IS”** and **“AS AVAILABLE.”** We do not guarantee specific earnings, conversion rates, uptime, or uninterrupted tracking. ## 13. Limitation of Liability To the extent permitted by law, Baltex is **not liable** for indirect, incidental, special, consequential, exemplary, or punitive damages; or lost profits/revenue/data; and our aggregate liability related to the Program will not exceed the **commissions paid to you in the 12 months** before the claim. ## 14. Indemnification You will indemnify Baltex, affiliates, officers, employees, and agents against **third-party claims** (and reasonable legal costs) arising from your (i) breach of these Terms, law, or third-party rights; (ii) non-compliant marketing; or (iii) misuse of the Tools—except to the extent caused by Baltex’s willful misconduct or gross negligence. ## 15. Confidentiality Non-public information we share (dashboards, rates, roadmaps, agreements) is confidential; use it only for the Program and protect it with reasonable care. ## 16. Governing Law & Venue These Terms are governed by the laws of **Costa Rica**. Courts of Costa Rica shall have exclusive jurisdiction, unless mandatory law provides otherwise. ## 17. Changes We may update these Terms; changes take effect on posting unless a later date is stated. Continued participation after changes constitutes acceptance. ## 18. Contact \