# Integration Guide

Integrating with Pluton enables wallets, dApps, and services to offer seamless cross-chain swaps and bridges to their users.

\
A typical integration involves:

* Defining an intent (e.g., swap 100 USDT on Arbitrum to TON on Ton).
* Sending the intent to Pluton via our SDK or API.
* Receiving a quote and transaction details.
* Executing the transaction and receiving confirmation.

\
See our Terminology Page for definitions of key concepts such as intent, solver, quote, affiliate, and more. For developers looking to integrate Pluton into their projects, the following endpoints and workflows are essential.

***

### 1. Prerequisites

* **API Key:** Request an API key from the Pluton team for authenticated endpoints.
* **Base URL:** All endpoints are relative to your Pluton backend deployment (e.g., `https://api.pluton.exchange`).

***

### 2. Network & Token Discovery

#### Get Supported Networks and Tokens

* **GET `/network`**\
  Returns all supported networks and their tokens.

  **Response Example:**

  ```json
  {
    "res": [
      {
        "chainId": 42161,
        "tokens": [
          {
            "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
            "symbol": "USDT",
            ...
          }
        ]
      }
    ],
    "count": 1
  }
  ```
* **GET `/network/tokens/?page=1&offset=10`**\
  Paginated list of networks and tokens.
* **GET `/network/all`**\
  Returns all networks and tokens (non-paginated).

***

#### Get Token List

* **GET `/token/list?page=1&offset=10`**\
  Paginated list of tokens.
* **GET `/token/sync`**\
  Manually trigger token sync (admin/integrator use).

***

#### Get Token USD Price

* **GET `/price/usd-price?address=<tokenAddress>&chainId=<chainId>`**\
  Returns the USD price for a given token.

***

### 3. Quote & Intent Flow

#### 1. Request a Quote

* **POST `/quote/select`**\
  Request a quote for a user intent.

  **Request Body Example:**

  ```json
  {
    "fromChainId": 42161,
    "fromToken": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
    "fromAmount": "100000000",
    "toChainId": 101,
    "toToken": "So11111111111111111111111111111111111111112",
    "toAddress": "DestinationWalletAddress",
    "slippage": 0.005,
    "affiliate": "optionalAffiliateId",
    "referrer": "optionalReferrerId"
  }
  ```

  **Response Example:**

  ```json
  {
    "quoteId": "uuid",
    "solverId": "uuid",
    "fromAmount": "100000000",
    "toAmount": "50000000",
    "fee": "1000000",
    "rate": "0.5",
    "estimatedDuration": 45,
    "executionPlan": [ ... ]
  }
  ```

***

#### 2. Track Intent Status

* **GET `/quote/intent/:id`**\
  Get the status and details of a specific quote intent by ID.

***

#### 3. Refunds

* **POST `/quote/refund/request`**\
  Request a refund signature for an unsolved quote.
* **POST `/quote/refund`**\
  Get the user refund signature to claim back funds from the contract.

***

#### 4. Affiliate/Referral Claims

* **GET `/quote/affiliate/request`**\
  Request a signature to claim affiliate assets.
* **POST `/quote/affiliate`**\
  Get the affiliate claim signature to claim funds from the contract.

***

### 4. Solver Claim Flow

For solvers who have executed an intent and want to claim their reward:

* **POST `/solver/claim`**\
  Request a signature and transaction details for a claim.

  **Request Body Example:**

  ```json
  {
    "claimerAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "chainId": 42161,
    "coinType": 60,
    "tokenAddress": "0xdAC17F958D2ee523a2206206994597C13D831ec7"
  }
  ```

  **Response Example:**

  ```json
  {
    "signature": "0xabcdef...",
    "lastClaimedAmount": "1000000",
    "claimerAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "amountToClaim": "500000",
    "transaction": {
      "hash": "0xabc123...",
      "status": 1
    }
  }
  ```

***

### 5. Error Handling

All endpoints return errors in a standardized format:

```json
{
  "error": {
    "code": "ERR_CODE",
    "message": "Description of the error."
  }
}
```

**Common Error Codes:**

* `ERR_NO_SOLVER`
* `ERR_INVALID_QUOTE`
* `ERR_EXECUTION_FAILED`
* `ERR_VERIFICATION_FAILED`
* `ERR_UNAUTHORIZED`

***

### 6. Integration Checklist

* [ ] Obtain API key and set up authentication.
* [ ] Use `/network` and `/token/list` to discover supported assets.
* [ ] Use `/price/usd-price` for price feeds.
* [ ] Implement quote request and selection via `/quote/select`.
* [ ] Track intent status and handle refunds as needed.
* [ ] Integrate affiliate/referral claim endpoints if applicable.
* [ ] For solvers, implement the claim flow via `/solver/claim`.
* [ ] Handle errors and provide user feedback.

***

### 7. Example Flow

1. **User Action:** User initiates a cross-chain swap in your dApp.
2. **Quote Request:** Your backend sends a POST to `/quote/select`.
3. **Quote Selection:** Receive and display the quote to the user.
4. **Execution:** User confirms; transaction is executed.
5. **Status Tracking:** Poll `/quote/intent/:id` for updates.
6. **Completion:** User is notified of success, or error handling is triggered.

***