Getting Started with SplitRoute API

This guide will help you get started with the SplitRoute API for processing Nano cryptocurrency payments.

• Use our AI Context for fastest results

Prerequisites

Before you begin, you'll need:

1. A basic understanding of REST APIs
2. A development environment with your preferred programming language
3. A way to make HTTP requests (e.g., cURL, Postman, or a HTTP client library)

Step 1: Register for an API Key

First, you need to register for a free API key:

BASH
1
curl -X POST https://api.splitroute.com/api/v1/api-keys/register \
2
  -H "Content-Type: application/json" \
3
  -d '{"email": "[email protected]" , "name": "your.key.name" }'

You'll receive a response with your API key:

JSON
1
{
2
    "key":  "SR_SECRET_d069a1d9a53ff1a77296d0223eb000ac",
3
    "name":  "your.key.name",
4
    "tier":  "FREE",
5
    "status":  "ACTIVE",
6
    "rate_limit_per_hour":  1000,
7
    "remaining_invoices":  -1,
8
    "created_at":  "2025-03-25T19:06:33.107954Z",
9
    "expires_at":  "2124-03-01T19:06:33.107943Z",
10
    "is_active":  true
11
}

Step 2: Create Your First Invoice

Now you can create your first invoice:

BASH
1
curl -X POST https://api.splitroute.com/api/v1/invoices \
2
  -H "Content-Type: application/json" \
3
  -H "X-API-Key: your_api_key" \
4
  -d '{
5
    "nominal_amount": 10,
6
    "nominal_currency": "EUR",
7
    "destinations": [
8
      {
9
        "account": "nano_123...",
10
        "primary": true
11
      }
12
    ],
13
    "reference": "my-first-invoice"
14
  }'

You'll receive a response with the invoice details:

JSON
1
{
2
  "invoice_id":  "INV_2025_03_d1447da3e9ff90cd3822",
3
  "secret_id":  "INV_SECRET_02122c244c4a33453dbc4",
4
  "account_address":  "nano_1payment_address",
5
  "nominal_currency":  "EUR",
6
  "formatted_currency":  "XNO",
7
  "required":  {
8
    "unit_amount":  "10020763000000000000000000000000",
9
    "formatted_amount":  "10.020763",
10
    "nominal_amount":  "10"
11
  },
12
  "received":  {
13
    "unit_amount":  "0",
14
    "formatted_amount":  "0",
15
    "nominal_amount":  "0"
16
  },
17
  "exchange_rate":  "0.997928",
18
  "expires_at":  "2025-03-25T20:24:03.090148Z",
19
  "destinations":  [
20
    {
21
      "type":  "primary",
22
      "account":  "nano_123...",
23
      "unit_amount":  "9970659185000000000000000000000",
24
      "formatted_amount":  "9.970659185",
25
      "nominal_amount":  "9.950"
26
    },
27
    {
28
      "type":  "service_fee",
29
      "account":  "nano_1nowapi9w5hx3d4wb9swa88p8dd7tsf8xsycob3owy855sai6j9zuyztjzdj",
30
      "unit_amount":  "50103815000000000000000000000",
31
      "formatted_amount":  "0.050103815",
32
      "nominal_amount":  "0.050",
33
      "description":  "Service fee"
34
    }
35
  ],
36
  "service_fee_rate":  "0.50",
37
  "show_qr":  false,
38
  "is_simulation":  false,
39
  "is_pending":  false,
40
  "is_paid":  false,
41
  "is_forwarded":  false,
42
  "is_done":  false,
43
  "is_expired":  false,
44
  "is_overpaid":  false,
45
  "uri_rfc_8905":  "payto:nano/nano_1payment_address?amount=10020763000000000000000000000000",
46
  "uri_nano":  "nano:nano_1payment_address?amount=10020763000000000000000000000000"
47
}

Step 3: Monitor Payment Status

You can monitor the payment status in two ways:

Option 1: WebSocket

See here for further details

Connect to the WebSocket to receive real-time updates:

JAVASCRIPT
1
const invoiceId = 'INV_2025_03_d1447da3e9ff90cd3822';
2
const socket = new WebSocket(`wss://api.splitroute.com/api/v1/ws/invoices/${invoiceId}`);
3
4
socket.onopen = function(e) {
5
  console.log('Connected to WebSocket');
6
};
7
8
socket.onmessage = function(event) {
9
  const message = JSON.parse(event.data);
10
  console.log(`Received message type: ${message.message_type}, category: ${message.category}`);
11
  
12
  // Check for invoice payment
13
  if (message.payload.event_type === 'invoice.paid') {
14
    console.log('Invoice has been paid!');
15
    console.log(`Received amount (formatted): ${message.payload.formatted_amount}`);
16
    // Update your UI or take other actions
17
  }
18
  
19
  // Check for invoice completion
20
  if (message.category === 'completed') {
21
    console.log('Invoice processing completed');
22
    // Close the connection as we're done
23
    socket.close();
24
  }
25
};
26
27
socket.onclose = function(event) {
28
  if (event.wasClean) {
29
    console.log(`Connection closed cleanly, code=${event.code} reason=${event.reason}`);
30
  } else {
31
    console.log('Connection died');
32
  }
33
};
34
35
socket.onerror = function(error) {
36
  console.log(`WebSocket error: ${error.message}`);
37
};

Option 2: Webhook

See here for further details

Alternatively, you can set up a webhook to receive notifications:

BASH
1
curl -X POST https://api.splitroute.com/api/v1/invoices \
2
  -H "Content-Type: application/json" \
3
  -H "X-API-Key: your_api_key" \
4
  -d '{
5
    "nominal_amount": 10.00,
6
    "nominal_currency": "USD",
7
    "destinations": [
8
      {
9
        "account": "nano_1abc...",
10
        "primary": true
11
      }
12
    ],
13
    "webhook_url": "https://your-server.com/webhook",
14
    "webhook_secret": "your_webhook_secret",
15
    "reference": "invoice-with-webhook"
16
  }'

Your webhook endpoint will receive notifications about invoice status changes.

Step 4: Check Invoice Status

You can also check the invoice status manually:

BASH
1
curl -X GET https://api.splitroute.com/api/v1/invoices/INV_2025_03_d1447da3e9ff90cd3822

Step 5: Handle Payment Completion

Once the payment is complete, you'll receive a notification via WebSocket or webhook. You can then update your system to reflect the payment status.

Invoice Lifecycle

The typical lifecycle of an invoice follows these steps:

1. Created: Invoice is created and ready to receive payment (all status flags are false initially)
2. Pending: Invoice has received a partial payment (is_pending = true)
3. Paid: Full payment has been received and confirmed (is_paid = true)
4. Forwarded: Funds have been distributed to the specified destinations (is_forwarded = true)
5. Done: Invoice processing is complete (is_done = true)
6. Expired: Invoice has expired without being fully paid (is_expired = true, alternative end state)

WebSocket and webhook notifications will inform you as the invoice progresses through these states.

Next Steps

Now that you've created your first invoice and monitored its payment status, you can explore more advanced features:

1. Split payments among multiple recipients
2. Set up advanced webhook handling
3. Implement error handling and retries
4. Upgrade to a paid API key tier

Example Implementation

Here's a complete example in JavaScript:

JAVASCRIPT
1
// Create an invoice
2
async function createInvoice() {
3
  const response = await fetch('https://api.splitroute.com/api/v1/invoices', {
4
    method: 'POST',
5
    headers: {
6
      'Content-Type': 'application/json',
7
      'X-API-Key': 'your_api_key'
8
    },
9
    body: JSON.stringify({
10
      nominal_amount: 10.00,
11
      nominal_currency: 'USD',
12
      destinations: [
13
        {
14
          account: 'nano_1abc...',
15
          primary: true
16
        }
17
      ],
18
      reference: 'example-invoice'
19
    })
20
  });
21
  
22
  const invoice = await response.json();
23
  console.log('Invoice created:', invoice);
24
  
25
  // Connect to WebSocket for real-time updates
26
  const socket = new WebSocket(`wss://api.splitroute.com/api/v1/ws/invoices/${invoice.invoice_id}`);
27
  
28
  socket.onmessage = function(event) {
29
    const message = JSON.parse(event.data);
30
    
31
    // Handle different event types
32
    switch(message.payload.event_type) {
33
      case 'invoice.paid':
34
        console.log('Invoice has been paid!');
35
        console.log(`Amount received: ${message.payload.formatted_amount}`);
36
        // Update your system to reflect payment
37
        break;
38
      case 'invoice.forwarded':
39
        console.log('Payment has been forwarded to destinations');
40
        break;
41
      case 'invoice.done':
42
        console.log('Invoice processing is complete');
43
        socket.close();
44
        break;
45
      case 'invoice.expired':
46
        console.log('Invoice has expired without full payment');
47
        socket.close();
48
        break;
49
    }
50
  };
51
  
52
  return invoice;
53
}
54
55
// Call the function
56
createInvoice().catch(error => console.error('Error:', error));