Agreements

Agreement management operations

Create a new agreement

post

Create a new pre-approval agreement between the payer and receiver, including one or more milestones. The agreement becomes valid once both parties approve it.

Authorizations

x-api-idx-api-key

x-api-idstringRequired

Body

application/json

idstringRequired

ID of the agreement

Example: agreement_123

payerUserIdstringRequired

ID of the user paying for milestones

Example: 123

receiverUserIdstringRequired

ID of the user paid for milestones

Example: 123

platformFeePercentagenumberRequired

Platform fee percentage (as a fraction, e.g. 0.01 for 1%)

Example: 0.01

organizationFeePercentagenumberRequired

Organization fee percentage (as a fraction, e.g. 0.01 for 1%)

Example: 0.01

Responses

200

Agreement created

application/json

400

Bad request

401

Unauthorized

404

Not found

500

Internal server error

post

/v1/agreements

HTTPcURLJavaScriptPython

POST /v1/agreements HTTP/1.1
Host: staging.api.portafino.appliedblockchain.dev
x-api-id: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 187

{
  "milestones": [
    {
      "id": "milestone_123",
      "amount": 100,
      "tax": 20
    }
  ],
  "id": "agreement_123",
  "payerUserId": "123",
  "receiverUserId": "123",
  "platformFeePercentage": 0.01,
  "organizationFeePercentage": 0.01
}

{
  "id": "agreement_123",
  "status": "pending",
  "payerUserId": "123",
  "payerAddress": "0x1234567890abcdef",
  "receiverUserId": "123",
  "receiverAddress": "0x1234567890abcdef",
  "platformFeePercentage": 0.01,
  "organizationFeePercentage": 0.01,
  "milestones": [
    {
      "id": "milestone_123",
      "address": "0x1234567890abcdef",
      "amount": 100,
      "tax": 20,
      "fundedBalance": 100,
      "status": "pending",
      "fundedAt": "2021-01-01T00:00:00.000Z",
      "approvedByReceiverAt": "2021-01-01T00:00:00.000Z",
      "deliveryFileUri": "https://example.com/delivery.pdf",
      "deliveryFileHash": "0x1234567890abcdef",
      "agreementId": "agreement_123"
    }
  ],
  "agreementFileUri": "https://example.com/agreement.pdf",
  "agreementFileHash": "0x1234567890abcdef"
}

Get agreement by id

get

Get an agreement by id.

Authorizations

x-api-idx-api-key

x-api-idstringRequired

Path parameters

idstringRequired

ID of the agreement

Example: agreement_123

Responses

200

Agreement retrieved

application/json

400

Bad request

401

Unauthorized

404

Not found

500

Internal server error

get

/v1/agreements/{id}

HTTPcURLJavaScriptPython

GET /v1/agreements/{id} HTTP/1.1
Host: staging.api.portafino.appliedblockchain.dev
x-api-id: YOUR_API_KEY
Accept: */*

{
  "id": "agreement_123",
  "status": "pending",
  "payerUserId": "123",
  "payerAddress": "0x1234567890abcdef",
  "receiverUserId": "123",
  "receiverAddress": "0x1234567890abcdef",
  "platformFeePercentage": 0.01,
  "organizationFeePercentage": 0.01,
  "milestones": [
    {
      "id": "milestone_123",
      "address": "0x1234567890abcdef",
      "amount": 100,
      "tax": 20,
      "fundedBalance": 100,
      "status": "pending",
      "fundedAt": "2021-01-01T00:00:00.000Z",
      "approvedByReceiverAt": "2021-01-01T00:00:00.000Z",
      "deliveryFileUri": "https://example.com/delivery.pdf",
      "deliveryFileHash": "0x1234567890abcdef",
      "agreementId": "agreement_123"
    }
  ],
  "agreementFileUri": "https://example.com/agreement.pdf",
  "agreementFileHash": "0x1234567890abcdef"
}

Add milestones to an agreement

post

Add pre-approval milestone(s) to an existing agreement.

Authorizations

x-api-idx-api-key

x-api-idstringRequired

Body

application/json

idstringRequired

ID of the agreement

Example: agreement_123

Responses

200

Milestone added

application/json

400

Bad request

401

Unauthorized

404

Not found

500

Internal server error

post

/v1/agreements/milestones

HTTPcURLJavaScriptPython

POST /v1/agreements/milestones HTTP/1.1
Host: staging.api.portafino.appliedblockchain.dev
x-api-id: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 82

{
  "id": "agreement_123",
  "milestones": [
    {
      "id": "milestone_123",
      "amount": 100,
      "tax": 20
    }
  ]
}

{
  "id": "agreement_123",
  "status": "pending",
  "payerUserId": "123",
  "payerAddress": "0x1234567890abcdef",
  "receiverUserId": "123",
  "receiverAddress": "0x1234567890abcdef",
  "platformFeePercentage": 0.01,
  "organizationFeePercentage": 0.01,
  "milestones": [
    {
      "id": "milestone_123",
      "address": "0x1234567890abcdef",
      "amount": 100,
      "tax": 20,
      "fundedBalance": 100,
      "status": "pending",
      "fundedAt": "2021-01-01T00:00:00.000Z",
      "approvedByReceiverAt": "2021-01-01T00:00:00.000Z",
      "deliveryFileUri": "https://example.com/delivery.pdf",
      "deliveryFileHash": "0x1234567890abcdef",
      "agreementId": "agreement_123"
    }
  ],
  "agreementFileUri": "https://example.com/agreement.pdf",
  "agreementFileHash": "0x1234567890abcdef"
}

(Coming soon) Updates existing approval milestones to pre-approval status

patch

(Coming soon) Updates existing approval milestones to pre-approval status (with agreement and funds distribution).

Authorizations

x-api-idx-api-key

x-api-idstringRequired

Path parameters

idanyRequired

ID of the agreement

Example: agreement_123

Body

application/json

Responses

200

Milestone updated

application/json

400

Bad request

401

Unauthorized

404

Not found

500

Internal server error

501

Not implemented

patch

/v1/agreements/{id}/milestones

HTTPcURLJavaScriptPython

PATCH /v1/agreements/{id}/milestones HTTP/1.1
Host: staging.api.portafino.appliedblockchain.dev
x-api-id: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 60

{
  "milestones": [
    {
      "id": "milestone_123",
      "name": "Milestone 1"
    }
  ]
}

{
  "id": "agreement_123",
  "status": "pending",
  "payerUserId": "123",
  "payerAddress": "0x1234567890abcdef",
  "receiverUserId": "123",
  "receiverAddress": "0x1234567890abcdef",
  "platformFeePercentage": 0.01,
  "organizationFeePercentage": 0.01,
  "milestones": [
    {
      "id": "milestone_123",
      "address": "0x1234567890abcdef",
      "amount": 100,
      "tax": 20,
      "fundedBalance": 100,
      "status": "pending",
      "fundedAt": "2021-01-01T00:00:00.000Z",
      "approvedByReceiverAt": "2021-01-01T00:00:00.000Z",
      "deliveryFileUri": "https://example.com/delivery.pdf",
      "deliveryFileHash": "0x1234567890abcdef",
      "agreementId": "agreement_123"
    }
  ],
  "agreementFileUri": "https://example.com/agreement.pdf",
  "agreementFileHash": "0x1234567890abcdef"
}

Cancel an agreement

post

Cancel a pending agreement before any milestones have been approved.

Authorizations

x-api-idx-api-key

x-api-idstringRequired

Path parameters

idstringRequired

ID of the agreement

Example: agreement_123

Responses

200

Agreement cancelled

application/json

400

Bad request

401

Unauthorized

404

Not found

500

Internal server error

post

/v1/agreements/{id}/cancel

HTTPcURLJavaScriptPython

POST /v1/agreements/{id}/cancel HTTP/1.1
Host: staging.api.portafino.appliedblockchain.dev
x-api-id: YOUR_API_KEY
Accept: */*

{
  "id": "agreement_123",
  "status": "pending",
  "payerUserId": "123",
  "payerAddress": "0x1234567890abcdef",
  "receiverUserId": "123",
  "receiverAddress": "0x1234567890abcdef",
  "platformFeePercentage": 0.01,
  "organizationFeePercentage": 0.01,
  "milestones": [
    {
      "id": "milestone_123",
      "address": "0x1234567890abcdef",
      "amount": 100,
      "tax": 20,
      "fundedBalance": 100,
      "status": "pending",
      "fundedAt": "2021-01-01T00:00:00.000Z",
      "approvedByReceiverAt": "2021-01-01T00:00:00.000Z",
      "deliveryFileUri": "https://example.com/delivery.pdf",
      "deliveryFileHash": "0x1234567890abcdef",
      "agreementId": "agreement_123"
    }
  ],
  "agreementFileUri": "https://example.com/agreement.pdf",
  "agreementFileHash": "0x1234567890abcdef"
}

Cancel a milestone

post

Cancel a pending milestone before escrow deployment.

Authorizations

x-api-idx-api-key

x-api-idstringRequired

Path parameters

idstringRequired

External ID of the agreement

Example: agreement_123

milestoneIdstringRequired

External ID of the milestone

Example: milestone_123

Responses

200

Milestone cancelled

application/json

400

Bad request

401

Unauthorized

404

Not found

500

Internal server error

post

/v1/agreements/{id}/milestones/{milestoneId}/cancel

HTTPcURLJavaScriptPython

POST /v1/agreements/{id}/milestones/{milestoneId}/cancel HTTP/1.1
Host: staging.api.portafino.appliedblockchain.dev
x-api-id: YOUR_API_KEY
Accept: */*

{
  "id": "milestone_123",
  "address": "0x1234567890abcdef",
  "amount": 100,
  "tax": 20,
  "fundedBalance": 100,
  "status": "pending",
  "fundedAt": "2021-01-01T00:00:00.000Z",
  "approvedByReceiverAt": "2021-01-01T00:00:00.000Z",
  "deliveryFileUri": "https://example.com/delivery.pdf",
  "deliveryFileHash": "0x1234567890abcdef",
  "agreementId": "agreement_123"
}