{"openapi":"3.1.0","info":{"title":"StableGift","description":"Pay with x402 or MPP to create Loop & Tie gift redemption links capped at $150.","version":"1.0.0","x-guidance":"# StableGift API\n\nStableGift creates Loop & Tie gift redemption links paid with x402 or MPP. A buyer pays upfront and receives a redeem URL. The recipient opens the URL, chooses one item from the selected collection, and enters their own shipping address.\n\nSupported payment paths: x402 on Base, x402 on Solana, and MPP on Tempo.\n\n## Flow\n\n1. GET /api/collections — list supported gift collections capped at $150.\n2. POST /api/gift-link — pay via x402 and create a gift redemption link.\n3. GET /api/gifts/{giftId} — check gift status and events.\n\n## Collections\n\nCollections are curated from Loop & Tie and capped at $150. Impact-only collections such as \"$10 - Happy Planet\", \"$15 - Give Back\", and Social Impact collections are hidden by default so agents get shippable gift collections unless they explicitly build a different flow later.\n\nUse collectionId from /api/collections when creating a gift link. Prices are exact collection prices in USDC.\n\n## Gift Links\n\nPOST /api/gift-link\nBody:\n{\n  \"collectionId\": \"4438\",\n  \"recipientName\": \"Sam\",\n  \"message\": \"Happy birthday!\",\n  \"from\": \"Merit Systems\"\n}\n\nThe route validates the collection before returning a 402 price. The buyer pays the collection price, then StableGift creates the Loop & Tie gift with delivery_method \"link\" and returns giftId, redeemUrl, stage, expiresOn, and collection.\n\nThe recipient does not need a wallet and does not pay. They redeem the gift at redeemUrl.","guidance":"# StableGift API\n\nStableGift creates Loop & Tie gift redemption links paid with x402 or MPP. A buyer pays upfront and receives a redeem URL. The recipient opens the URL, chooses one item from the selected collection, and enters their own shipping address.\n\nSupported payment paths: x402 on Base, x402 on Solana, and MPP on Tempo.\n\n## Flow\n\n1. GET /api/collections — list supported gift collections capped at $150.\n2. POST /api/gift-link — pay via x402 and create a gift redemption link.\n3. GET /api/gifts/{giftId} — check gift status and events.\n\n## Collections\n\nCollections are curated from Loop & Tie and capped at $150. Impact-only collections such as \"$10 - Happy Planet\", \"$15 - Give Back\", and Social Impact collections are hidden by default so agents get shippable gift collections unless they explicitly build a different flow later.\n\nUse collectionId from /api/collections when creating a gift link. Prices are exact collection prices in USDC.\n\n## Gift Links\n\nPOST /api/gift-link\nBody:\n{\n  \"collectionId\": \"4438\",\n  \"recipientName\": \"Sam\",\n  \"message\": \"Happy birthday!\",\n  \"from\": \"Merit Systems\"\n}\n\nThe route validates the collection before returning a 402 price. The buyer pays the collection price, then StableGift creates the Loop & Tie gift with delivery_method \"link\" and returns giftId, redeemUrl, stage, expiresOn, and collection.\n\nThe recipient does not need a wallet and does not pay. They redeem the gift at redeemUrl.","contact":{"name":"Merit Systems","url":"https://stablegift.dev"}},"servers":[{"url":"https://stablegift.dev"}],"tags":[{"name":"Collections"},{"name":"Gift Link"},{"name":"Gifts"}],"paths":{"/api/collections":{"get":{"operationId":"collections","summary":"List supported Loop & Tie gift collections capped at $150. Requires SIWX.","tags":["Collections"],"security":[{"siwx":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"collections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"price":{"type":"string"},"nickname":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","price","nickname"],"additionalProperties":false}}},"required":["collections"],"additionalProperties":false}}}},"402":{"description":"Authentication Required"}}}},"/api/gift-link":{"post":{"operationId":"gift-link","summary":"Create a Loop & Tie gift redemption link. Pays the selected collection price via x402 on Base, then returns a redeemUrl for the recipient.","tags":["Gift Link"],"x-payment-info":{"price":{"mode":"dynamic","currency":"USD","min":"0","max":"150.00"},"protocols":[{"x402":{}},{"mpp":{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50"}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"collectionId":{"type":"string","minLength":1,"description":"Loop & Tie collection ID."},"recipientName":{"type":"string","minLength":1,"maxLength":120,"description":"Recipient display name shown on the redemption page."},"message":{"type":"string","minLength":1,"maxLength":500,"description":"Gift message shown to the recipient."},"from":{"type":"string","minLength":1,"maxLength":120,"description":"Sender display name shown to the recipient."}},"required":["collectionId","recipientName","message","from"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"gift":{"type":"object","properties":{"giftId":{"type":"string"},"externalId":{"type":"string"},"redeemUrl":{"type":"string","format":"uri"},"deliveryMethod":{"type":"string"},"stage":{"type":"string"},"expiresOn":{"anyOf":[{"type":"string"},{"type":"null"}]},"scheduledAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastEventAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"subject":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]},"from":{"anyOf":[{"type":"string"},{"type":"null"}]},"selectedProduct":{"anyOf":[{"type":"string"},{"type":"null"}]},"trackingNumber":{"anyOf":[{"type":"string"},{"type":"null"}]},"events":{"type":"array","items":{"type":"object","properties":{"stage":{"type":"string"},"message":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"}},"required":["stage","createdAt"],"additionalProperties":false}},"collection":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"price":{"type":"string"},"nickname":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","price","nickname"],"additionalProperties":false}},"required":["giftId","externalId","redeemUrl","deliveryMethod","stage","expiresOn","scheduledAt","lastEventAt","subject","message","from","selectedProduct","trackingNumber","events","collection"],"additionalProperties":false}},"required":["gift"],"additionalProperties":false}}}},"402":{"description":"Payment Required"}}}},"/api/gifts/{giftId}":{"get":{"operationId":"gifts_get","summary":"Get Loop & Tie gift status and events by giftId.","tags":["Gifts"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"gift":{"type":"object","properties":{"giftId":{"type":"string"},"externalId":{"type":"string"},"redeemUrl":{"type":"string","format":"uri"},"deliveryMethod":{"type":"string"},"stage":{"type":"string"},"expiresOn":{"anyOf":[{"type":"string"},{"type":"null"}]},"scheduledAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastEventAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"subject":{"anyOf":[{"type":"string"},{"type":"null"}]},"message":{"anyOf":[{"type":"string"},{"type":"null"}]},"from":{"anyOf":[{"type":"string"},{"type":"null"}]},"selectedProduct":{"anyOf":[{"type":"string"},{"type":"null"}]},"trackingNumber":{"anyOf":[{"type":"string"},{"type":"null"}]},"events":{"type":"array","items":{"type":"object","properties":{"stage":{"type":"string"},"message":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"}},"required":["stage","createdAt"],"additionalProperties":false}},"collection":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"price":{"type":"string"},"nickname":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","price","nickname"],"additionalProperties":false}},"required":["giftId","externalId","redeemUrl","deliveryMethod","stage","expiresOn","scheduledAt","lastEventAt","subject","message","from","selectedProduct","trackingNumber","events","collection"],"additionalProperties":false}},"required":["gift"],"additionalProperties":false}}}}}}}},"components":{"securitySchemes":{"siwx":{"type":"apiKey","in":"header","name":"SIGN-IN-WITH-X"}}}}