# DropSwap Launchpad Liquidity Gateway — Quickstart

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

## Purpose

DropSwap Launchpad Liquidity Gateway lets a launchpad hand post-launch liquidity to DropSwap without transferring wallet control to DropSwap.

The launchpad signs and broadcasts every returned transaction itself.

On production Gateway V2 deployments, LP tokens created by the liquidity operation are sent directly to the chain-specific DropSwap Permanent Locker. The launchpad does not supply an `lpRecipient`.

## Production V2 networks

This guide covers:

- Arbitrum One
- Robinhood Chain

API base URL:

```bash
export GATEWAY_API="https://dropswap.finance/launchpad-api"
```

## Partner access

Discovery and preview are public. Production `POST /v1/prepare` requires approved Launchpad Gateway partner credentials.

Register or manage access here:

`https://dropswap.finance/?launchpadGateway=1`

Keep the Partner ID and API key on your backend only.

```bash
export DROPSWAP_PARTNER_ID="lp_YOUR_PARTNER_ID"
export DROPSWAP_API_KEY="ds_lp_YOUR_API_KEY"
```

Never expose the API key in browser JavaScript or a public repository.

## Recommended flow

1. Discover chain configuration.
2. Discover approved quote tokens.
3. Preview liquidity.
4. Generate a unique integrationId.
5. Prepare the transaction plan.
6. Sign and broadcast the returned transactions in order.
7. Query execution status.
8. Store the final Liquidity Receipt.

## 1. Discover chain configuration

```bash
curl "$GATEWAY_API/v1/chains"
```

The response contains runtime chain configuration and Gateway deployment information.

## 2. Discover approved quote tokens

Arbitrum:

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

Robinhood:

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

For normal ERC20/ERC20 liquidity, `quoteToken` must be the ERC-20 contract address returned by the quote-token endpoint. Do not use a symbol such as `USDC`, `USDG` or `WETH` for normal ERC20/ERC20 mode.

## 3. Preview liquidity

Example:

```bash
curl -X POST "$GATEWAY_API/v1/preview" \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "arbitrum",
    "token": "TOKEN_ADDRESS",
    "quoteToken": "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
    "tokenAmount": "TOKEN_AMOUNT_BASE_UNITS",
    "quoteAmount": "USDC_AMOUNT_BASE_UNITS"
  }'
```

Inspect at least ready, riskLevel, blockingIssues, warnings, pool, priceAnalysis and contractChecks.

Do not continue to execution when ready=false.

## 4. Generate integrationId

Every execution requires a unique non-zero bytes32 integration ID.

Example with ethers:

```js
const integrationId = ethers.keccak256(
  ethers.toUtf8Bytes(
    `my-launchpad:${chainId}:${token}:${launchpad}:${Date.now()}`
  )
);
```

The launchpad generates the integrationId. DropSwap validates its format and passes it to the Gateway unchanged.

Gateway V2 replay protection is scoped by launchpad wallet and integration ID:

```text
executedFor(launchpad, integrationId)
```

Never reuse an integrationId after successful execution.

## 5. Prepare execution

launchpad is the wallet address that will sign and execute the Gateway seed transaction. Use the same address later when querying status.

```bash
curl -X POST "$GATEWAY_API/v1/prepare" \
  -H "Content-Type: application/json" \
  -H "X-DropSwap-Partner: $DROPSWAP_PARTNER_ID" \
  -H "X-DropSwap-API-Key: $DROPSWAP_API_KEY" \
  -d '{
    "chain": "arbitrum",
    "launchpad": "LAUNCHPAD_WALLET_ADDRESS",
    "token": "TOKEN_ADDRESS",
    "quoteToken": "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
    "tokenAmount": "TOKEN_AMOUNT_BASE_UNITS",
    "quoteAmount": "USDC_AMOUNT_BASE_UNITS",
    "integrationId": "0xYOUR_BYTES32_INTEGRATION_ID",
    "slippageBps": 100,
    "deadlineSeconds": 1200
  }'
```

For Gateway V2, do not send lpRecipient. LP tokens are sent directly to the chain-specific Permanent Locker.

Defaults:

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

Maximum deadlineSeconds is 86400.

The API returns an ordered transactions array. Execute it exactly in the returned order.

## 6. Sign and broadcast

Conceptual ethers example:

```js
let seedTxHash = null;

for (const txRequest of prepared.transactions) {
  const tx = await signer.sendTransaction({
    to: txRequest.to,
    data: txRequest.data,
    value: txRequest.value
  });

  const receipt = await tx.wait();

  if (String(txRequest.type).startsWith("GATEWAY_SEED_")) {
    seedTxHash = receipt.hash;
  }
}
```

Store the Gateway seed transaction hash with the launch record.

### ERC20 / ERC20 plan

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

### ERC20 / native ETH plan

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

The seed transaction carries the native amount in value.

## 7. Resolve status and Liquidity Receipt

Use the same launchpad wallet supplied to /v1/prepare:

```bash
export INTEGRATION_ID="0xYOUR_BYTES32_INTEGRATION_ID"
export LAUNCHPAD_WALLET="LAUNCHPAD_WALLET_ADDRESS"

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

Possible states include:

```text
NOT_EXECUTED
EXECUTED_RECEIPT_UNRESOLVED
EXECUTED
```

On Arbitrum, integrationId plus the launchpad wallet is normally sufficient for receipt resolution.

On Robinhood, cached receipts are returned directly. If an executed receipt is not yet resolved, provide the stored Gateway seed transaction hash:

```bash
export TX_HASH="0xGATEWAY_SEED_TRANSACTION_HASH"

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

The API resolves and caches the receipt. The launchpad does not need to perform historical event scanning itself.

Store the final EXECUTED Liquidity Receipt in the launch record.

## Liquidity Receipt

Receipt data includes the launchpad, token, quote token, pair, deposited amounts, liquidity amount, LP/Locker recipient information, new-pool flag, transaction hash and block number.

For Gateway V2, the LP recipient is the chain-specific Permanent Locker.

## Gateway V2 security model

The launchpad retains control of its wallet and funds until it signs the prepared transactions.

Gateway V2:

- sends LP tokens directly to the chain-specific Permanent Locker;
- does not accept a launchpad-selected lpRecipient;
- uses executedFor(launchpad, integrationId) for replay protection;
- does not retain execution funds after successful liquidity seeding;
- enforces minimum token and quote amounts through the DEX Router;
- can be paused for new liquidity seeds.

See API.md, GATEWAY_ABI.md and SECURITY_INVARIANTS.md for the detailed integration reference.