Documentation

Coinos is free and open source software. You can run it on your own server and connect it to your own Bitcoin and Lightning nodes. The code is available for download at https://github.com/coinos

Coinos has a simple REST API that can be used to register accounts and make payments and queries. The following examples show how you can call the API with curl from your command line.

API Base URL

https://coinos.io/api

Auth Token

Sign in to view your auth token here, or get one from the /login endpoint. Save it in a variable called $token to run the examples.

export token=<your auth token>

POST /register

Register a new user account with a username and password

curl "https://coinos.io/api/register" -H "content-type: application/json" -d '{ "user": { "username": "demo", "password": "hunter2" } }'

POST /login

Login to an account to get its auth token

curl "https://coinos.io/api/login" -H "content-type: application/json" -d '{ "username": "demo", "password": "hunter2" }'

POST /invoice

Create an invoice.

Get a lightning invoice to receive funds

curl "https://coinos.io/api/invoice" -H "content-type: application/json" -H "Authorization: Bearer $token" -d '{ "invoice": { "amount": 1000, "type": "lightning" } }'

Get a bitcoin address to receive funds

curl "https://coinos.io/api/invoice" -H "content-type: application/json" -H "Authorization: Bearer $token" -d '{ "invoice": { "amount": 3141, "type": "bitcoin" } }'

Sample response

{ "amount":3141 "tip":0 "type":"bitcoin" "prompt":false "rate":31836.9702667 "hash":"bc1qmhfk9stzffhd9umzmld92vff7zg3mdlh7rvvaj" "text":"bitcoin:bc1qmhfk9stzffhd9umzmld92vff7zg3mdlh7rvvaj?amount=0.00003141" "currency":"CAD" "uid":"a9770421-3f65-11ed-9f57-0242ac2a0004" "received":0 "created":1677537428134 }

You can check the received field to see how much has been paid

Specify a webhook to be called when an invoice is paid

curl "https://coinos.io/api/invoice" -H "content-type: application/json" -H "Authorization: Bearer $token" -d '{ "invoice": { "type": "lightning", "webhook": "https://example.com/payment/received", "secret": "webhooksecret" } }'

GET /invoice/:hash

Fetch an invoice by passing a bitcoin address or lightning payment hash

curl "https://coinos.io/api/invoice/bc1qmhfk9stzffhd9umzmld92vff7zg3mdlh7rvvaj" -H "content-type: application/json"'

POST /payments

Send a lightning payment

curl "https://coinos.io/api/payments" -H "content-type: application/json" -H "Authorization: Bearer $token" -d '{ "payreq": "lnbc1pj94d8fsp5n77k340ps4m9jn7kp8he8yynpddvurv6mcsrrqpnq5l2jxdxzlwqpp5m96pqhc5nrlk8cqsu9ufdxxa43sarp8vwf9egvm2pg9nl0zu9r8qdq2vdhkjmn0wvxqztgcqpjrzjqwhmav82kntsppmkp8jp4vg4h9nns78tsy8mg7ve4lq5txrkp0h56zlarvqqdtcqqsqqqqqqqqqqp6cq9q9qyysgqzxlypywzphyujm3ga5j5csfcmqvlnae0fgnvymkaaw94eeg7py5rqzysyjkr3ev2snq63qpsc69vf54adkd0szvmvwt5cuadjnuy95sq4xfa40" }'

Send an internal payment to another user

HASH=$(curl "https://coinos.io/api/invoice" -H "content-type: application/json" -H "Authorization: Bearer $token" -d '{ "invoice": { "amount": 1000, "type": "lightning" }, "user": { "username": "alice" } }' | jq -r '.hash'); curl "https://coinos.io/api/payments" -H "content-type: application/json" -H "Authorization: Bearer $token" -d '{ "amount": 5000, "hash": $HASH }'

POST /bitcoin/send

Send a bitcoin payment

curl "https://coinos.io/api/bitcoin/send" -H "content-type: application/json" -H "Authorization: Bearer $token" -d '{ "amount": 5000, "address": "bc1q3unh97w4rmelflrm2hvdwz37d8kray3vn4d5ca" }'

GET /payments

Get all payments sent or received by the current user

curl "https://coinos.io/api/payments" -H "content-type: application/json" -H "Authorization: Bearer $token"