# 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.

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://pluton-finance.gitbook.io/pluton-fnance/technical/integration-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.