From 1b941ca71192419cef1b521a9aa661b798a29c31 Mon Sep 17 00:00:00 2001 From: "Justin (HoangVD2)" Date: Fri, 15 Mar 2024 14:38:53 +0700 Subject: [PATCH 1/2] docs: documentation for section Campaigns Service API --- .vitepress/config.ts | 4 + .vitepress/theme/tailwind.postcss | 2 - developers/campaigns-service-api.md | 195 ++++++++++++++++++++++++++++ developers/introduction.md | 6 + 4 files changed, 205 insertions(+), 2 deletions(-) create mode 100644 developers/campaigns-service-api.md diff --git a/.vitepress/config.ts b/.vitepress/config.ts index 0e7598f53..d0718e132 100644 --- a/.vitepress/config.ts +++ b/.vitepress/config.ts @@ -711,6 +711,10 @@ function sidebarHome() { }, ], }, + { + text: "Campaigns Service API", + link: "/developers/campaigns-service-api", + }, ], }, { diff --git a/.vitepress/theme/tailwind.postcss b/.vitepress/theme/tailwind.postcss index 8a90c8074..bd6213e1d 100644 --- a/.vitepress/theme/tailwind.postcss +++ b/.vitepress/theme/tailwind.postcss @@ -1,5 +1,3 @@ @tailwind base; - @tailwind components; - @tailwind utilities; \ No newline at end of file diff --git a/developers/campaigns-service-api.md b/developers/campaigns-service-api.md new file mode 100644 index 000000000..8839337db --- /dev/null +++ b/developers/campaigns-service-api.md @@ -0,0 +1,195 @@ +--- +prev: + text: Libraries Integration + link: /developers/libraries-integration +--- + +# Campaigns Service API + +Welcome to the XDEFI Campaigns Service API documentation. This API allows third-party websites to connect a list of addresses from an external source to the XDEFI Wallet's internal list of opted-in ad + +### Base URL + +The base URL for all API endpoints is: `https://compaign-ts.xdefi.services/api` + +### Workflow + +The high-level workflow for the XDEFI Campaigns Service API is as follows: + +1. A third-party website sends a list of addresses from any XDEFI-supported chain to the Campaigns Service API. These addresses fulfill certain criteria determined by the third-party website. +2. XDEFI maintains an internal list of user addresses that have opted into the Campaigns feature in XDEFI Wallet. +3. The Campaigns Service API cross-references the third-party list of addresses with the internal list of opted-in addresses. +4. If there is a match between a third-party address and an opted-in address, the corresponding EVM address is identified. +5. A request is made to the Campaigns Service API from a website like Galxe, using an endpoint such as `https://compaign-ts.xdefi.services/api/campaigns/{campaign_name}/address/{evm_address}/`. +6. The request includes a user's EVM address. +7. If the user's EVM address meets both criteria: + - The EVM address is in the XDEFI list of opted-in addresses (indicating participation in the campaign). + - The corresponding SOL address is in the third-party list of addresses (indicating completion of the task). +8. If the criteria are met, the API returns TRUE to Galxe. + +Note: The requested address will always be in the EVM format, but the corresponding address could be on any XDEFI-supported chain. + +### Swagger Documentation + +You can find the Swagger documentation for the XDEFI Campaigns Service API [here](https://compaign-ts.xdefi.services/documentation/v1.0.0). + +## Endpoints + +### Create Event + +Create a new event for a campaign. + +- Method: POST +- Endpoint: `/events` +- Request format: JSON +- Response format: JSON + +::: code-group + +```js [Request Body] +{ + "address": "0x...", + "campaign": "campignName", + "partnerName": "routing", + "partnerKey": "abc", + "metadata": { ... } +} +``` + +::: + +The request body should include the following parameters: + +| Field | Type | Required | Description | +| ------------- | ------ | -------- | ---------------------------------- | +| `address` | string | Yes | The user's address. | +| `campaign` | string | Yes | The name of the campaign. | +| `partnerName` | string | Yes | The name of the partner. | +| `partnerKey` | string | Yes | The key of the partner. | +| `metadata` | object | Yes | Additional metadata for the event. | + +::: code-group + +```js [Example Request] +POST /events HTTP/1.1 +Host: compaign-ts.xdefi.services/api +Content-Type: application/json + +{ + "address": "0x1234567890abcdef", + "campaign": "campignName", + "partnerName": "routing", + "partnerKey": "abc", + "metadata": { ... } +} +``` + +```json [Example Response] +{ + "id": 0, + "address": "0x1234567890abcdef", + "metadata": { ... }, + "createdAt": "string", + "updatedAt": "string", + "publishedAt": "string" +} +``` + +::: + +### Check Campaign Address + +Check if all partners have reported the address for a given campaign. + +- Method: GET +- Endpoint: `/campaign/{name}/address/{address}` +- Response format: JSON + +**Parameters** + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ------------------------------------------------ | +| `name` | string | Yes | The name of the campaign. | +| `address` | string | Yes | The address to check for campaign participation. | + +::: code-group + +```js [Example Request] +GET /campaign/mycampaign/address/0x1234567890abcdef HTTP/1.1 +Host: compaign-ts.xdefi.services/api +``` + +```json [Example Response] +{ + "result": true, + "events": [ + { + "address": "0x1234567890abcdef", + "partnerName": "string" + } + ] +} +``` + +::: + +This response indicates that all partners have reported the address `0x1234567890abcdef` for the campaign with the name `mycampaign`. + +### Opt-in + +Opt-in a user to the campaigns service. + +- Method: POST +- Endpoint: `/campaigns/opt-in` +- Request format: JSON +- Response format: JSON + +::: code-group + +```js [Request Body] +{ + "userId": "dfsjnsekjdfbgjkdfgkjdfjkgbdfjkgk", + "addresses": [ + { + "chain": "ETH", + "address": "0xE9752bf95F4cF73cf8b45e75D88756EC8D48845c" + } + ] +} +``` + +::: + +The request body should include the following parameters: + +| Parameter | Type | Required | Description | +| ----------- | ------ | -------- | ------------------------------------------------------------------------------------- | +| `userId` | string | Yes | The user ID. | +| `addresses` | array | Yes | An array of address objects, each containing the chain (string) and address (string). | + +### Opt-out + +Opt-out a user from the campaigns service. + +- Method: POST +- Endpoint: `/campaigns/opt-out` +- Request format: JSON +- Response format: JSON + +::: code-group + +```js [Request Body] +{ + "userId": "dfsjnsekjdfbgjkdfgkjdfjkgbdfjkgk", +} +``` + +::: + +The request body should include the following parameters: + +| Parameter | Type | Required | Description | +| --------- | ------ | -------- | ------------ | +| `userId` | string | Yes | The user ID. | + +Please refer to the Swagger documentation for detailed information on these endpoints, including their HTTP methods, request and response schemas, and any additional parameters or headers required. diff --git a/developers/introduction.md b/developers/introduction.md index 466097a56..791882f64 100644 --- a/developers/introduction.md +++ b/developers/introduction.md @@ -57,3 +57,9 @@ You can acces the list from here: - [CosmosKit](./cosmoskit-xdefi-integration) - [RainbowKit](./rainbowkit-xdefi-integration) - [Solana Adapter](./solana-adapter-xdefi-integration) + +## Campaigns Service API + +XDEFI Wallet is also providing a Campaigns Service API to make it easier for developers to integrate their dApps with XDEFI Wallet. + +- [Campaigns Service API](./campaigns-service-api) From c38dc503f6e5dd1dfc0c4bd181a429af8b8f28b3 Mon Sep 17 00:00:00 2001 From: "Justin (HoangVD2)" Date: Fri, 15 Mar 2024 15:21:41 +0700 Subject: [PATCH 2/2] chore: fix broken link --- .vitepress/config.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.vitepress/config.ts b/.vitepress/config.ts index d0718e132..faafce0f7 100644 --- a/.vitepress/config.ts +++ b/.vitepress/config.ts @@ -158,7 +158,7 @@ export default { }, editLink: { - pattern: "https://github.com/XDeFi-tech/docs/edit/main/:path", + pattern: "https://github.com/XDeFi-tech/docs-new/edit/main/:path", text: "Edit this page on GitHub", }, @@ -171,7 +171,7 @@ export default { siteTitle: false, socialLinks: [ - { icon: "github", link: "https://github.com/XDeFi-tech/docs" }, + { icon: "github", link: "https://github.com/XDeFi-tech" }, { icon: "twitter", link: "https://twitter.com/xdefi_wallet" }, { icon: "discord", link: "https://discord.com/invite/xdefiwallet" }, { icon: { svg: telegramSVG }, link: "https://t.me/xdefi_announcements" },