Payouts

Use the Payouts API to send royalties, share revenues or fractionalize earnings among thousands of payees in realtime.

Create a payout

POST /v1

Creates a payout to a smart contract recipient which contains a set of payees. Since payees are members of a smart contract, the caller does not need to specify individual payees. Instead, by specifying a smart contract ID, all payees within the contract are paid, even as this set of payees changes over time.

cURL

curl -v -X POST 'https://share-ddn.formless.xyz/v1' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $API_KEY" \
-d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "payouts",
    "params": {
        "recipient_type": "smart_contract",
        "recipient_id": "a4680ff6-715b-4101-8ff4-5a34f32ee3f9",
        "amount": {
            "value" : 5.00,
            "currency" : "USD"
        }
    }
}'

The recipient_id value, which is the ID of the receiving smart contract, is the result of creating a community splits smart contract using the SHARE App. As the payer, you would not create this contract. Instead, the recipient provides you with this value as the ID of the entity with which they expect to receive payments.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Body

Name	Type	Description
idempotency_key	string	Optional. For idempotent requests, supply a unique identifier here. Repeated calls to the endpoint with the same key value are guaranteed to execute only once.
recipient_type	string	Only smart_contract type is supported. This indicates that the payout receiver is a contract containing a set of payees.
recipient_id	string	The ID of the recipient. For type smart_contract, this is the contract_id value returned at contract upload time within the SHARE App.
amount	object	A dictionary with keys value and currency. Only USD is supported at this time.

Response

200

{
    "jsonrpc": "2.0",
    "id": "1",
    "result": {
        "batch_id": "02473ddd-c09c-475f-a120-7d771b6ae43e",
        "status": "pending",
        "message": "Your payouts are being processed and you will receive an email upon completion."
    }
}

Show payout details

POST /v1

Shows the current status of a payout batch that has been started.

cURL

curl -v -X POST 'https://share-ddn.formless.xyz/v1' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $API_KEY" \
--data '{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "payouts",
    "params": {
        "batch_id" : "89de4f6d-a8e5-4808-9c29-ebac29dec4cb"
    }
}'

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Body

Name	Type	Description
batch_id	string	The ID of the payout batch.

Response

200

{
    "jsonrpc": "2.0",
    "id": "1",
    "result": {
        "details": {
            "contract_address": "0x0aa152EF5D504612dEE5ec6146bD8B83bEbC9187",
            "network_id": 137,
            "amount_usd": 1.0
        },
        "submitter": "00000003XG",
        "payout_batch_id": "89de4f6d-a8e5-4808-9c29-ebac29dec4cb",
        "timestamp": {
            "_seconds": 1729567778,
            "_nanoseconds": 739000000
        },
        "status": "complete"
    }
}