Section 12: Planar Transit Network Integration

Overview

The Planar Transit Network (PTN) allows your castle to send and receive travelers, goods, and messages across dimensional boundaries. This guide covers initial setup, authentication, and basic integration patterns.

Prerequisites:

• Active castle registration with the Interdimensional Transit Authority
• At least one properly installed teleportation circle (see Section 8)
• Castle Nexus Crystal (included with Premium tier and above)
• Mage level 5+ or authorized castle administrator

API Version: PTN v3.2
Protocol: Ethereal Transport Layer (ETL)
Base Endpoint: ptn://network.planar.transit

Authentication

Obtaining Your Castle Key

All PTN requests require authentication using your unique Castle Key.

1. Navigate to your castle's central control chamber
2. Locate the Castle Nexus Crystal (typically mounted above the main hearth)
3. Channel a simple identification spell while touching the crystal
4. Your Castle Key will be revealed as a 32-character runeglyph sequence

Example Castle Key:

ᚱᚢᚾᛖ-ᚲᚨᛊᛏᛚᛖ-ᚺᛖᛪ-᛫᛫᛫᛫

Key Rotation

For security purposes, rotate your Castle Key every 90 days:

castle.nexus.rotateKey({
  currentKey: "your-current-key",
  verificationType: "blood-seal"
})

Making Your First Request

Basic Transit Request

To send a traveler through the PTN, you'll invoke a transit request with the following parameters:

Required Parameters:

• origin: Your castle's planar coordinates
• destination: Target location's planar coordinates
• payload: Traveler or cargo manifest
• signature: Cryptographic seal (generated via castle key)

Example Request:

PTN.initiateTransit({
  origin: "Prime-Material.Realm-47.CastleBlackspire",
  destination: "Prime-Material.Realm-47.TowerAzure",
  payload: {
    type: "humanoid",
    count: 1,
    species: "human",
    name: "Aldric the Bold",
    inventory: ["sword", "traveling cloak", "rations(3)"]
  },
  signature: castle.generateSignature(payload, castleKey),
  options: {
    priority: "standard",
    returnRoute: true
  }
})

Response:

{
  status: "transit_initiated",
  transitId: "TRN-9847562",
  estimatedArrival: "47 seconds",
  energyCost: 250,
  route: ["BlackspireNode", "RegionalHub-7", "AzureNode"],
  confirmation: "ᛏᚱᚨᚾᛊᛁᛏ-ᚲᛟᚾᚠᛁᚱᛗᛖᛞ"
}

Response Codes

The PTN uses standard ethereal response codes:

Rate Limits

To prevent dimensional strain and energy grid overload, the PTN enforces the following limits:

Standard Tier:

• 50 transits per day
• 5 simultaneous active transits
• 10 transit requests per minute

Premium Tier:

• 500 transits per day
• 25 simultaneous active transits
• 50 transit requests per minute

Enterprise Tier:

• Unlimited transits (fair use policy applies)
• 100 simultaneous active transits
• 200 transit requests per minute

When rate limited, you'll receive a 429 response with a retryAfter timestamp:

{
  status: "rate_limited",
  message: "Transit quota exceeded",
  retryAfter: "2026-01-13T14:30:00Z",
  quotaReset: "2026-01-14T00:00:00Z"
}

Error Handling

Always implement proper error handling for transit requests. Dimensional travel is inherently unstable.

Best Practice Example:

try {
  const result = await PTN.initiateTransit(transitRequest);

  if (result.status === "transit_initiated") {
    castle.notifyStaff(`Traveler ${payload.name} in transit`);
    return result.transitId;
  }

} catch (error) {

  if (error.code === 503) {
    // Destination offline - notify traveler
    castle.alert(`Cannot reach ${destination}. Circle may be damaged.`);

  } else if (error.code === 666) {
    // Demonic interference - activate defenses
    castle.shields.raise();
    castle.alert("INFERNAL ACTIVITY DETECTED - Transit aborted");

  } else {
    // Generic error handling
    castle.log.error(`Transit failed: ${error.message}`);
  }
}

Webhook Notifications

Configure webhooks to receive real-time updates about transit status without polling.

Setup

PTN.registerWebhook({
  castleKey: "your-castle-key",
  endpoint: "castle://blackspire/transit-notifications",
  events: [
    "transit.initiated",
    "transit.completed",
    "transit.failed",
    "entity.arriving"
  ]
})

Webhook Payload Example

When a transit completes, you'll receive:

{
  event: "transit.completed",
  transitId: "TRN-9847562",
  timestamp: "2026-01-13T12:45:33Z",
  payload: {
    name: "Aldric the Bold",
    status: "arrived_safely",
    integrity: 100,
    location: "circle-3-north-tower"
  }
}

Note: Webhook endpoints must respond within 5 seconds or they will be considered failed and retried up to 3 times with exponential backoff.

Advanced Features

Scheduled Transits

Schedule future transits for automated courier services or routine deliveries:

PTN.scheduleTransit({
  ...transitRequest,
  scheduledTime: "2026-01-15T09:00:00Z",
  recurring: {
    frequency: "weekly",
    dayOfWeek: "Monday"
  }
})

Cargo Manifests

For bulk transit of goods, use detailed cargo manifests:

payload: {
  type: "cargo",
  containers: [
    {
      id: "CONT-001",
      contents: "enchanted_weapons",
      count: 50,
      weight: "250 lbs",
      magicLevel: "moderate"
    },
    {
      id: "CONT-002",
      contents: "potion_supplies",
      count: 200,
      weight: "150 lbs",
      hazardClass: "volatile"
    }
  ]
}

Emergency Recall

Cancel an in-progress transit and return payload to origin:

PTN.emergencyRecall({
  transitId: "TRN-9847562",
  reason: "hostile_activity_detected",
  authorization: castle.ownerSignature()
})

Testing

Sandbox Environment

The PTN provides a sandbox for testing integrations without risking actual dimensional travel:

Sandbox Endpoint: ptn://sandbox.planar.transit

Sandbox features:

• Simulated transit delays and responses
• Controllable error injection for testing error handling
• No energy costs or rate limits
• Test entities are non-corporeal and cannot interact with physical plane

Test Coordinates

Use these coordinates for development:

• Origin: Sandbox.Realm-Test.CastleAlpha
• Destination: Sandbox.Realm-Test.TowerBeta

Monitoring & Diagnostics

Energy Usage Tracking

Monitor your castle's energy consumption:

const usage = PTN.getEnergyUsage({
  castleKey: "your-key",
  period: "last_30_days"
});

// Returns:
{
  totalTransits: 247,
  totalEnergy: 61750,
  averagePerTransit: 250,
  peakDay: "2025-12-28",
  remainingQuota: 15000
}

Network Status

Check PTN network health before critical transits:

const status = PTN.getNetworkStatus();

// Returns:
{
  status: "operational",
  dimensionalStability: 98,
  averageTransitTime: "42 seconds",
  activeTransits: 1847,
  incidents: []
}

Security Best Practices

1. Validate incoming travelers - Always verify identity before granting castle access
2. Implement allowlists - Restrict which origins can send transits to your castle
3. Monitor for anomalies - Unusual transit patterns may indicate attempted breaches
4. Regular key rotation - Rotate Castle Keys every 90 days minimum
5. Backup transit logs - Maintain records for at least 1 year for security audits

Support & Resources

Documentation: ptn://docs.planar.transit
Status Page: ptn://status.planar.transit
Developer Portal: ptn://developers.planar.transit
Technical Support: Send spell to PTN Node 108 or visit support.planar.transit

Community:

• Wizard's Forum: Discussion and integration examples
• PTN Developer Discord: Real-time help from other castle administrators
• Monthly Office Hours: First Tuesday of each month, 2pm GMT

Changelog

v3.2 (Current)

• Added webhook notification support
• Improved error messages for dimensional instability
• New emergency recall feature
• Enhanced cargo manifest validation

v3.1

• Increased rate limits for Premium tier
• Fixed issue with temporal displacement on recalls
• Added sandbox environment

v3.0

• Major protocol update (breaking changes from v2.x)
• Introduced Castle Key authentication
• Deprecated legacy portal stones