Testing Your Integration

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 for contract addresses.

End-to-end test flow

Walk through a complete settlement to verify your integration:

1. Submit a seller instruction

Submit the sell side of the trade. Each instruction carries a single party and that party’s legs (both directions from their perspective). The response returns a trade_reference that the buyer uses to submit the counterpart instruction.

curl -X POST https://api.keystoneos.xyz/v1/instructions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "test-sell-001",
    "template_slug": "dvp-standard",
    "role": "seller",
    "party": {
      "external_reference": "test-seller-001",
      "name": "Test Seller",
      "wallet_address": "0x1234567890abcdef1234567890abcdef12345678"
    },
    "legs": [
      { "leg_type": "asset_delivery", "instrument_id": "0xKBONDAddress", "quantity": "1", "direction": "deliver", "chain_id": 84532 },
      { "leg_type": "payment", "instrument_id": "0xTUSDCAddress", "quantity": "100", "direction": "receive", "chain_id": 84532 }
    ],
    "timeout_at": "2026-08-01T00:00:00Z"
  }'

The response includes the generated trade_reference (e.g. KS-a1b2c3d4-...). Share it with the buyer.

2. Submit a buyer instruction

Submit the counterparty instruction using the same trade_reference. When the two sides agree, KeyStone confirms them and creates the settlement.

curl -X POST https://api.keystoneos.xyz/v1/instructions \
  -H "Authorization: Bearer $COUNTERPARTY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "test-buy-001",
    "trade_reference": "KS-a1b2c3d4-...",
    "template_slug": "dvp-standard",
    "role": "buyer",
    "party": {
      "external_reference": "test-buyer-001",
      "name": "Test Buyer",
      "wallet_address": "0xfedcba9876543210fedcba9876543210fedcba98"
    },
    "legs": [
      { "leg_type": "asset_delivery", "instrument_id": "0xKBONDAddress", "quantity": "1", "direction": "receive", "chain_id": 84532 },
      { "leg_type": "payment", "instrument_id": "0xTUSDCAddress", "quantity": "100", "direction": "deliver", "chain_id": 84532 }
    ],
    "timeout_at": "2026-08-01T00:00:00Z"
  }'

On confirmation the response shows "status": "matched" and a non-null settlement_id.

3. Verify the settlement was created

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

curl "https://api.keystoneos.xyz/v1/settlements?limit=50" \
  -H "Authorization: Bearer $TOKEN"
# Look for the settlement carrying 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 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:

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 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 for setup instructions.

Checklist before going to production

Before switching from your Development environment to Production, verify:

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

Webhook handler processes all settlement states - Your handler should gracefully handle every state in the settlement state machine, including error and rollback states.
Signature verification is implemented - Validate the X-Keystone-Signature header on every webhook delivery. See 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.
Rate limits accounted for - Implement exponential backoff for retries and respect 429 responses.

Getting Started

Core Concepts

Guides

Smart Contracts

Testing Your Integration

Sandbox environment

Test tokens

End-to-end test flow

1. Submit a seller instruction

2. Submit a buyer instruction

3. Verify the settlement was created

4. Check webhook delivery

5. Advance through states (optional)

CLI for local development

Postman collection

Checklist before going to production

​Sandbox environment

​Test tokens

​End-to-end test flow

​1. Submit a seller instruction

​2. Submit a buyer instruction

​3. Verify the settlement was created

​4. Check webhook delivery

​5. Advance through states (optional)

​CLI for local development

​Postman collection

​Checklist before going to production

Sandbox environment

Test tokens

End-to-end test flow

1. Submit a seller instruction

2. Submit a buyer instruction

3. Verify the settlement was created

4. Check webhook delivery

5. Advance through states (optional)

CLI for local development

Postman collection

Checklist before going to production