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 -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

NameValue

Content-Type

application/json

Authorization

Bearer <token>

Body

NameTypeDescription

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

{
    "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 -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

NameValue

Content-Type

application/json

Authorization

Bearer <token>

Body

NameTypeDescription

batch_id

string

The ID of the payout batch.

Response

{
    "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"
    }
}

Last updated