Skip to main content

​
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:
TokenDescriptionNetworks
KBONDTest security token (tokenized bond)Sepolia, Base Sepolia
TUSDCTest 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

Use the SDK or API to submit an instruction for the sell side. This returns a trade_reference that the buyer uses to match. 
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. 
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: 
const settlements = await keystone.settlements.list();
// Check for a settlement with your trade reference

​
4. Check webhook delivery

Verify that your webhook endpoint received events for each state transition. You should see events like settlement.created, settlement.compliance_checking, and so on.

​
5. Advance through states (optional)

If you have access to the integration testing endpoints, you can programmatically advance the settlement through its state machine. See the integration testing guide for details.

​
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.