​
Getting Started: P2P Transaction with Fee

This guide walks you through creating a ledger, accounts, and assets, then performing a P2P transaction with a fee using our API.

​
Prerequisites

  • Replace {your_org_id} and {your_api_key} with your actual credentials.
  • Set the API base URL: 
    API_URL="https://api.sandbox.nxos.io/v1"

​
1. Create a Ledger

A ledger is the foundation of your financial system in our API. It acts as a container for all your accounts, assets, and transactions. Creating a ledger is therefore the first step in setting up your financial operations.

# Create Ledger and extract ledger_id
LEDGER_ID=$(curl -X POST "$API_URL/ledger" \
  -H "Authorization: Basic $(echo -n $your_org_id:$your_api_key | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "ledger_ref": "p2p_demo"
  }' | jq -r '.ledger_id')

echo "Ledger ID: $LEDGER_ID"

The ledger_id returned in the response is crucial for subsequent API calls, as it’s currently required to identify the ledger in operations where the ledger reference isn’t sufficient; we’re working on updating our backend to allow using ledger references consistently across all endpoints.

​
2. Create Asset

Assets represent the different types of value that can be transferred within your ledger. In this example, we’re creating a USD asset to represent US Dollars. Defining assets allows you to work with multiple currencies or value types within your financial system.

curl -X POST "$API_URL/ledger/$LEDGER_ID/asset" \
  -H "Authorization: Basic $(echo -n $your_org_id:$your_api_key | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_code": "USD",
    "name": "US Dollar",
    "scale": 2
  }'

​
3. Create Accounts

Accounts are the individual entities within your ledger that can hold assets and participate in transactions. For this P2P transaction example, we’re creating three accounts: a sender, a receiver, and a revenue account for fees. These accounts will allow us to demonstrate a basic peer-to-peer transfer with a transaction fee.

Note the min_balance setting for the sender account. We’ve set it to a negative value (-10000000, representing -$100,000.00) to allow for outgoing transfers. This is crucial because the min_balance for accounts typically defaults to 0, which would prevent sending funds if the account starts with a zero balance. By setting a negative min_balance, we ensure the sender account can initiate transfers even without a pre-existing positive balance. This setup is common for demo environments or systems where you want to allow initial outgoing transactions without prefunding the account.

# Sender Account
curl -X POST "$API_URL/ledger/$LEDGER_ID/account" \
  -H "Authorization: Basic $(echo -n $your_org_id:$your_api_key | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "account_ref": "sender",
    "default_asset_code": "USD",
    "enabled_assets": [{
        "asset_code": "USD",
        "min_balance": "-10000000" 
    }]
  }'

# Receiver Account
curl -X POST "$API_URL/ledger/$LEDGER_ID/account" \
  -H "Authorization: Basic $(echo -n $your_org_id:$your_api_key | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "account_ref": "receiver",
    "default_asset_code": "USD"
  }'

# Revenue Account
curl -X POST "$API_URL/ledger/$LEDGER_ID/account" \
  -H "Authorization: Basic $(echo -n $your_org_id:$your_api_key | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "account_ref": "revenue",
    "default_asset_code": "USD"
  }'

​
4. Perform P2P Transaction

The P2P transaction is where we bring together all the elements we’ve set up. This step involves creating a transaction with two asset moves: one from the sender to the receiver, and another for the fee from the receiver to the revenue account. This demonstrates how complex financial operations can be modeled using simple building blocks in our API.

curl -X POST "$API_URL/ledger/$LEDGER_ID/transaction" \
  -H "Authorization: Basic $(echo -n $your_org_id:$your_api_key | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_ref": "p2p_tx_001",
    "asset_moves": [
      {
        "asset_move_ref": "sender_to_receiver",
        "source_account": {"ref": "sender"},
        "destination_account": {"ref": "receiver"},
        "asset_code": "USD",
        "amount": "50000",
        "type": "TRANSFER"
      },
      {
        "asset_move_ref": "receiver_fee",
        "source_account": {"ref": "receiver"},
        "destination_account": {"ref": "revenue"},
        "asset_code": "USD",
        "amount": "100",
        "type": "FEE"
      }
    ]
  }'

Note: Amount is in cents (50000 = 500.00USD, 100 = 1.00USD).

​
5. Verify Balances

​
Expected Balances

After executing the P2P transaction, you should observe the following changes in account balances:

  • Sender’s Account: The balance should decrease by 500.00USD. If the initial balance was 0USD, the new balance would be -500.00USD.
# Check Sender's Balance
curl -X GET "$API_URL/ledger/$LEDGER_ID/account/ref:sender/balance/USD" \
  -H "Authorization: Basic $(echo -n $your_org_id:$your_api_key | base64)"
  • Receiver’s Account: The balance should increase by 499.00USD, the transferred amount minus the fee. If the initial balance was 0.00USD, the new balance would be 499.00USD.
# Check Receiver's Balance
curl -X GET "$API_URL/ledger/$LEDGER_ID/account/ref:receiver/balance/USD" \
  -H "Authorization: Basic $(echo -n $your_org_id:$your_api_key | base64)"
  • Revenue Account: The balance should increase by 1.00USD, the fee amount. If the initial balance was 0.00, the new balance would be 1.00USD.
# Check Revenue Account's Balance
curl -X GET "$API_URL/ledger/$LEDGER_ID/account/ref:revenue/balance/USD" \
  -H "Authorization: Basic $(echo -n $your_org_id:$your_api_key | base64)"

​
Conclusion

Congratulations! You’ve just created your first P2P transaction with a fee using our API. By following these steps, you’ve learned how to set up a ledger, create assets and accounts, execute a multi-step transaction, and verify the results through balance checks. This foundational knowledge sets the stage for more complex financial operations and integrations. Feel free to experiment with different transaction types and explore more of our API’s capabilities to build robust financial systems for your applications.

Resource keysTransfer