# DropSwap Launchpad Liquidity Gateway — API Reference

**Documentation version:** 2.0.2
**API version:** v2
**Last updated:** 2026-09-04

> **Compatibility:** Gateway API v2 keeps the existing `/v1/...` HTTP route prefix. The route prefix does not indicate the deployed Gateway contract version.

## Recommended flow

```text
/v1/chains
    ->
/v1/quote-tokens
    ->
/v1/preview
    ->
/v1/prepare
    ->
launchpad signs returned transactions
    ->
/v1/status/:integrationId
    ->
Liquidity Receipt
```

## GET /health

Gateway API health check.

## GET /v1/chains

Returns chains currently exposed by the Launchpad Gateway.

Use this endpoint instead of hard-coding the supported chain list.

Returned data includes chain ID, DropSwap Factory, Router, wrapped-native
configuration where applicable, Gateway deployment state and Gateway
address.

## GET /v1/quote-tokens?chain=CHAIN

Returns approved quote tokens for the selected chain.

Example:

```bash
curl "$GATEWAY_API/v1/quote-tokens?chain=arbitrum"
```

## quoteToken input rule

For normal `ERC20_ERC20` execution, `quoteToken` must be the ERC-20 contract
address returned by:

`GET /v1/quote-tokens?chain=CHAIN`

Examples:

- Arbitrum USDC:
  `0xaf88d065e77c8cc2239327c5edb3a432268e5831`
- Robinhood USDG:
  `0x5fc5360d0400a0fd4f2af552add042d716f1d168`

Do not use the token symbol for ERC20/ERC20 execution.


## POST /v1/preview

Performs preflight analysis before transaction construction.

Core request:

```json
{
  "chain": "arbitrum",
  "token": "0x...",
  "quoteToken": "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
  "tokenAmount": "1000000",
  "quoteAmount": "1000000"
}
```

Amounts are base-unit strings.

Important output:

```text
ready
riskLevel
blockingIssues
chain
token
quoteToken
requested
pool
priceAnalysis
contractChecks
gateway
warnings
```

Risk levels:

```text
LOW
WARNING
HIGH
```

`HIGH` is blocking.

For an existing pair, DropSwap compares the requested ratio with current
reserves and calculates optimal Router-compatible amounts.

A material deviation may produce `PRICE_MISMATCH`.

### Native aliases

Generic aliases:

```text
native
0x0000000000000000000000000000000000000000
0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee
```

Standard ETH-native chains also accept `ETH`.

## POST /v1/prepare

Prepare runs preview again.

Executable calldata is not produced when preflight is blocked.

Additional fields:

```text
launchpad
integrationId
slippageBps
deadlineSeconds
```

`launchpad` is the wallet address that signs and executes the transactions returned by `/v1/prepare`. Use the same address when querying `/v1/status/:integrationId`.

Gateway V2 does not accept a launchpad-selected `lpRecipient`. LP tokens are sent directly to the chain-specific Permanent Locker.

The `integrationId` is generated by the launchpad, must be unique for that launchpad, and is passed to DropSwap unchanged.

`integrationId` must be a non-zero bytes32:

```text
0x + 64 hexadecimal characters
```

Defaults:

```text
slippageBps     = 100
deadlineSeconds = 1200
```

Maximum deadline:

```text
86400 seconds
```

Before preparation the service verifies:

```text
Gateway deployed
Gateway paused() == false
executedFor(launchpad, integrationId) == false
```

Important response fields:

```text
version
ready
chain
gateway
integrationId
execution
transactions
preview
```

The `transactions` array is ordered.

## Execution modes

### ERC20_ERC20

```text
1. ERC20_APPROVE_TOKEN
2. ERC20_APPROVE_QUOTE
3. GATEWAY_SEED_LIQUIDITY
```

### ERC20_NATIVE

```text
1. ERC20_APPROVE_TOKEN
2. GATEWAY_SEED_LIQUIDITY_NATIVE
```

## GET /v1/status/:integrationId

Required query parameter:

```text
chain
launchpad
```

Optional:

```text
txHash
```

Example:

```bash
curl "$GATEWAY_API/v1/status/$INTEGRATION_ID?chain=arbitrum&launchpad=$LAUNCHPAD_WALLET"
```

Receipt resolution:

```bash
curl "$GATEWAY_API/v1/status/$INTEGRATION_ID?chain=robinhood&launchpad=$LAUNCHPAD_WALLET&txHash=$TX_HASH"
```

Status values:

```text
NOT_EXECUTED
EXECUTED_RECEIPT_UNRESOLVED
EXECUTED
```

A resolved `EXECUTED` response contains the Liquidity Receipt.

## Receipt fields

```text
launchpad
token
quoteToken
pair
tokenAmount
quoteAmount
liquidity
lockerRecipient
isNewPool
transactionHash
blockNumber
```

## Common errors

```text
UNSUPPORTED_CHAIN
INVALID_TOKEN_ADDRESS
INVALID_QUOTE_TOKEN_ADDRESS
IDENTICAL_TOKENS
QUOTE_TOKEN_NOT_APPROVED
INVALID_AMOUNT
ZERO_AMOUNT
RPC_CHAIN_MISMATCH
TOKEN_NOT_CONTRACT
QUOTE_TOKEN_NOT_CONTRACT
FACTORY_CODE_MISSING
ROUTER_CODE_MISSING
ROUTER_FACTORY_MISMATCH
ROUTER_USDC_MISMATCH
ROUTER_WETH_NOT_ZERO
TOKEN_METADATA_UNAVAILABLE
PRECHECK_BLOCKED
GATEWAY_NOT_DEPLOYED
INVALID_LAUNCHPAD_ADDRESS
INVALID_INTEGRATION_ID
GATEWAY_PAUSED
INTEGRATION_ALREADY_EXECUTED
INVALID_SLIPPAGE_BPS
INVALID_DEADLINE_SECONDS
ZERO_PREPARED_AMOUNT
```

## Recommended rule

Preferred integration:

```text
preview -> prepare -> sign returned transactions -> status
```

Do not reconstruct Gateway calldata manually unless deliberately using
the smart-contract ABI directly.