API
The ECO carbon retirement API simplifies interacting with on-chain carbon markets by facilitating seamless, atomic purchase and retirement of a growing number of supported tokenized carbon offsets.
To complete the atomic retirement of an arbitrary amount of carbon, you must implement the following programmatic lifecycle:
- 1.
- 2.
- 3.
To programmatically retire carbon using the ECO API, users first create a
RetireCarbonRequest.post
https://api.providepayments.com/api/v1
/retire_carbon_requests
Parameterize a retire carbon request for signature and broadcast
After creating a parameterized request that can be used to retire the specified amount of carbon, the transaction needs to be signed. We designed the API in this manner to ensure users can enable self-custody in their implementations. The signature over the transaction data returned by the parameterize request provides flexibility for (i) broadcasting the transaction and bearing the network transaction costs or (ii) leveraging the Managed Transactions API to broadcast the transaction while maintaining the ability to verify the original signer (e.g., by using
ecrecover).An integrated code sample will be provided here shortly. You can see how we leverage the PRVD Vault to sign transactions for EVM-based networks here.
This final step in the process to programmatically retire carbon enables flexibility in systems and applications that would otherwise struggle to assemble, encode and broadcast transactions to the targeted network. The broadcast API accepts the unsigned
data as returned by the Parameterize call and a hex-encoded signature.The following code demonstrates how to broadcast parameterized and signed ECO transactions:
curl -i -XPOST \
-H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7fSwiZXhwIjpudWxsLCJpYXQiOjE1NTk4Nzg1NzQsImp0aSI6IjYzYTJkY2QzLWI5OTgtNDZjNC1hNzFkLTQ5MjU4YTBhYmEyMyIsInN1YiI6ImFwcGxpY2F0aW9uOmNiMjAzN2Y3LTc5ZmMtNDBmNC05NzIwLWFkYTYzNmRhNDE4MyJ9.NQLm__LbMWor-9GMG0LPcH4yQIbu9Uw70kJfRt1KP64' \
-H 'Content-Type: application/json' \
https://api.providepayments.com/api/v1/eco/retire_carbon_requests/90638fe9-1433-4a09-89c6-4585ffde8ddf/retire \
-d '{
"data": "c8b9467e0000000000000000000000002791bca1f2de4661ed88a30c99a7a9449aa841740000000000000000000000002f800db0fdb5223b3c3f354886d907a671414a7f000000000000000000000000225b28c1a77fd4493196db19c538a44801243537000000000000000000000000000000000000000000000000000000000000343a00000000000000000000000000000000000000000000000000000000000001200000000000000000000000001480320db0aa1bbef15f847981e28776e7d2c442000000000000000000000000000000000000000000000000000000000000016000000000000000000000000000000000000000000000000000000000000001a00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000750726f7669646500000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000750726f7669646500000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000003048656c6c6f2066726f6d207468652050726f766964652045434f20636172626f6e207265746972656d656e742041504900000000000000000000000000000000",
"signature": "4bf45a05a078d2fbd18996ce50f001d3841121b86e6026edff83b5b2aac949f74588378d001687b1b5c85460851952fabb93778c681a4a209a9cf5f25e94823400",
"signer": "0xc9327CB2982cb0B7922670DeF04a11aE5A4E0479"
}'
The broadcast method provides guarantees around atomicity and double-spend protection, ensuring each parameterized carbon retirement request is only executed once. Subsequent attempts to broadcast the same request will fail with a
422 status code. Here is an example response to an API call attempting to retire a parameterized transaction:{
"message": "retire carbon request has already been broadcast; tx hash: 584205679a00025e927fc24ef0a3a5e726017392395e7d027b3936d7e644d0ca"
}
You can retrieve details related to an existing
RetireCarbonRequest, including links to generated certificates and verifiable credentials, if applicable.Note that the returned
RetireCarbonRequest details will contain a non-null tx_hash and cardinality if the request has been successfully broadcast to the network for settlement. The returned cardinality represents the serial position of the completed carbon retirement for the provider for the associated beneficiary_address.Similarly, the
certificate_href and verifiable_credentials_href fields will only be included in the response if the underlying RetireCarbonRequest has been successfully retired and the provider supports those resources on the settlement network.Some
provider implementations may support an additional certificate_href_alt field.Last modified 2mo ago