# Tokens

Create and manage **Solana Token-2022** tokens with on-chain metadata and built-in tax distribution.

### Token creation flow

{% stepper %}
{% step %}

### Generate a distribution wallet (optional but recommended)

Call `POST /tokens/generate-distribution-wallet` to get a `walletId` + derived distribution address.
{% endstep %}

{% step %}

### Upload the image to IPFS

Call `POST /tokens/upload-image` to receive an `imageUri`.
{% endstep %}

{% step %}

### Create an unsigned transaction

Call `POST /tokens/create-unsigned` to receive a base64 transaction.
{% endstep %}

{% step %}

### Sign & submit

Sign the transaction with the user wallet and submit via `POST /tokens/submit`.
{% endstep %}
{% endstepper %}

***

### POST `/tokens/generate-distribution-wallet`

Generate a distribution wallet for fee collection. Typically called when a user opens the token creation UI.

{% hint style="info" %}
**Public endpoint** — no JWT required.
{% endhint %}

#### Response (`200 OK`)

```json
{
  "walletId": "uuid",
  "address": "DistributionWalletAddress..."
}
```

{% hint style="warning" %}
The returned `walletId` must be sent in `POST /tokens/create-unsigned`. The wallet address is derived deterministically on the backend.
{% endhint %}

***

### POST `/tokens/upload-image`

Upload token image to IPFS. The image is optimized to **512×512 JPG**.

{% hint style="warning" %}
Requires JWT authentication. See [Authentication](/api-reference/readme/authentication.md).
{% endhint %}

#### Request (`multipart/form-data`)

* `image`: file (`.png` or `.jpg`, max **1MB**)

#### Response (`200 OK`)

```json
{
  "success": true,
  "imageUri": "https://ipfs.io/ipfs/QmAbc...",
  "imageCid": "QmAbc..."
}
```

***

### POST `/tokens/create-unsigned`

Create an **unsigned** Solana Token-2022 transaction with on-chain metadata.

{% hint style="warning" %}
Requires JWT authentication.
{% endhint %}

{% hint style="info" %}
⏱️ The returned transaction expires in **5 minutes** and must be signed by the user wallet.
{% endhint %}

#### Request body

```json
{
  "walletId": "uuid",

  "name": "My Token",
  "symbol": "MTK",
  "description": "Token description",
  "imageUri": "https://ipfs.io/ipfs/QmAbc...",

  "twitter": "https://twitter.com/mytoken",
  "telegram": "https://t.me/mytoken",
  "website": "https://mytoken.com",

  "transferFeePercent": 5,
  "burnPercent": 10,
  "developerFeePercent": 30,
  "developerWallet": "DevWalletAddress...",

  "distributionInterval": "15m",
  "percentageToSellPerDistribution": 25,
  "rewardToken": "SOL",
  "minimumHoldingRequirement": "1000000",

  "decimals": 6,
  "supply": "1000000000000000",
  "transferFeeAdjustable": false,
  "immutableMetadata": true
}
```

#### Response (`200 OK`)

```json
{
  "transaction": "base64_encoded_transaction",
  "transactionId": "uuid",
  "expiresAt": "2024-01-01T12:05:00Z",
  "mintKeypair": {
    "publicKey": "MintPublicKey...",
    "secretKey": [/* encrypted */]
  }
}
```

***

### POST `/tokens/submit`

Submit a **signed** transaction to Solana and save token metadata.

{% hint style="warning" %}
Requires JWT authentication.
{% endhint %}

#### Request body

```json
{
  "transactionId": "uuid",
  "signedTransaction": "base64_encoded_signed_transaction"
}
```

#### Response (`200 OK`)

```json
{
  "success": true,
  "signature": "transaction_signature",
  "mintAddress": "TokenMintAddress...",
  "token": {
    "id": "uuid",
    "mintAddress": "TokenMintAddress...",
    "name": "My Token",
    "symbol": "MTK",
    "imageUri": "https://ipfs.io/ipfs/QmAbc...",
    "createdAt": "2024-01-01T12:00:00Z"
  }
}
```

***

### GET `/tokens`

Get a paginated list of all visible tokens.

#### Query parameters

* `page` (number, default: `1`) — page number
* `limit` (number, default: `20`, max: `100`) — items per page

#### Response (`200 OK`)

```json
{
  "tokens": [
    {
      "id": "uuid",
      "mintAddress": "TokenMintAddress...",
      "name": "My Token",
      "symbol": "MTK",
      "imageUri": "https://ipfs.io/ipfs/QmAbc...",
      "description": "Token description",
      "transferFeePercent": 5,
      "poolAddress": "PoolAddress...",
      "createdAt": "2024-01-01T12:00:00Z"
    }
  ],
  "pagination": {
    "total": 150,
    "page": 1,
    "limit": 20,
    "totalPages": 8
  }
}
```

***

### GET `/tokens/me`

Get list of tokens created by the authenticated user.

{% hint style="warning" %}
Requires JWT authentication.
{% endhint %}

#### Response (`200 OK`)

```json
{
  "tokens": [
    {
      "id": "uuid",
      "mintAddress": "TokenMintAddress...",
      "name": "My Token",
      "symbol": "MTK",
      "imageUri": "https://ipfs.io/ipfs/QmAbc...",
      "distributionEnabled": true,
      "createdAt": "2024-01-01T12:00:00Z"
    }
  ]
}
```

***

### GET `/tokens/:mintAddress`

Get detailed information about a specific token.

#### Path parameters

* `mintAddress` (string) — Solana mint address

#### Response (`200 OK`)

```json
{
  "token": {
    "id": "uuid",
    "mintAddress": "TokenMintAddress...",
    "name": "My Token",
    "symbol": "MTK",
    "decimals": 6,
    "supply": "1000000000000000",
    "imageUri": "https://ipfs.io/ipfs/QmAbc...",
    "description": "Token description",
    "twitter": "https://twitter.com/mytoken",
    "telegram": "https://t.me/mytoken",
    "website": "https://mytoken.com",
    "transferFeePercent": 5,
    "burnPercent": 10,
    "developerFeePercent": 30,
    "developerWallet": "DevWalletAddress...",
    "distributionWallet": "DistributionWalletAddress...",
    "distributionInterval": "15m",
    "distributionEnabled": true,
    "poolAddress": "PoolAddress...",
    "poolCreatedAt": "2024-01-01T12:30:00Z",
    "createdAt": "2024-01-01T12:00:00Z",
    "updatedAt": "2024-01-01T12:00:00Z"
  }
}
```

### Related

* [Distribution settings](/api-reference/readme/distribution-settings.md)
* [Burns](/api-reference/readme/burns.md)
* [DEX integration](/api-reference/readme/dex-integration.md)


---

# 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://docs.taxsplit.app/api-reference/readme/tokens.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.