> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keystoneos.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Testing Your Integration

> Set up a sandbox, get test tokens, and verify your integration end-to-end.

## Sandbox environment

Your **Development** environment is your sandbox. It connects to testnets (Sepolia and Base Sepolia) instead of mainnet, so you can run full settlement flows without real assets or funds.

All API behavior is identical between Development and Production environments. The only difference is the underlying blockchain network and smart contract deployment.

## Test tokens

KeyStone provides two mintable ERC-20 tokens for testing:

| Token     | Description                          | Networks              |
| --------- | ------------------------------------ | --------------------- |
| **KBOND** | Test security token (tokenized bond) | Sepolia, Base Sepolia |
| **TUSDC** | Test stablecoin (USDC equivalent)    | Sepolia, Base Sepolia |

Both tokens have a public `mint()` function, so you can mint as many as you need for testing. See [testnet addresses](/smart-contracts/testnet-addresses) for contract addresses.

## End-to-end test flow

Walk through a complete settlement to verify your integration:

### 1. Submit a seller instruction

Use the SDK or API to submit an instruction for the sell side. This returns a `trade_reference` that the buyer uses to match.

```typescript theme={null}
const instruction = await keystone.instructions.submit({
  template_id: "dvp-template-id",
  idempotency_key: "test-sell-001",
  party: {
    role: "seller",
    name: "Test Seller",
    wallet_address: "0x...",
  },
  legs: [
    {
      type: "asset",
      token_address: "0x...", // KBOND address
      amount: "1000000000000000000", // 1 KBOND
    },
  ],
});

const tradeReference = instruction.trade_reference;
```

### 2. Submit a buyer instruction

Submit the counterparty instruction using the same `trade_reference`. This triggers the matching process.

```typescript theme={null}
await keystone.instructions.submit({
  template_id: "dvp-template-id",
  trade_reference: tradeReference,
  idempotency_key: "test-buy-001",
  party: {
    role: "buyer",
    name: "Test Buyer",
    wallet_address: "0x...",
  },
  legs: [
    {
      type: "payment",
      token_address: "0x...", // TUSDC address
      amount: "100000000", // 100 TUSDC
    },
  ],
});
```

### 3. Verify the settlement was created

After both instructions match, a settlement is created. Query it to confirm:

```typescript theme={null}
const settlements = await keystone.settlements.list();
// Check for a settlement with your trade reference
```

### 4. Check webhook delivery

Verify that your webhook endpoint received the settlement's events - on the happy path that is `settlement.state.awaiting_deposits` followed by `settlement.state.finalized`. See the [webhook event catalog](/guides/webhook-events) for exactly which events fire.

### 5. Advance through states (optional)

If you have access to the integration testing endpoints, you can programmatically advance the settlement through its state machine (the dedicated integration testing guide was retired; ask your KeyStone contact for the current test-environment options).

## CLI for local development

Use the KeyStone CLI to forward webhooks to your local development server:

```bash theme={null}
keystone listen --forward-to http://localhost:3000/webhooks
```

This creates a temporary webhook endpoint that tunnels events to your local machine, so you can test webhook handling without deploying.

See the [CLI reference](/sdks/cli) for installation and usage.

## Postman collection

For manual API exploration, import the KeyStone Postman collection. It includes pre-configured requests for all endpoints with environment variables for authentication.

See the [Postman guide](/sdks/postman) for setup instructions.

## Checklist before going to production

Before switching from your Development environment to Production, verify:

<Info>
  This checklist covers the most common integration issues. Complete each item to avoid surprises in production.
</Info>

* [ ] **Webhook handler processes all settlement states** - Your handler should gracefully handle every state in the [settlement state machine](/concepts/state-machine), including error and rollback states.
* [ ] **Signature verification is implemented** - Validate the `X-Keystone-Signature` header on every webhook delivery. See [webhooks](/guides/webhooks) for details.
* [ ] **Idempotency keys on all create/submit calls** - Every `POST` to `/v1/instructions` should include a unique `idempotency_key` to prevent duplicates on retry.
* [ ] **Error handling covers all error codes** - Handle `400`, `401`, `409`, `422`, and `5xx` responses appropriately. See [error handling](/guides/error-handling).
* [ ] **Rate limits accounted for** - Implement exponential backoff for retries and respect `429` responses.