Twetch API

Fetching payees / outputs

To have posts display properly on Twetch, posting fees and payments to users must map properly to Bitcoin outputs (P2PKH scripts).

This can be done manually with calculations done locally, but this is error-prone and may not display on Twetch if done improperly, wasting satoshis.

Twetch has an endpoint where an array adhering to the above examples can be posted, returning the necessary outputs to be included in the Bitcoin transaction.

HTTP POST request:

URL: https://api.twetch.app/v1/payees

Headers: {
    Authorization: ‘Bearer <twetch_authorization_token>’
}

Body: {
    clientIdentifier: <your_client_identifier>,
    action: ‘<twetch_action>’,
    args: ‘array_of_fields’
}

Response:

{
    errors: [],
    invoice: '42560230-ca7c-44d6-aebc-371be1d3daa1',
    payees: [
    {
        to: '1Twetcht1cTUxpdDoX5HQRpoXeuupAdyf',
        amount: 0.00010711,
        currency: 'BSV',
        user_id: '0',
        types: [Array]
    },
    {
        to: '1baroWNpX7taBXkUdMwVZqot9pgxCjJ4U',
        amount: 0.0000119,
        currency: 'BSV',
        user_id: '145',
        types: [Array]
    }],
    estimate: 0.0199996305,
    exchangeRate: 168.05
}

Payees represent the Bitcoin outputs that must be present in the Bitcoin transaction to be a valid Twetch.

Additionally, estimate returns the approximate USD cost of the Twetch, and exchangeRate is the USD exchange rate at the time of the API call.

Invoice

An invoice value is returned from the payees endpoint.

Example:

42560230-ca7c-44d6-aebc-371be1d3daa1

Populate this value in the invoice field of the ABI action.

Customize interaction amounts

In your Twetch implementation, satoshi amounts can be added to customize mentions, like, branch amounts, etc.

Upon receiving a /payees response, increase the satoshi amounts to do the following for example:

• Implement 25 cent likes

• Implement 5 cent branches

• Implement 1 cent mentions

Note that amounts can only be increased, as the minimums are enforced by Twetch in the /payees response.

Client identifiers

Obtain a client identifier for your implementation at https://twetch.app/developer

When specifying this value in the /payees POST request, the Twetch fee will be discounted at 10%, and the 10% will be refunded in an additional output to the developer’s address in the response.

Publishing a Twetch transaction

Broadcasting the transaction to the Bitcoin network is not enough to be a valid Twetch transaction.

Twetch has a publish endpoint where data can be posted and broadcasted so that if valid, the data will immediately display on Twetch.

HTTP POST request:

URL: https://api.twetch.app/v1/publish

Headers: {
    Authorization: ‘Bearer <twetch_authorization_token>’
}
Body: {
    signed_raw_tx: <raw_bitcoin_transaction_hex>
    action: ‘<twetch_action>’,
    broadcast: <true_or_false>,
    invoice: <invoice_of_twetch>,
    payParams: <JSON_object_of_additional_parameters>
}

Setting broadcast to true will also broadcast the raw transaction to the Bitcoin network. Setting to false will only send the data to the Twetch publish endpoint.

payParams example:

payParams: {
    tweetFromTwetch:  false,
    hideTweetFromTwetchLink:  false
}

• tweetFromTwetch – if twetch will also post to Twitter

• hideTweetFromTwetchLink – if tweetFromTwetch = true, then set to true to hide the Twetch unfurl on the Tweet

Response:

{
    errors: <array_of_errors>
    published: <true_or_false>
    broadcasted: <true_or_false>
    txid: <transaction_id>
    abi: <BSVABI_object>
}

Example BSVABI object:

BSVABI {
    network: 'mainnet',
    options: { network: 'mainnet', action: 'twetch/post@0.0.1' },
    abi: {
    name: 'Twetch',
    hostname: 'twetch.com',
    endpoint: 'api.twetch.app/v1/publish',
    actions: [Object]
    },
    args: [
    '19HxigV4QyBv3tHpQVcUEQyq1pzZVdoAut',
    'testundefinedundefined',
    'text/plain',
    'text',
    'twetch.txt',
    '|',
    '1PuQa7K62MiKCtssSLKy1kh56WWU7MtUR5',
    'SET',
    'twdata_json',
    'null',
    'url',
    'null',
    'comment',
    'null',
    'mb_user',
    'null',
    'reply',
    'null',
    'type',
    'post',
    'timestamp',
    'null',
    'app',
    'twetch',
    'invoice',
    'ea11c355-a91e-40fd-b2cd-20594aacd7c2',
    '|',
    '15PciHG22SNLQJXMoSUaWVi7WSqc7hCfva',
    'BITCOIN_ECDSA',
    '1Kbfq4pGDBuoyMth9GkdnP5UPDqcSeCZ3Q',
    'H1FRK7cgEwB0bUOs3z1rz8ikhNKWrPjsYBWLZogltTTXAoxceJt8p+H8cYTbT06cnH95Nf3YwCSan/cmCRlMNds='
    ],
    actionName: 'twetch/post@0.0.1',
    action: {
        type: 'post',
        contentIndex: 1,
        contentTypeIndex: 2,
        encodingIndex: 3,
        filenameIndex: 4,
        args: [Array]
    }
}