{"openapi":"3.1.0","info":{"title":"fragment-api.io","description":"Provider API for Telegram Stars and Premium via Fragment. Pay with **TON** or **USDT TON** from merchant balance.\n\nHuman docs: https://doc.fragment-api.io\n\nAuth: `X-API-Key: <your_key>`","version":"1.0.0"},"paths":{"/api/balance":{"get":{"tags":["merchants"],"summary":"Get Balance","operationId":"get_balance_api_balance_get","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantBalance"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/api/prices":{"get":{"tags":["prices"],"summary":"Get Price","operationId":"get_price_api_prices_get","parameters":[{"name":"product_type","in":"query","required":true,"schema":{"type":"string","title":"Product Type"}},{"name":"quantity","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quantity"}},{"name":"payment_method","in":"query","required":false,"schema":{"enum":["ton","usdt_ton"],"type":"string","default":"usdt_ton","title":"Payment Method"}},{"name":"recipient","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Required for live Fragment quote","title":"Recipient"},"description":"Required for live Fragment quote"},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/api/prices/list":{"get":{"tags":["prices"],"summary":"Get Price List","operationId":"get_price_list_api_prices_list_get","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PriceResponse"},"title":"Response Get Price List Api Prices List Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/api/search":{"post":{"tags":["search"],"summary":"Search Recipient","operationId":"search_recipient_api_search_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/api/purchase":{"post":{"tags":["purchases"],"summary":"Purchase","operationId":"purchase_api_purchase_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/api/test/purchase":{"post":{"tags":["purchases"],"summary":"Test Purchase","operationId":"test_purchase_api_test_purchase_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/api/purchase/by-idempotency-key/{key}":{"get":{"tags":["purchases"],"summary":"Purchase By Idempotency","operationId":"purchase_by_idempotency_api_purchase_by_idempotency_key__key__get","parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string","title":"Key"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transaction"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/api/purchase/transaction/{transaction_id}":{"get":{"tags":["purchases"],"summary":"Purchase By Id","operationId":"purchase_by_id_api_purchase_transaction__transaction_id__get","parameters":[{"name":"transaction_id","in":"path","required":true,"schema":{"type":"string","title":"Transaction Id"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transaction"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/api/purchase/history":{"get":{"tags":["purchases"],"summary":"Purchase History","operationId":"purchase_history_api_purchase_history_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseHistoryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/merchants/topup":{"post":{"tags":["merchants"],"summary":"Topup","operationId":"topup_merchants_topup_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopUpRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopUpResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/health":{"get":{"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/balance":{"get":{"tags":["legacy"],"summary":"Balance V1","operationId":"balance_v1_v1_balance_get","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/stars/search":{"post":{"tags":["legacy"],"summary":"Stars Search V1","operationId":"stars_search_v1_v1_stars_search_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/stars/quote":{"post":{"tags":["legacy"],"summary":"Stars Quote V1","operationId":"stars_quote_v1_v1_stars_quote_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/stars/purchase":{"post":{"tags":["legacy"],"summary":"Stars Purchase V1","operationId":"stars_purchase_v1_v1_stars_purchase_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/orders/{order_id}":{"get":{"tags":["legacy"],"summary":"Get Order V1","operationId":"get_order_v1_v1_orders__order_id__get","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","title":"Order Id"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/withdraw":{"post":{"tags":["legacy"],"summary":"Withdraw V1","operationId":"withdraw_v1_v1_withdraw_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithdrawBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"MerchantBalance":{"properties":{"ton_balance":{"type":"number","title":"Ton Balance"},"usdt_balance":{"type":"number","title":"Usdt Balance"},"deposit_address":{"type":"string","title":"Deposit Address"},"usdt_jetton_master":{"type":"string","title":"Usdt Jetton Master","description":"Official USDT jetton contract on TON"},"usdt_jetton_master_suffix":{"type":"string","title":"Usdt Jetton Master Suffix","description":"Last chars of USDT contract — verify in wallet before send"},"mainnet_balance":{"type":"number","title":"Mainnet Balance","description":"TON balance (compat field)"},"testnet_balance":{"type":"number","title":"Testnet Balance","default":0.0}},"type":"object","required":["ton_balance","usdt_balance","deposit_address","usdt_jetton_master","usdt_jetton_master_suffix","mainnet_balance"],"title":"MerchantBalance"},"PriceResponse":{"properties":{"product_type":{"type":"string","title":"Product Type"},"item_name":{"type":"string","title":"Item Name"},"price":{"type":"number","title":"Price"},"gas_fee":{"type":"number","title":"Gas Fee"},"total":{"type":"number","title":"Total"},"currency":{"type":"string","title":"Currency","description":"ton or usdt"},"payment_method":{"type":"string","title":"Payment Method"}},"type":"object","required":["product_type","item_name","price","gas_fee","total","currency","payment_method"],"title":"PriceResponse"},"PurchaseBody":{"properties":{"username":{"type":"string","maxLength":64,"minLength":5,"title":"Username"},"quantity":{"type":"integer","maximum":1000000.0,"minimum":50.0,"title":"Quantity"},"asset":{"type":"string","pattern":"^(ton|usdt)$","title":"Asset","default":"usdt"},"idempotency_key":{"type":"string","maxLength":128,"minLength":1,"title":"Idempotency Key"}},"type":"object","required":["username","quantity","idempotency_key"],"title":"PurchaseBody"},"PurchaseHistoryResponse":{"properties":{"transactions":{"items":{"$ref":"#/components/schemas/Transaction"},"type":"array","title":"Transactions"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"}},"type":"object","required":["transactions","limit","offset"],"title":"PurchaseHistoryResponse"},"PurchaseRequest":{"properties":{"product_type":{"type":"string","title":"Product Type"},"recipient":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recipient"},"quantity":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quantity"},"payment_method":{"anyOf":[{"type":"string","enum":["ton","usdt_ton"]},{"type":"null"}],"title":"Payment Method","default":"usdt_ton"},"idempotency_key":{"type":"string","maxLength":128,"minLength":1,"title":"Idempotency Key"}},"type":"object","required":["product_type","idempotency_key"],"title":"PurchaseRequest"},"PurchaseResponse":{"properties":{"transaction_id":{"type":"string","title":"Transaction Id"},"status":{"type":"string","title":"Status"},"product_type":{"type":"string","title":"Product Type"},"recipient":{"type":"string","title":"Recipient"},"item_name":{"type":"string","title":"Item Name"},"item_price":{"type":"number","title":"Item Price"},"item_quantity":{"type":"integer","title":"Item Quantity"},"payment_method":{"type":"string","title":"Payment Method"},"created_at":{"type":"string","title":"Created At"},"ton_tx_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ton Tx Id"}},"type":"object","required":["transaction_id","status","product_type","recipient","item_name","item_price","item_quantity","payment_method","created_at"],"title":"PurchaseResponse"},"SearchBody":{"properties":{"username":{"type":"string","maxLength":64,"minLength":5,"title":"Username"}},"type":"object","required":["username"],"title":"SearchBody"},"SearchFound":{"properties":{"recipient":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recipient"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"photo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Photo"},"myself":{"type":"boolean","title":"Myself","default":false}},"type":"object","title":"SearchFound"},"SearchRequest":{"properties":{"product_type":{"type":"string","title":"Product Type"},"query":{"type":"string","title":"Query"},"quantity":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quantity"},"payment_method":{"anyOf":[{"type":"string","enum":["ton","usdt_ton"]},{"type":"null"}],"title":"Payment Method"}},"type":"object","required":["product_type","query"],"title":"SearchRequest"},"SearchResponse":{"properties":{"ok":{"type":"boolean","title":"Ok"},"found":{"anyOf":[{"$ref":"#/components/schemas/SearchFound"},{"type":"null"}]}},"type":"object","required":["ok"],"title":"SearchResponse"},"TopUpRequest":{"properties":{"amount":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Amount"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","default":"ton"}},"type":"object","title":"TopUpRequest"},"TopUpResponse":{"properties":{"wallet_address":{"type":"string","title":"Wallet Address"},"amount":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Amount"},"currency":{"type":"string","title":"Currency"},"invoice_id":{"type":"string","title":"Invoice Id"},"usdt_jetton_master":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usdt Jetton Master"},"usdt_jetton_master_suffix":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usdt Jetton Master Suffix"},"note":{"type":"string","title":"Note","default":"Send TON or USDT TON to this address. Credited automatically."}},"type":"object","required":["wallet_address","currency","invoice_id"],"title":"TopUpResponse"},"Transaction":{"properties":{"id":{"type":"string","title":"Id"},"transaction_id":{"type":"string","title":"Transaction Id"},"merchant_id":{"type":"string","title":"Merchant Id"},"status":{"type":"string","title":"Status"},"type":{"type":"string","title":"Type"},"operation_type":{"type":"string","title":"Operation Type"},"recipient":{"type":"string","title":"Recipient"},"item_name":{"type":"string","title":"Item Name"},"item_price":{"type":"number","title":"Item Price"},"item_quantity":{"type":"integer","title":"Item Quantity"},"payment_method":{"type":"string","title":"Payment Method"},"idempotency_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency Key"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"},"ton_tx_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ton Tx Id"},"created_at":{"type":"string","title":"Created At"},"updated_at":{"type":"string","title":"Updated At"}},"type":"object","required":["id","transaction_id","merchant_id","status","type","operation_type","recipient","item_name","item_price","item_quantity","payment_method","created_at","updated_at"],"title":"Transaction"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WithdrawBody":{"properties":{"asset":{"type":"string","pattern":"^(ton|usdt)$","title":"Asset"},"amount":{"type":"number","exclusiveMinimum":0.0,"title":"Amount"},"to_address":{"type":"string","title":"To Address"}},"type":"object","required":["asset","amount","to_address"],"title":"WithdrawBody"}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Merchant API key (plain string, no prefix)"}}},"tags":[{"name":"merchants","description":"Balance and top-up"},{"name":"prices","description":"Product pricing"},{"name":"purchases","description":"Stars and Premium purchases"},{"name":"search","description":"Recipient lookup"},{"name":"legacy","description":"Deprecated v1 routes"}]}